For example, if you have two fields, both with width 50 and one with widthPercent of 25 and the other with widthPercent of 75, and the container is 200 pixels wide, first both get their width of 50. then the 100 remaining pixels are split up, so the one gets a total of 75 pixels and the other gets a total of 125.
This is automatically applied as the window is resized.
If there is not enough space - that is, when a horizontal scrollbar needs to appear - there are 0 pixels divided up, and thus everyone gets 0. This can cause a column to shrink out of proportion when passing the scroll threshold.
It is important to still set a fixed width (that is, to populate the width field) even if you use the percents because that will be the default minimum in the event of a scroll bar appearing.
The percents total in the column can never exceed 100 or be less than 0. Doing this will trigger an assert error.
Implementation note:
Please note that percentages are only recalculated 1) upon original construction and 2) upon resizing the control. If the user adjusts the width of a column, the percentage items will not be updated.
On the other hand, if the user adjusts the width of a percentage column then resizes the window, it is recalculated, meaning their hand adjustment is discarded. This specific behavior may change in the future as it is arguably a bug, but I'm not certain yet.
Added November 10, 2021 (dub v10.4)
After all the pixel widths have been assigned, any left over space is divided up among all columns and distributed to according to the widthPercent field.