Layout manager define the strategy of how to position the child widgets of a widget. They compute the position and size of each child by tyking the size hints and layout properties of the children and the size hint of the parent into account.

qooxdoo comes with some of the most common layout managers. The following layout managers are supported by qooxdoo:

• Basic: The Basic is used to position the children at absolute coordinates. It supports left and top coordinates and uses the preferred size of every widget to position it on the managed area.
• Canvas: The Canvas adds a few features to the Basic layout. For example it is possible to position a widgetrelative to the right or bottom edge of the available space. It also supports stretching between left and right or top and bottom e.g. left=20 and right=20 would keep a margin of 20 pixels to both edges. The Canvas layout has support for percent dimensions and locations.
• HBox/VBox: There are two box layouts, a horizontal HBox and a vertical VBox layout. Box layouts automatically put one child after another (horizontally from left to right or vertically from top to bottom). This is useful for many layout scenarios like toolbars (horizontal) or menus (vertical). They support all of the core widget features like margin (with support for collapsing). It is also possible to configure a spacing between each child. alignment and growing and shrinking. The box layouts also come with a lot of advanced features like flexible allocation (distribution of free space) of the available space and percent dimensions.
• Dock: A Dock Layout attaches the children to the edges of the availble space. The space distribution respect the child order and starts with the first child. Every added child reduces the available space of the other ones (this may be interesting as for example left attached children reduces the available width for top attached children and vice-versa). This layout is mainly used for the basic application layout structure. The dock layouts supports all kind of features like margins on the children and spacing between every child (configurable separately between horizontal and vertical axis).
• Grid: Table like grids can be created using the Grid layout. This is often used for forms to align labels and text fields etc. The layout supports many advanced features like column and row spans. Auto-sizing and spaces between cells are supported as well.
• Grow: The Grow layout is the simplest layout in qooxdoo. It scales every child to the full available width and height (still respecting limitations of each child). Normally this layout is used with only one child in scenarios where exactly one child should fill the whole content (e.g. adding a TabView to a Window). This layout performs a lot better in these cases than for example a canvas layout.

There are a few more layouts bundled with the default qooxdoo distribution but these are mostly thought to be used exclusively by one component only. For example the Atom uses the Atom Layout, the SplitPane uses the two split layouts HSplit and VSplit.

Through the simple API it should be quite easy to write custom layouts when the included ones are not enough. Simply derive from the Abstract Layout and start with a refined version of the method renderLayout.

Usually all position and size values are defined as pixel values. For example the left and top layout properties of the Basic layout are defined as pixel values.

Indicates the flexibility of the item, which indicates how an item’s container distributes remaining empty space among its children. Flexible elements grow and shrink to fit their given space. Elements with larger flex values will be made larger than elements with lower flex values, at the ratio determined by the two elements. The actual value is not relevant unless there are other flexible elements within the same container. Once the default sizes of elements in a box are calculated, the remaining space in the box is divided among the flexible elements, according to their flex ratios. Specifying a flex value of 0 has the same effect as leaving the flex attribute out entirely.

The easiest use case is to make exactly one child consuming the remaining space. This is often seen in modern application. For example the location field in common browsers are automatically configured to behave like this. To do this add a flex value of 1 to the child. To make more children behave like this, one could make them flexible the same way. The available space is automatically allocated between all of them. As flex allows integer values it is also possible to define weighted values. A flex value of 2 means double important than 1. The result is that from 100 pixel remaining space and two flexible children the one with 2 gets about 66 pixel and the other one 33 pixel.

Please note that in shrinking mode flex behaves the other way around. As a flex value of 2 means doubled importance compared to 1 the child with 2 is shrunk less than the child with 1.

In contrast to qooxdoo 0.7 flex values are supplemental to the normal size values of a widget. First all children are positioned using their regular size hints. If after this step the combined size of the children is larger or smaller than the available size the flex vaule defines by how much each widget is stretched/shrunk.

The flex property is supported by both Box Layouts, the Dock Layout and the Grid (for columns and rows).

In some way the Split Pane supports flex as well, but it behaves a bit different there as it is regarded as an alternative to the preferred size. The allocation is the Split Pane do not start with the remaining space, but with the full available space. A combination of the flex values 1 and 2 can be interpreted as “33%” and “66%”.

With the above mentioned flex feature the use of percents is quite un-common in most qooxdoo applications. Still there are some cases where it might be interesting to define percent locations or dimensions.

The Canvas Layout for example allows the position of children to percent values e.g. the layout property left could be configured to 20%. When there are 1000 pixel available the so-configured child is placed at a left coordinate of 200 pixel. The final coordinate is automatically updated when the outer dimensions are modified.

The dimension properties of the LayoutItem only support integer values. To allow percent dimensions some qooxdoo layout managers allows to define a width and height using layout properties. This dimensions are then higher priorized than the width and height configured in the child using the normal properties. The limitations defined through minWidth etc. are still respected by the layout manager. Percent dimensions are useful to allocate a specific part of the available space to a given widget without being dependend on the configuration of the other children.

It is possible to combine flex with percent dimensions. This is good because it allows to only define near matches like 3 times 33% instead of being forced to fill the 100% completely. With flex enabled the layout manager automatically arranges the children to fill the remaining pixels.

The effects of percent dimensions in box layouts are comparable to the result of flex in a Split Pane. The resulting size is computed from the available space minus all statically configured gaps like spacings or margins. Layout managers with support for percent dimensions are the already mentioned box layouts, but also the Canvas Layout as well as the Dock Layout.

The docking of children inside a Dock Layout is confgured with the dock layout property. The property can be empty for exactly one child (the centered one). For all other children a value of north, east, south or west must be defined.

• Basic
• Canvas
• HBox/VBox
• Grid
• Dock
• Grow

• Template for new layouts