Skip to content

Restore LayoutGroup as its own page; rewrite Layout group nodes landing #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jduval23 merged 1 commit into from
May 12, 2026
Merged

Restore LayoutGroup as its own page; rewrite Layout group nodes landing #35

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 19 additions & 53 deletions docs/REFERENCES/scenegraph/layout-group-nodes/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,37 @@
---
title: "Layout group nodes"
excerpt: 'Arranges child nodes in rows or columns with configurable spacing and alignment'
excerpt: 'SceneGraph group nodes for arranging child nodes: Group, LayoutGroup, ButtonGroup, and TargetGroup'
deprecated: false
hidden: false
metadata:
title: 'Layout group nodes'
description: 'The LayoutGroup node arranges child nodes in a horizontal row or vertical column, with fields to control spacing, alignment, and margins around the group.'
description: 'Group nodes act as containers for other SceneGraph nodes. This page covers Group, LayoutGroup, ButtonGroup, and TargetGroup, and explains how they relate to each other.'
robots: index
next:
description: ''
---
Group nodes act as containers for other SceneGraph nodes. They define a local coordinate system, control the position and visibility of their children, and (in the case of LayoutGroup) automatically arrange children in a row or column.

## Choosing a node

Extends [**Group**](doc:group)
| Node | Use case |
| :--- | :--- |
| [Group](doc:group) | The foundational container node. Provides translation, rotation, scale, opacity, and visibility for itself and its children. Every renderable node ultimately extends Group. |
| [LayoutGroup](doc:layoutgroup) | Automatically arranges its children in a horizontal row or vertical column with configurable spacing and alignment. |
| [ButtonGroup](doc:buttongroup) | A specialized LayoutGroup for managing a set of [Button](doc:button) nodes, with built-in focus and selection handling. |
| [TargetGroup](doc:targetgroup) | Maps children to a [TargetSet](doc:targetset) of rectangular regions, animating items between target positions as focus moves. |

The LayoutGroup node class manages the position of its child nodes by arranging them in a row from left to right (horizontal layout), or in a column from top to bottom (vertical layout). Fields provide options to control the spacing between children, the horizontal and vertical alignment, and the margins around the edges of the group.
## Inheritance

## Fields
ButtonGroup extends [LayoutGroup](doc:layoutgroup), so its fields include everything LayoutGroup offers plus button-specific behavior. TargetGroup extends [Group](doc:group) directly and uses a TargetSet to position children, so it does not share LayoutGroup's row/column model.

## How positioning is calculated

<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Default</th>
<th>Access Permission</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>layoutDirection</td>
<td>string</td>
<td>vert</td>
<td>READ_WRITE</td>
<td>Controls the layout direction <table><thead><tr><th>Value</th><th>Use</th></tr></thead><tbody><tr><td>horiz</td><td>Positions the children in a row from left to right</td></tr><tr><td>vert</td><td>Positions the children in a column from top to bottom</td></tr></tbody></table></td>
</tr>
<tr>
<td>horizAlignment</td>
<td>string</td>
<td>left</td>
<td>READ_WRITE</td>
<td>Specifies the alignment point in the horizontal direction. The effect of the value set depends on the whether the layoutDirection field value is set to either horiz or vert <table><thead><tr><th>Value</th><th>layoutDirection</th><th>Use</th></tr></thead><tbody><tr><td>left</td><td>vert</td><td>Aligns the left edges of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the left edge of the children</td></tr><tr><td>left</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the left edge of the first child</td></tr><tr><td>center</td><td>vert</td><td>Aligns the centers of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the center alignment point</td></tr><tr><td>center</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the center of the horizontal row of children</td></tr><tr><td>right</td><td>vert</td><td>Aligns the right edges of each child in the column, and sets the <strong>LayoutGroup</strong> node local x-coordinate origin is at the right edge of the children</td></tr><tr><td>right</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the right edge of the last child</td></tr><tr><td>custom</td><td>vert</td><td>Explicitly set the x translation of each child of the LayoutGroup. If the layoutDirection is "horiz", custom will not be a valid setting. Instead, "left" will be used to do the child layout.</td></tr></tbody></table></td>
</tr>
<tr>
<td>vertAlignment</td>
<td>string</td>
<td>top</td>
<td>READ_WRITE</td>
<td>Specifies the alignment point in the vertical direction. The effect of the value set depends on the whether the layoutDirection field value is set to either horiz or vert <table><thead><tr><th>Value</th><th>layoutDirection</th><th>Use</th></tr></thead><tbody><tr><td>top</td><td>horiz</td><td>Aligns the top edges of each child in the row, and sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the top edge of the children</td></tr><tr><td>top</td><td>vert</td><td>Sets the LayoutGroup node local y-coordinate origin at the top edge of the first child</td></tr><tr><td>center</td><td>horiz</td><td>Aligns the centers of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the center alignment point</td></tr><tr><td>center</td><td>vert</td><td>Sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the center of the vertical column of children</td></tr><tr><td>bottom</td><td>horiz</td><td>Aligns the bottom edges of each child in the row, and sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the bottom edge of the children</td></tr><tr><td>bottom</td><td>vert</td><td>Sets the LayoutGroup node local y-coordinate origin at the bottom edge of the last child</td></tr><tr><td>custom</td><td>horiz</td><td>Explicitly set the y translation of each child of the LayoutGroup. If the layoutDirection is "vert", custom will not be a valid setting. Instead, "top" will be used to do the child layout.</td></tr></tbody></table></td>
</tr>
<tr>
<td>itemSpacings</td>
<td>array of floats</td>
<td>[ ]</td>
<td>READ_WRITE</td>
<td>Controls the spacing before or after each child in the layout direction. By default, no space is added between the children</td>
</tr>
<tr>
<td>addItemSpacingAfterChild</td>
<td>Boolean</td>
<td>true</td>
<td>READ_WRITE</td>
<td>Controls how the spaces specified in the itemSpacings field are inserted. By default, the field value is set to true. This causes the specified spaces to be inserted after the child is positioned. If the field value is set to false, the specified item space is inserted before the child is positioned</td>
</tr>
</tbody>
</table>
LayoutGroup and ButtonGroup arrange children based on each child's bounding rectangle: the rendered footprint of the child including any of its own children, images, or text. The fields on each node (`itemSpacings`, `horizAlignment`, `vertAlignment`, and so on) operate on those bounding rectangles, not on raw `width`/`height` values you set directly.

For details on how a bounding rectangle is computed for any node, and notes on when it's safe to read (typically after images load and layout settles), see [ifSGNodeBoundingRect](doc:ifsgnodeboundingrect).

## Looking for something else?

* **For built-in lists or grids of items** with focus and selection handling, see [List and grid nodes](doc:list-and-grid-nodes) (LabelList, MarkupList, PosterGrid, MarkupGrid, RowList, and others).
* **For a freely positioned set of children** without automatic layout, use a plain [Group](doc:group) and set each child's `translation` field directly.
109 changes: 109 additions & 0 deletions docs/REFERENCES/scenegraph/layout-group-nodes/layoutgroup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
---
title: "LayoutGroup"
excerpt: 'Arranges child nodes in a horizontal row or vertical column with configurable spacing and alignment'
deprecated: false
hidden: false
metadata:
title: 'LayoutGroup'
description: 'The LayoutGroup node arranges child nodes in a horizontal row or vertical column, with fields to control item spacing, horizontal and vertical alignment, and margins around the edges of the group.'
robots: index
next:
description: ''
---
Extends [**Group**](doc:group)

The LayoutGroup node class manages the position of its child nodes by arranging them in a row from left to right (horizontal layout), or in a column from top to bottom (vertical layout). Fields provide options to control the spacing between children, the horizontal and vertical alignment, and the margins around the edges of the group.

## Fields

<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Default</th>
<th>Access Permission</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>layoutDirection</td>
<td>string</td>
<td>vert</td>
<td>READ_WRITE</td>
<td>
Controls the layout direction.
<table>
<thead>
<tr><th>Value</th><th>Use</th></tr>
</thead>
<tbody>
<tr><td>horiz</td><td>Positions the children in a row from left to right</td></tr>
<tr><td>vert</td><td>Positions the children in a column from top to bottom</td></tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td>horizAlignment</td>
<td>string</td>
<td>left</td>
<td>READ_WRITE</td>
<td>
Specifies the alignment point in the horizontal direction. The effect of the value set depends on whether the layoutDirection field value is set to horiz or vert.
<table>
<thead>
<tr><th>Value</th><th>layoutDirection</th><th>Use</th></tr>
</thead>
<tbody>
<tr><td>left</td><td>vert</td><td>Aligns the left edges of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the left edge of the children</td></tr>
<tr><td>left</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the left edge of the first child</td></tr>
<tr><td>center</td><td>vert</td><td>Aligns the centers of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the center alignment point</td></tr>
<tr><td>center</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the center of the horizontal row of children</td></tr>
<tr><td>right</td><td>vert</td><td>Aligns the right edges of each child in the column, and sets the <strong>LayoutGroup</strong> node local x-coordinate origin at the right edge of the children</td></tr>
<tr><td>right</td><td>horiz</td><td>Sets the LayoutGroup node local x-coordinate origin at the right edge of the last child</td></tr>
<tr><td>custom</td><td>vert</td><td>Explicitly set the x translation of each child of the LayoutGroup. If the layoutDirection is "horiz", custom is not a valid setting; "left" is used instead.</td></tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td>vertAlignment</td>
<td>string</td>
<td>top</td>
<td>READ_WRITE</td>
<td>
Specifies the alignment point in the vertical direction. The effect of the value set depends on whether the layoutDirection field value is set to horiz or vert.
<table>
<thead>
<tr><th>Value</th><th>layoutDirection</th><th>Use</th></tr>
</thead>
<tbody>
<tr><td>top</td><td>horiz</td><td>Aligns the top edges of each child in the row, and sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the top edge of the children</td></tr>
<tr><td>top</td><td>vert</td><td>Sets the LayoutGroup node local y-coordinate origin at the top edge of the first child</td></tr>
<tr><td>center</td><td>horiz</td><td>Aligns the centers of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the center alignment point</td></tr>
<tr><td>center</td><td>vert</td><td>Sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the center of the vertical column of children</td></tr>
<tr><td>bottom</td><td>horiz</td><td>Aligns the bottom edges of each child in the row, and sets the <strong>LayoutGroup</strong> node local y-coordinate origin at the bottom edge of the children</td></tr>
<tr><td>bottom</td><td>vert</td><td>Sets the LayoutGroup node local y-coordinate origin at the bottom edge of the last child</td></tr>
<tr><td>custom</td><td>horiz</td><td>Explicitly set the y translation of each child of the LayoutGroup. If the layoutDirection is "vert", custom is not a valid setting; "top" is used instead.</td></tr>
</tbody>
</table>
</td>
</tr>
<tr>
<td>itemSpacings</td>
<td>array of floats</td>
<td>[ ]</td>
<td>READ_WRITE</td>
<td>Controls the spacing before or after each child in the layout direction. By default, no space is added between the children.</td>
</tr>
<tr>
<td>addItemSpacingAfterChild</td>
<td>Boolean</td>
<td>true</td>
<td>READ_WRITE</td>
<td>Controls how the spaces specified in the itemSpacings field are inserted. By default, the field value is set to true. This causes the specified spaces to be inserted after the child is positioned. If the field value is set to false, the specified item space is inserted before the child is positioned.</td>
</tr>
</tbody>
</table>
Loading