LogoLogo
  • Gum Tool
    • Introduction
    • Setup
      • Running from Source
    • Showcase
    • Tutorials and Examples
      • Intro Tutorials
        • 1 - The Basics
        • 2 - Variables Tab
        • 3 - Files
        • 4 - Components
        • 5 - Exposing Variables
        • 6 - Parent
        • 7 - States
        • 8 - State Categories
      • Animation Tutorials
        • 1 - Introduction to Animation
        • 2 - Creating an Animation
        • 3 - Playing Animations inside other Animations
        • 4 - Combining Multiple Categories
      • Examples
        • Bottom-Up Stack
        • Centering
        • Custom NineSlice
        • Health Bar
        • Padding
    • Gum Elements
      • General Properties
        • Alpha
        • Base Type (Inheritance)
        • Blend
        • Clips Children
        • Has Events
        • Height Units
        • Ignored By Parent Size
        • Locked
        • Max Height
        • Max Width
        • Min Height
        • Min Width
        • Order
        • Parent
        • Rotation
        • Visible
        • Variable References
        • Width Units
        • X
        • X Origin
        • X Units
        • Y
        • Y Origin
        • Y Units
      • Behaviors
        • Default Implementation
      • Circle
      • ColoredRectangle
      • Component
        • Default Child Container
      • Container
        • Children Layout
        • Contained Type
        • Is Render Target
        • Stack Spacing
        • Wraps Children
      • NineSlice
        • Blend
        • Custom Frame Texture Coordinate Width
        • Texture Address
        • Texture Left
        • Texture Top
      • Polygon
        • Points
      • Skia Standard Elements
        • General Properties
          • Has Dropshadow
          • Is Filled
          • Use Gradient
        • Arc
          • Start Angle
          • Sweep Angle
          • Thickness
        • Canvas
        • ColoredCircle
        • LottieAnimation
        • RoundedRectangle
          • Corner Radius
        • Svg
      • Sprite
        • Color
        • Source File
        • Texture Address
        • Wrap
      • States
        • Categories
      • Text
        • Blue
        • Color
        • Font
        • Font Scale
        • Font Size
        • Green
        • Is Bold
        • Is Italic
        • MaxLettersToShow
        • Outline Thickness
        • Red
        • Text
        • Text Overflow Horizontal Mode
        • Text Overflow Vertical Mode
        • Use Custom Font
        • Use Font Smoothing
    • Project Tab
    • Code Tab
      • Runtime Generation Details
      • Generation Scope
      • Inheritance Location
      • Is CodeGen Plugin Enabled
      • Show CodeGen Preview
    • Localization
    • Menu
      • Content
      • Project Properties
    • Plugins
      • AddAndRemoveVariablesForType
      • AddMenuItem
      • Export
      • Setting Up Post Build Events
    • Variables
      • Add Variable
    • Bitmap font generator (.fnt)
    • Upgrading
      • Migrating 2025 April 27 to Preview
      • Breaking Changes
        • Removal of Variable Spaces
  • Code
    • Gum Code Reference
      • AnimationRuntime
      • BitmapCharacterInfo
      • BitmapFont
      • Camera
      • CircleRuntime
      • ColoredRectangleRuntime
      • Component Runtimes
      • ContainerRuntime
      • Cursor
      • Gum Class Overview
      • DataUiGrid
        • Reflection
        • Categories
      • ElementSave
        • ToGraphicalUiElement
      • GraphicalUiElement
        • Absolute Values
        • AddToManagers
        • AnimateSelf
        • ApplyState
        • BlendState
        • CanvasHeight
        • CanvasWidth
        • Children
        • ContainedElements
        • Font Values
        • GetAbsoluteHeight
        • GetAbsoluteWidth
        • GetChildByNameRecursively
        • GetFrameworkElementByName
        • IsAllLayoutSuspended
        • Parent
        • RemoveFromManagers
        • UpdateLayout
      • GumProjectSave
      • IDataUi
      • InstanceMember
      • InstanceSave
      • InteractiveGue
        • CurrentInputReceiver
        • RaiseChildrenEventsOutsideOfBounds
        • RollOverBubbling
      • IPositionedSizedObject
      • Layer
      • NineSliceRuntime
      • RectangleRuntime
      • Renderer
        • SinglePixelTexture
      • SelectedState
      • SpriteRenderer
        • LastFrameDrawStates
      • SpriteRuntime
        • TextureAddress
        • TextureHeight
        • TextureLeft
        • TextureTop
        • TextureWidth
      • TextRuntime
        • Color
        • FontScale
        • FontSize
        • HorizontalAlignment
        • Text Wrapping
        • VerticalAlignment
      • VariableSave
    • FNA
    • Kni
    • Meadow
    • MonoGame
      • Setup
        • Linking Game Project to Source (Optional)
      • Tutorials
        • Gum Project Forms Tutorial
          • Setup
          • Gum Screens
          • Common Component Types
          • Styling
          • Multiple Screens
        • Code-Only Gum Forms Tutorial
          • Setup
          • Forms Controls
          • ListBox Items
          • Input in Forms
        • [Deprecated] Gum Project (.gumx) Tutorial
          • Setup
          • Gum Screens
          • Gum Forms
          • Customizing Forms
          • Strongly Typed Components Using Code Generation
          • Multiple Screens
      • Setup for GumBatch (Optional)
      • Loading a Gum Project (Optional)
      • async Programming
      • Custom Runtimes
      • GumBatch
      • Gum Forms
        • Binding (ViewModels)
        • Controls
          • Button
          • CheckBox
          • FrameworkElement
            • BindingContext
            • IsEnabled
            • IsFocused
            • ModalRoot and PopupRoot
            • SetBinding
          • ListBox
          • ListBoxItem
          • MenuItem
          • PasswordBox
          • RadioButton
          • ScrollViewer
            • VerticalScrollBarValue
          • StackPanel
          • Slider
          • TextBox
        • Control Customization In Code
          • MenuItem
        • Control Customization in Gum Tool
        • Gamepad Support
        • Keyboard Support
        • Troubleshooting
      • File Loading
      • Resizing the Game Window
      • Known Issues
      • Samples
        • MonoGameGumFormsSample
    • Nez
    • Silk.NET
    • SkiaGum
      • Setup
        • WPF
    • .NET MAUI
      • Setup
Powered by GitBook
On this page
  • Introduction
  • Example
  • Regular
  • Top to Bottom Stack
  • Left to Right Stack
  • Stacking and Container Height Units and Width Units
  • Stacking and X/Y Values
  • Stacking and Units
  • Stack Spacing
  • Stacking and Children Origin
  • Wraps Children
  • Reordering Children
  • Auto Grid Horizontal and Auto Grid Vertical
  • Auto Grid and Width/Height Units

Was this helpful?

Edit on GitHub
Export as PDF
  1. Gum Tool
  2. Gum Elements
  3. Container

Children Layout

PreviousContainerNextContained Type

Last updated 2 months ago

Was this helpful?

Introduction

Children Layout determines how a container positions its children. The default value is Regular which means that children are positioned according to their and .

Top to Bottom Stack results in the children stacking one on top of another, from top to bottom.

Left to Right Stack results in the children stacking one beside another, from left to right.

Auto Grid Horizontal results in the children being placed in a grid, filling in horizontally first before wrapping to the next row.

Auto Grid Vertical results in the children being placed in a grid, filling in vertically first before wrapping to a new column.

Example

The following animation shows how to use the ChildrenLayout variable to change the default position of a Container's children:

Regular

Regular layout positions each child independent of every other child. The position of one child does not affect the position other children. This is the default layout for containers.

Top to Bottom Stack

Top to Bottom Stack results in each child being positioned after its previous sibling vertically. This can be used to create horizontal stacks.

Left to Right Stack

Left to Right Stack results in each child being positioned after its previous sibling horizontally. This can be used to create vertical stacks.

Stacking and Container Height Units and Width Units

A container can stack its children and also have its size based on its children. This results in the container growing as children are added.

For example, the following shows a container with its Height Units set to Relative To Children and its Children Layout set to Top To Bottom Stack. As more children are added the container grows vertically.

Stacking and X/Y Values

When children stack, each child's X or Y depends on the boundary of its previous sibling. When stacking vertically, the child's Y value begins at the bottom side of the previous item. Similarly, when stacking horizontally, the child's X value begins at the right side of the previous item.

For example, the following image shows a Text object with a Y value of 20. Notice that it is positioned 20 units below the item above it.

This effect is easy to notice when dragging an object inside a stack, as shown in the following animation:

Stacking and Units

If instances are stacked in a container, the stacking controls the instance values based on the direction of the stack.

  • Top to Bottom Stack containers control the Y value of their children.

  • Left to Right Stack containers control the X value of their children.

The position value which is not controlled by the stack can be changed freely without any impact on the stacking.

For example, if a container stacks its children using a Top to Bottom Stack, the children in the stack are free to change their X values. The following animation shows how children can be left, center, or right anchored (which changes their X Units and X Origin) without affecting the other children in the stack.

An object stacks only if its position unit values are top or left for vertical or horizontal stacks. For example, if a child is part of a Top to Bottom Stack, it only stacks if its Y Units is set to Pixels from Top. Otherwise it ignores its parents stacking behavior.

In general this can cause unexpected behavior, especially if additional siblings follow the child which is not using the default Pixels from Top or Pixels from Left, so changing this value on the primary stacking direction is not recommended.

Stack Spacing

Stacking and Children Origin

Consider a container with a blue rectangle which stacks horizontally. The blue occupies some space according to its absolute width. The next instance after the blue rectangle is placed relative to the right-side of the blue rectangle.

For example, if a red rectangle (partially transparent to make it easier to see when overlapping) is added to the container, the stack may create a layout similar to the following image:

This overlapping may not be desirable, so keep this in mind when changing a stacked child's origin.

Wraps Children

Reordering Children

Children of a container which uses the Top To Bottom Stack or Left To Right Stack are ordered according to their order in the tree view on the left. By default this is the order in which the children are added to a parent container.

Children can be reordered using the right-click menu on an instance.

Alternatively, children order can be changed by clicking on the item in the tree view, holding down the ALT key, then pressing the up or down arrows.

Auto Grid Horizontal and Auto Grid Vertical

Auto Grid Horizontal and Auto Grid Vertical layouts result in each child of the container being placed in its own cell. All position and size values are relative to the entire cell, so children can expand to fill their cell or be positioned according to any side or corner.

The following shows a container with an Auto Grid Horizontal and Vertical Cells of 2, resulting in a 2x2 grid. As children are added to the container through copy/paste, each child is placed in its own cell.

The number of cells is controlled by the Auto Grid Horizontal Cells and Auto Grid Vertical Cells. Increasing the number of cells results in the rows or columns adjusting automatically.

Each child occupies one cell, and the order of the children controls the order of the placement in grids. The first child occupies the top-left row. If using Auto Grid Horizontal, each child is placed to the right of its preceding sibling, wrapping to the next line when reaching the end of a row. If using Auto Grid Vertical, each child is placed below its preceding sibling, wrapping to the next column when reaching the end of a column.

Children can be reordered by using the alt+arrow key in the tree view, resulting in reordering just like when using a stacking Children Layout.

Children treat their particular cell in the grid as their parent, so any sizes or positions will be based on their parent cell. In other words, if a child's Width Units is set to Relative To Parent, the parent in this case is the cell, not the entire Container instance.

The number of cells in a grid is determined by multiplying Auto Grid Cells Horizontal by Auto Grid Cells Vertical. If a container has more children than its total cells and if the container's size does not depend on its children, additional children spill over the bounds of the grid. The following animation shows a 3x3 grid using Auto Grid Horizontal. As more children are added, additional rows are added below the bounds of the grid.

When using Auto Grid Horizontal, the number of columns is fixed, but additional rows can be added beyond the bounds of the container.

When using Auto Grid Vertical, the number of rows is fixed, but additional columns can be added beyond the bounds of the container.

Auto Grid and Width/Height Units

Top to Bottom Stack and Left to Right Stack separate their children using the Stack Spacing value. For more information, see the page.

The position of a child in a stack is determined by the size of the previous item in the stack and the origin of the child. In most cases children which are stacked should use a Left if the parent uses a Left To Right Stack and should use a Top if the parent uses a Top To Bottom Stack.

Keep in mind that the stack simply states the position of the next item. Each item can freely adjust its X Origin (or Y Origin in a Top to Bottom Stack). If the red rectangle's is changed to Center, the red rectangle overlaps the blue rectangle.

If the red rectangle's is changed to Right, then its right side aligns with the right side of the blue rectangle, resulting in the red overlapping the blue completely. In this case the red rectangle's stacking is essentially cancelled out by the .

The property controls how stacking behaves beyond boundaries. For more information, see the page.

For more information on ordering, see the page.

If the container has its Width Units or Height Units set to Relative To Children, then its size may adjust in response to adding more children. For more information, see the and pages.

If a container's Children Layout is set to Auto Grid Horizontal or Auto Grid Vertical, it can size itself according to the largest cell by using Width Units or Height Units of Relative To Children. For more information see the and pages.

Stack Spacing
X Origin
Y Origin
X Origin
X Origin
X Origin
Wraps Children
Wraps Children
Order
X Units
Y Units
Width Units
Width Units
Height Units
Height Units
Children Layout with Regular selected
Changing Children Layout updates the position of all contained children
Two ColoredRectangles using Regular layout
Text Instances in a top to bottom stack
Sprites in a Left to Right Stack
Top To Bottom Stack can be used with Height Units of Relative To Children to grow the container as children are added
A Text's Y value can be used to separate it from its previous sibling in a Top to Bottom Stack
As a Y value changes, all following siblings move too
Changing horizontal layout values does not affect siblings in a Top to Bottom Stack
Top to Bottom Stack is only respected if the child has its Y Units set to Pixels from Top
The next item's position is based on the right-side of the blue rectangle
Red rectangle is positioned relative to the right-side of the blue rectangle.
Stack determines a child's position, the child can change its origin
Red rectangle overlapping blue rectangle
Item order in the Project tab determines the order of items in a stacked container
Changing order with ALT+Arrow hotkey
Blue ColoredRectangles in a Container using Children Layout of Auto Grid Horizontal
Container using Auto Grid Horizontal creating a 2x2 grid
Increasing Auto Grid Horizontal Cells adds additional columns
Auto Grid Vertical and Horizontal change the ordering of children
Alt+arrow changes the order of the selected item in the tree view, updating the positions in the grid
Changing Anchor and Dock values results in children being placed relative to their particular cell
Additional children can create rows or columns outside of the bounds of the grid.