Fill Policies

Ewl is a container-based widget library, this means that the container will care to place its children. As point of reference the preferred size of the child is used. In the case (and these cases are not rare) that the container has more free space or less free space to distribute the fill policies of the children kick in and adjust the widget sizes as needed to make everything fit. Thus you can give the container hints if the child is stick to its preferred size or if it can grow and/or shrink. The fill policies of Ewl can be a bit confusing for the first time user. But once you understood the concept, it gives you the power to arrange the widget as you like without being a worry to the underlying calculations, which are fortunately done by the container.

Using the fill policy

The basis for how fill policies fit together is shown the following image.

Todo:: Update this image

There are three sizes to any widget:

minimum size
preferred size
maximum size

As the name implies the widget wants to be set to its preferred size whenever possible. If the fill policy allows, the widget can also shrink or grow within the bounds of its minimum and maximum sizes.

EWL_FLAG_FILL_NONE: Do not fill or shrink in any direction

EWL_FLAG_FILL_VSHRINKABLE: Vertically shrinkable

EWL_FLAG_FILL_HSHRINKABLE: Horizontally shrinkable

EWL_FLAG_FILL_SHRINKABLE: Shrinkable both horizontally and vertically

EWL_FLAG_FILL_VSHRINK: Vertically shrink

EWL_FLAG_FILL_HSHRINK: Horizontally shrink

EWL_FLAG_FILL_SHRINK: Shrink both horizontally and vertically

EWL_FLAG_FILL_VFILL: Vertically fill

EWL_FLAG_FILL_HFILL: Horizontally fill

EWL_FLAG_FILL_FILL: Fill both horizontally and vertically

EWL_FLAG_FILL_ALL: Shrink or fill as needed

You can combine any combination of fill policies with a binary OR. For example EWL_FLAG_FILL_VSHRINK | EWL_FLAG_FILL_HSHRINK is the same like EWL_FLAG_FILL_SHRINK.

The difference between shrink and shrinkable

But what is the difference between the 'shrink' and the 'shrinkable' fill policy? The 'shrink' fill policy is used if the widget really wants to be shrunk, i.e. it prefers its minimum size over its actual set preferred size. Hence the container will only consider the minimum size of the child to calculate the preferred size. This fill policy is useful in cases, where you do not really want that the widget is shown in its full size. For example you do not want to show all items in a scrollpane, because if you'd want that you wouldn't use a scrollpane. So for a vertical scrollpane you can use VSHRINK, for example. The scrollpane will not show the whole list of the items, but it will make the scrollpane width enough, therefor each child fits into it and you don't need a horizontal scrollbar.

Guidelines for container authors

As you have seen in the previous section fill policies and the three different sizes are very closely connected. As a container author you have to set them to proper values in particular for the preferred size. Of course you do not have to overwrite them if you are inheriting this feature from the parent widget, as long it fits your needs.

Note:: The following guidelines are only commendations and not strict rules. There maybe good reason for some containers to not follow them.

The minimum size

A container should set a minimum size for any components it displays beyond the children packed inside of it. For example if you write a scrollpane, the minimum size should contain the scrollbars, but not the content added by the user of the container.

The preferred size

Every child of the container should be visible if the container has the size of its preferred size. Your container should respect the fill policy of the children, so if a child is set to SHRINK the user doesn't want it to be drawn in its full preferred size. For the calculation of the preferred size, it is advisable to use, what is returned from ewl_object_preferred_size_get(). If the child is set to shrink the returned value is the minimum size, for any other fill policy it will return the actual preferred size, i.e. what was set with ewl_object_preferred_inner_size_set() plus the inset and padding values.

The maximum size

You do not need to set this value. By default it is set to a very big number which should be sufficient in most cases. But, of course, you can set it if you need to.