gum-layout

name	gum-layout
description	Gum's layout system — dimension units, position units, children layout modes, layout calculation flow, suspension. Triggers: Width/HeightUnits, XUnits/YUnits, stacking, wrapping, auto-sizing, Anchor/Dock, GraphicalUiElement layout logic. For engine internals see gum-layout-engine.

Gum Layout System

Gum's layout is driven by unit enums that tell the engine how to interpret numeric Width/Height/X/Y values, plus a children layout mode on containers. All layout lives in GraphicalUiElement (GumRuntime/GraphicalUiElement.cs).

Key Concepts

Dimension Units (Width & Height)

DimensionUnitType enum (GumDataTypes/DimensionUnitType.cs) controls how a Width or Height value is interpreted. Units fall into dependency categories:

Dependency	Units
No dependency	Absolute, PercentageOfSourceFile, PercentageOfOtherDimension, MaintainFileAspectRatio, AbsoluteMultipliedByFontScale, ScreenPixel
Depends on parent	PercentageOfParent, RelativeToParent, RelativeToMaxParentOrChildren*
Depends on children	RelativeToChildren
Depends on siblings	Ratio

* RelativeToMaxParentOrChildren is classified as DependsOnParent but also depends on children — special-cased throughout the layout engine. See dimension-units.md for circular dependency handling.

See dimension-units.md for detailed descriptions.

Position Units (X & Y)

GeneralUnitType enum (GumDataTypes/UnitConverter.cs) controls how X/Y values are measured: from edges, center, baseline, or as percentages. Combined with XOrigin/YOrigin (HorizontalAlignment/VerticalAlignment) to set which point on the element is being positioned.

See dimension-units.md for detailed descriptions.

Children Layout

ChildrenLayout enum (Gum/Managers/StandardElementsManager.cs):

• Regular — children positioned independently
• TopToBottomStack / LeftToRightStack — stack children along an axis
• AutoGridHorizontal / AutoGridVertical — arrange in wrapping grid

Related properties: StackSpacing, WrapsChildren, AutoGridHorizontalCells, AutoGridVerticalCells, StackedRowOrColumnDimensions.

Anchor & Dock

Convenience APIs on GraphicalUiElement that set multiple layout properties at once (X, Y, XUnits, YUnits, XOrigin, YOrigin, Width, WidthUnits, etc.).

• Anchor — 9 positions (TopLeft..BottomRight) + CenterHorizontally/Vertically
• Dock — Top, Left, Right, Bottom, Fill, FillHorizontally, FillVertically, SizeToChildren

Layout Engine

See layout-engine.md for the calculation flow, suspension system, dirty tracking, and performance considerations.

Quick Reference

Method	Purpose
UpdateLayout()	Full layout recalculation
UpdateLayout(updateParent, childrenUpdateDepth, xOrY)	Granular control
SuspendLayout(recursive)	Pause layout, queue as dirty
ResumeLayout(recursive)	Resume and apply queued updates
AbsoluteWidth / AbsoluteHeight	Final computed dimensions
MakeDirty(...)	Queue deferred update when suspended

Key Properties

• IsLayoutSuspended — instance-level pause
• IsAllLayoutSuspended — thread-static global pause (background loading)
• GlobalFontScale — multiplier for AbsoluteMultipliedByFontScale
• CanvasWidth / CanvasHeight — root canvas size