From 5734aff47c404a0c419f61a534c832d927600da2 Mon Sep 17 00:00:00 2001 From: Christopher Dwyer-Perkins Date: Tue, 12 May 2026 12:17:31 -0300 Subject: [PATCH] Restore LayoutGroup as its own page; rewrite Layout group nodes landing Upstream commit 600fc230 (May 6, 2026) renamed layout-group-nodes/layoutgroup.md to layout-group-nodes/index.md as a "fixed index page for layoutgroups" cleanup. The rename was a pure git move with zero content changes, but it left the LayoutGroup reference dressed up as a section landing (title still "Layout group nodes" rather than "LayoutGroup", which had been mismatched to the filename even before the May 6 rename), and broke five inbound doc:layoutgroup link sites pointing at a slug that no longer existed. Like Dialog (PR #34), LayoutGroup is a concrete instantiable node (not an abstract base class), so its natural home is back at layout-group-nodes/layoutgroup.md alongside ButtonGroup, TargetGroup, and Group. This change restores the page (title corrected to "LayoutGroup", fields-table HTML reformatted with proper indentation and per-row line breaks for source readability while preserving the rendered output) and rewrites index.md as a real section landing. The new landing: - Covers all four nodes in the section (Group, LayoutGroup, ButtonGroup, TargetGroup) with use-case descriptions - Notes the inheritance relationships (ButtonGroup extends LayoutGroup; TargetGroup extends Group directly, not LayoutGroup) - Adds a "How positioning is calculated" section explaining that LayoutGroup/ButtonGroup arrange children based on each child's bounding rectangle, with a pointer to ifSGNodeBoundingRect - Points readers at List and grid nodes for built-in list/grid options, and at plain Group for free-positioning use cases All five inbound doc:layoutgroup references resolve naturally to the restored page without any link rewrites elsewhere. No inbound references to doc:layout-group-nodes existed. --- .../scenegraph/layout-group-nodes/index.md | 72 +++--------- .../layout-group-nodes/layoutgroup.md | 109 ++++++++++++++++++ 2 files changed, 128 insertions(+), 53 deletions(-) create mode 100644 docs/REFERENCES/scenegraph/layout-group-nodes/layoutgroup.md diff --git a/docs/REFERENCES/scenegraph/layout-group-nodes/index.md b/docs/REFERENCES/scenegraph/layout-group-nodes/index.md index cdb454ce..96af317e 100644 --- a/docs/REFERENCES/scenegraph/layout-group-nodes/index.md +++ b/docs/REFERENCES/scenegraph/layout-group-nodes/index.md @@ -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 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
FieldTypeDefaultAccess PermissionDescription
layoutDirectionstringvertREAD_WRITEControls the layout direction
ValueUse
horizPositions the children in a row from left to right
vertPositions the children in a column from top to bottom
horizAlignmentstringleftREAD_WRITESpecifies 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
ValuelayoutDirectionUse
leftvertAligns 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
lefthorizSets the LayoutGroup node local x-coordinate origin at the left edge of the first child
centervertAligns the centers of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the center alignment point
centerhorizSets the LayoutGroup node local x-coordinate origin at the center of the horizontal row of children
rightvertAligns the right edges of each child in the column, and sets the LayoutGroup node local x-coordinate origin is at the right edge of the children
righthorizSets the LayoutGroup node local x-coordinate origin at the right edge of the last child
customvertExplicitly 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.
vertAlignmentstringtopREAD_WRITESpecifies 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
ValuelayoutDirectionUse
tophorizAligns the top edges of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the top edge of the children
topvertSets the LayoutGroup node local y-coordinate origin at the top edge of the first child
centerhorizAligns the centers of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the center alignment point
centervertSets the LayoutGroup node local y-coordinate origin at the center of the vertical column of children
bottomhorizAligns the bottom edges of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the bottom edge of the children
bottomvertSets the LayoutGroup node local y-coordinate origin at the bottom edge of the last child
customhorizExplicitly 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.
itemSpacingsarray of floats[ ]READ_WRITEControls the spacing before or after each child in the layout direction. By default, no space is added between the children
addItemSpacingAfterChildBooleantrueREAD_WRITEControls 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
+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. diff --git a/docs/REFERENCES/scenegraph/layout-group-nodes/layoutgroup.md b/docs/REFERENCES/scenegraph/layout-group-nodes/layoutgroup.md new file mode 100644 index 00000000..c0d417e8 --- /dev/null +++ b/docs/REFERENCES/scenegraph/layout-group-nodes/layoutgroup.md @@ -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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDefaultAccess PermissionDescription
layoutDirectionstringvertREAD_WRITE + Controls the layout direction. + + + + + + + + +
ValueUse
horizPositions the children in a row from left to right
vertPositions the children in a column from top to bottom
+
horizAlignmentstringleftREAD_WRITE + 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. + + + + + + + + + + + + + +
ValuelayoutDirectionUse
leftvertAligns 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
lefthorizSets the LayoutGroup node local x-coordinate origin at the left edge of the first child
centervertAligns the centers of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the center alignment point
centerhorizSets the LayoutGroup node local x-coordinate origin at the center of the horizontal row of children
rightvertAligns the right edges of each child in the column, and sets the LayoutGroup node local x-coordinate origin at the right edge of the children
righthorizSets the LayoutGroup node local x-coordinate origin at the right edge of the last child
customvertExplicitly 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.
+
vertAlignmentstringtopREAD_WRITE + 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. + + + + + + + + + + + + + +
ValuelayoutDirectionUse
tophorizAligns the top edges of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the top edge of the children
topvertSets the LayoutGroup node local y-coordinate origin at the top edge of the first child
centerhorizAligns the centers of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the center alignment point
centervertSets the LayoutGroup node local y-coordinate origin at the center of the vertical column of children
bottomhorizAligns the bottom edges of each child in the row, and sets the LayoutGroup node local y-coordinate origin at the bottom edge of the children
bottomvertSets the LayoutGroup node local y-coordinate origin at the bottom edge of the last child
customhorizExplicitly 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.
+
itemSpacingsarray of floats[ ]READ_WRITEControls the spacing before or after each child in the layout direction. By default, no space is added between the children.
addItemSpacingAfterChildBooleantrueREAD_WRITEControls 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.