Skip to content
Download
API reference

Box

Inherits: Container < Control < CanvasItem < Actor < Object

A container that lays out its children like the web’s flexbox, and draws a background.

A Box is a web div with display: flex: it places its children in a row or a column, on one line or wrapping onto more, with gaps between them and the alignment you choose. Its panel style is drawn behind them, and that style’s margins are its padding.

Boxes inside boxes make one layout, as nested elements do on a web page: a column of rows gets its sizes from all of them together. The layout is computed by Gobu’s own flexbox engine, a port of Yoga’s algorithm checked against layouts generated by Chrome.

A child grows on the main axis when its size flags have Control.SIZE_EXPAND, by its Control.size_flags_stretch_ratio, and Control.SIZE_SHRINK_BEGIN, Control.SIZE_SHRINK_CENTER or Control.SIZE_SHRINK_END on the cross axis align it on its own. A child is never smaller than its minimum size, nor bigger than its maximum size. Text that wraps (a Label with Label.text_wrap, or a RichTextLabel with autowrap and RichTextLabel.fit_content) is laid out like web text: as wide as it wants up to the space it gets, never narrower than its longest word, and as tall as its lines at that width.

Style sheets (StyleSheet) lay out boxes and their children with the web’s properties: flex-direction, flex-wrap, justify-content, align-items, align-content and gap on a box; flex, flex-grow, flex-shrink, flex-basis, align-self, width, height, their minimums and maximums, margin, aspect-ratio, order and position: absolute with its insets on any child of a box.

A property set in the Inspector wins over the style sheet; a property left at its default takes the sheet’s value, and the Inspector shows that value above it.

TypeNameDefault
Box.AlignContentalign_content0
Box.AlignItemsalign_items0
Box.Directiondirection0
Vector2gapVector2(0, 0)
Box.Justifyjustify_content0
Box.WrapModewrap0

  • DIRECTION_ROW = 0 — The children go in a row.

  • DIRECTION_COLUMN = 1 — The children go in a column.

  • DIRECTION_ROW_REVERSE = 2 — A row, from its end.

  • DIRECTION_COLUMN_REVERSE = 3 — A column, from the bottom.

  • WRAP_NONE = 0 — One line: the children shrink to fit, down to their minimum sizes.

  • WRAP_WRAP = 1 — The children that don’t fit go on to the next line.

  • WRAP_REVERSE = 2 — Like WRAP_WRAP, with the lines in reverse order.

  • JUSTIFY_START = 0 — The children are packed at the start.

  • JUSTIFY_CENTER = 1 — The children are centered.

  • JUSTIFY_END = 2 — The children are packed at the end.

  • JUSTIFY_SPACE_BETWEEN = 3 — The free space goes between the children.

  • JUSTIFY_SPACE_AROUND = 4 — The free space goes around each child: the ends get half as much.

  • JUSTIFY_SPACE_EVENLY = 5 — The free space is the same between the children and at the ends.

  • ALIGN_ITEMS_STRETCH = 0 — The children stretch to the line’s cross size.

  • ALIGN_ITEMS_START = 1 — The children sit at the start of the line.

  • ALIGN_ITEMS_CENTER = 2 — The children are centered in the line.

  • ALIGN_ITEMS_END = 3 — The children sit at the end of the line.

  • ALIGN_ITEMS_BASELINE = 4 — The children’s baselines line up.

  • ALIGN_CONTENT_STRETCH = 0 — The lines share the free space.

  • ALIGN_CONTENT_START = 1 — The lines are packed at the start.

  • ALIGN_CONTENT_CENTER = 2 — The lines are centered.

  • ALIGN_CONTENT_END = 3 — The lines are packed at the end.

  • ALIGN_CONTENT_SPACE_BETWEEN = 4 — The free space goes between the lines.

  • ALIGN_CONTENT_SPACE_AROUND = 5 — The free space goes around each line.

  • ALIGN_CONTENT_SPACE_EVENLY = 6 — The free space is the same between the lines and at the ends.

Box.AlignContent align_content = 0

Setter/getter: set_align_content(), get_align_content()

How the lines share the cross axis when the box wraps (CSS align-content).

Box.AlignItems align_items = 0

Setter/getter: set_align_items(), get_align_items()

Where each child sits on the cross axis of its line (CSS align-items). By default the children stretch to the line’s size.

Box.Direction direction = 0

Setter/getter: set_direction(), get_direction()

The main axis: a row (left to right, right to left in a right-to-left layout) or a column, either reversed (CSS flex-direction).

Vector2 gap = Vector2(0, 0)

Setter/getter: set_gap(), get_gap()

The space between children, in pixels: x between columns, y between rows (CSS column-gap and row-gap).

Box.Justify justify_content = 0

Setter/getter: set_justify_content(), get_justify_content()

How the children share the free space on the main axis (CSS justify-content).

Box.WrapMode wrap = 0

Setter/getter: set_wrap(), get_wrap()

Whether the children that don’t fit go on to another line (CSS flex-wrap). A wrapping box reports the height its lines need as its minimum size, like a label with autowrap.