genhvbox
Genhvbox is a generic, abstract horizontal/vertical box layout calculator for
dynamic layouts. The caller builds a tree representing the layout and
specifies various constraints. Genhvbox's update solves the constraints
so that sizes and coordinates of each element of the layout is known.
When used properly, such a dynamic layout can grow in size (when the user
resizes a window for example) with the newly gained space allocated to
the most important widgets.
concepts
A layout is a tree. The root node is special, as it has to match the size of
the window or screen area hosting the layout. The root has exactly one child.
Leaf nodes are usually widgets; widgets have no children. Widgets
have minimal size constraint specified by the caller.
Intermediate nodes are boxes.
A box has zero or more children. A box has a main and an auxiliary direction:
| box type | main direction | auxiliary direction
|
|---|
| hbox | horizontal | vertical
|
| vbox | vertical | horizontal
|
Children of the box inherit the auxiliary size of the box, which
is no smaller than the largest children (plus two times the passing of
the box) in that direction. The rules
for determining sizes in the main directions are:
- 1. calculate the minimum size by adding all children's size in the main direction, plus two times the box's padding
- 2. if the main size of the box is larger, the difference is called the available space
- 3a. if there is one or more children with span set to fill, enlarge them evenly to take up all available space; the alignment of the box is ignored as children will take up all available space
- 3b. available space will be inserted around the children, using the alignment
The alignments parameter of a box affects how available space is
distributed in the gaps left by non-filling children of the box. Alignments are:
- justify: spread available space evenly among the gaps between the children; if there's only one child, it is center-aligned
- center: no gap between the children, allocate half of available space before and the other half after the children
- left or top: children are packed to the left (hbox) or to the top (vbox), all available space allocated on the right or bottom
- right or bottom: children are packed to the right (hbox) or to the bottom (vbox), all available space allocated on the left or top
The span parameter determines how much room the given node tries to claim in the main direction of its parent box:
- minimal: the node stays as small as possible, no matter how much room is available
- in case of widgets, this means the minimum size specified by the caller
- in case of a box, this is the sum of the minimum sizes of all children in the main direction
- special case: the child of the root is always maximized in both directions
- fill: try to fill up available space (grow)
- an integer between 1 and 100: percentage of space to be claimed within the parent box
The padding field is used to pad content by inserting a few pixels wide
frame of empty space around the given node. The default value of padding is 0.
The minimum size a given node claims in its parent is increased by
2*node->padding in both directions.