vchelaru 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 pauseIsAllLayoutSuspended— thread-static global pause (background loading)GlobalFontScale— multiplier for AbsoluteMultipliedByFontScaleCanvasWidth/CanvasHeight— root canvas size