Box Model

A box is the fundamental visual building block in a Vexi user interface and typically represents a rectangular area on the screen. A box may contain other boxes, referred to as the children of the box. Boxes that are children of the same box are referred to as siblings. The children of a box, all their children, and subsequent boxes are referred to as descendents of the subject box. In this way, a parentless box and it's descendents combine to form a tree structure, a box tree where the topmost parentless box is referred to as the root box.

A root box may be attached to a Surface.

Box Layout

Layout Types

There are 3 layout strategies: pack, place, and layer

To change the layout strategy of a box, put one of these values as a string to the 'layout' property on the box.

Packed Layout

In packed layout boxes are positioned next to eachother in the direction of the parents orient property. The parent is constrained to the combined size of the packed children in the orient direction and to the maximum size of its children in the non-orient direction.

Place Layout

In placed layout child boxes are placed independently of each other and do not affect the size of the parent. They are placed according to the parent align property, and then offset by their x and y properties.

Layer Layout

In layered layout, child boxes are placed independently of each other and the parent is constrained to the maximum dimension of its largest child in each dimension. Child boxes are placed as with placed layout; according to the parent align property, and then offset by their x and y properties.


Box layout occurs in three phases:

  1. Constraining
  2. Placing
  3. Rendering

This process is called reflow. Every time a relevant box property is changed, this process is initiated.


Constraining is the process by which the size of the contents of a box is established. This occurs in a depth-first traversal of a box tree.

Herein considering the horizontal dimension, the contentwidth of a box is the maximum of:

  1. The value of the box's minwidth property
  2. The rendered width of the box's textual content
  3. The constrained width of the box's children

The constrained width of a box's children depends on the layout policy of the box:


0 -- that is, child boxes do not affect the width of the box

"layer" or "pack" with "vertical" orient

The maximum of the constrained child widths

"pack" with "horizontal" orient

The accumulation of the constrained child widths


The width of a box is assigned according to the 3 following rules, in strict order of priority:

  1. It's width is never greater than its maxwidth
  2. It's width will not be less than its contentwidth
  3. If a box is shrunk, the width be set to contentwidth

NB: if a box's maxwidth is less than it's contentwidth, the maxwidth is used

Boxes are placed in order in the space allocated to them by the parent box:

"place" or "layer"

A box is offset by the value of it's x and y properties from the alignment point of the parent. A box will try to be as wide as the space between it's offset x coordinate and the parents rightmost edge.

"pack" with "vertical" orient

A child box will try to be as wide as the parent. If it is not as wide, it is aligned according to the align property on the parent box.

"pack" with "horizontal" orient

Child boxes will try to consume any slack, and will attempt to be the same width. They are then placed consecutively next to each other in order of their index. If there is any slack, child boxes will be spaced evenly and aligned according to the align policy of the parent box.


A box tree is rendered in a depth-first pre-order traversal, starting with the root box.

  1. Render the color or texture, set by the fill property on a box, it applicable
  2. Render the text attribute of the box, if set to a non-empty string
  3. Render the boxes children (pre-order traversal).


Copyright © 2011 The Vexi Project (