gum-layout
$
npx mdskill add vchelaru/Gum/gum-layoutResolve 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
- bump-nuget-versionBump 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-cliReference 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-writingReference 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-behaviorsCovers 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-controlsReference 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-visualsReference 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-itemscontrolReference 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-localizationReference guide for Gum's runtime localization system — ILocalizationService, CSV/RESX loading, Text vs TextNoTranslate paths, Forms control localization patterns, and gotchas.
- gum-property-assignmentReference 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.