Box
Inherits: Container < Control < CanvasItem < Actor < Object
A container that lays out its children like the web’s flexbox, and draws a background.
Description
Section titled “Description”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.
Properties
Section titled “Properties”| Type | Name | Default |
|---|---|---|
| Box.AlignContent | align_content | 0 |
| Box.AlignItems | align_items | 0 |
| Box.Direction | direction | 0 |
| Vector2 | gap | Vector2(0, 0) |
| Box.Justify | justify_content | 0 |
| Box.WrapMode | wrap | 0 |
Enumerations and constants
Section titled “Enumerations and constants”enum Direction
Section titled “enum Direction”- 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.
enum WrapMode
Section titled “enum WrapMode”- 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— LikeWRAP_WRAP, with the lines in reverse order.
enum Justify
Section titled “enum Justify”- 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.
enum AlignItems
Section titled “enum AlignItems”- 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.
enum AlignContent
Section titled “enum AlignContent”- 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.
Property descriptions
Section titled “Property descriptions”align_content
Section titled “align_content”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).
align_items
Section titled “align_items”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.
direction
Section titled “direction”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).
justify_content
Section titled “justify_content”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.