gum-layout

Name: gum-layout
Author: vchelaru/Gum

$npx mdskill add vchelaru/Gum/gum-layout

Resolve complex UI dimension and stacking calculations.

Handles Width, Height, X, Y, and percentage unit conversions.
Depends on GraphicalUiElement and GumDataTypes enums.
Calculates layout flow based on parent or child dependencies.
Outputs resolved dimensions for container and element placement.

SKILL.md

.github/skills/gum-layoutView on GitHub ↗

---
name: gum-layout
description: >
  Reference guide for Gum's layout system — dimension units, position units,
  children layout modes, layout calculation flow, and layout suspension.
  Load when working on Width/HeightUnits, XUnits/YUnits, stacking, wrapping,
  auto-sizing, Anchor/Dock, or GraphicalUiElement layout logic.
  For deep engine internals (debugging/optimizing UpdateLayout, UpdateChildren,
  dirty state), see the gum-layout-engine skill instead.
trigger_phrase: layout|WidthUnits|HeightUnits|DimensionUnitType|XUnits|YUnits|ChildrenLayout|UpdateLayout|StackSpacing|WrapsChildren|Anchor|Dock|SuspendLayout|ResumeLayout|RelativeToChildren|RelativeToParent|PercentageOfParent|Ratio
---

# 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](dimension-units.md) for circular dependency handling.

See [dimension-units.md](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](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](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 |
| `GetAbsoluteWidth()` / `GetAbsoluteHeight()` | 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

More from vchelaru/Gum

Skill	Description
bump-nuget-version	Bump the NuGet package versions for all 12 Gum projects (11 libraries + GumCli). Queries NuGet to check if a version exists for today, then sets the new version to YYYY.M.D.V where V increments from the latest published version today (or starts at 1). Creates a release branch named ReleaseCode_YYYY_M_D_V, commits the changes, and pushes. Run this before triggering the nuget release workflow.
gum-cli	Reference guide for GumCli — the headless command-line tool for Gum projects. Load this when working on gumcli commands (new, check, codegen, codegen-init), Gum.ProjectServices, HeadlessErrorChecker, ProjectLoader, HeadlessCodeGenerationService, CodeGenerationAutoSetupService, or the FormsTemplateCreator.
gum-docs-writing	Reference guide for writing Gum documentation in GitBook markdown. Load when writing or editing docs/ files, adding pages to SUMMARY.md, using GitBook hints/figures, linking between pages, or adding images.
gum-forms-behaviors	Covers Gum's behaviors system and the design-time → runtime Forms wrapping lifecycle. Load this when working on BehaviorSave, ElementBehaviorReference, StandardFormsBehaviorNames, FormsUtilities.RegisterFromFileFormRuntimeDefaults, DefaultFromFileXxxRuntime classes, or when investigating why Forms properties cannot be set at design time in the Gum tool.
gum-forms-controls	Reference guide for Forms controls — classes inheriting from FrameworkElement. Load this when working on Button, CheckBox, ListBox, ComboBox, TextBox, ScrollViewer, or any class in Gum.Forms.Controls (or FlatRedBall.Forms.Controls). Also load when working on FrameworkElement itself, the Visual/InteractiveGue relationship, state machines, DefaultVisuals, or ReactToVisualChanged.
gum-forms-default-visuals	Reference guide for Forms DefaultVisuals — the code-only visual classes that back Forms controls. Load when working on ButtonVisual, any *Visual class in DefaultVisuals/, Styling, DefaultFormsTemplates registration, or building custom code-only Forms visuals.
gum-forms-itemscontrol	Reference guide for ItemsControl and ListBox — the Items/ListBoxItems relationship, templates, InnerPanel sync, and gotchas. Load this when working on ItemsControl, ListBox, ListBoxItem, VisualTemplate, FrameworkElementTemplate, Items collection behavior, ListBoxItems desync, or adding/removing items from a list box.
gum-layout-engine	>
gum-localization	Reference guide for Gum's runtime localization system — ILocalizationService, CSV/RESX loading, Text vs TextNoTranslate paths, Forms control localization patterns, and gotchas.
gum-property-assignment	Reference guide for how Gum applies variables and sets properties on renderables. Load this when working on ApplyState, SetProperty, SetVariablesRecursively, CustomSetPropertyOnRenderable, font loading, IsAllLayoutSuspended, or isFontDirty.