agentleFS
vchelaruvchelaru/Gum/.claude/skills/gum-forms-controls/SKILL.md

gum-forms-controls

Skill659 starsChanged 2 months agoMITView on GitHub

Forms controls (FrameworkElement subclasses) and their relationship to the visual behind them. Triggers: Button, CheckBox, ListBox, ComboBox, TextBox, ScrollViewer, Gum.Forms.Controls, FlatRedBall.Forms.Controls, FrameworkElement, button.Visual, InteractiveGue, FormsControlAsObject, state machines, DefaultVisuals, ReactToVisualChanged.

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    No direct Background, Foreground, or BorderBrush properties — visual styling is done through states

    line 14
  2. Very specific:

    No WPF grid/dock/wrap panel auto-layout — sizing and positioning follow Gum's unit system (X, Y, XUnits, YUnits, Width, Height, WidthUnits, …

    line 15
  3. Very specific:

    Every FrameworkElement has a Visual property of type InteractiveGue (which is GraphicalUiElement).

    line 19
  4. Very specific:

    When Visual is assigned, ReactToVisualChanged() fires.

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Gum Forms Controls Reference

What They Are

Forms controls are classes inheriting from FrameworkElement (MonoGameGum/Forms/Controls/FrameworkElement.cs). Their names and API intentionally mirror WPF (Button, CheckBox, ListBox, TextBox, etc.), but the visual and layout engine is Gum (GraphicalUiElement/InteractiveGue), not WPF. A control reaches its visual through Visual; see gum-architecture-layers for the Forms, visual and Renderable layers and the user docs Controls vs Visuals: What Goes Where and Visual/Logical Tree Separation.

WPF conventions that do NOT apply here:

  • No Margin, Padding, HorizontalAlignment, VerticalAlignment (in the WPF sense) on FrameworkElement
  • No direct Background, Foreground, or BorderBrush properties — visual styling is done through states
  • No WPF grid/dock/wrap panel auto-layout — sizing and positioning follow Gum's unit system (X, Y, XUnits, YUnits, Width, Height, WidthUnits, HeightUnits)

The Visual / FrameworkElement Split

Every FrameworkElement has a Visual property of type InteractiveGue (which is GraphicalUiElement). The Visual owns all layout and rendering; the FrameworkElement is a logical/behavioral layer on top.

  • Visual.FormsControlAsObject — back-link from the InteractiveGue to its FrameworkElement
  • FrameworkElement.X/Y/Width/Height/etc. — all forward to Visual; there is no separate logical sizing
  • ActualWidth / ActualHeight — computed pixel values, read from Visual.GetAbsoluteWidth/Height()

The control does not own or know its visual's internal structure. The Visual is arbitrary and pluggable — the code-only default (*Visual/Default*Runtime), a tool-authored component with Forms behaviors, or a custom InteractiveGue subclass — and the control knows only the named children it looks up in ReactToVisualChanged (which may be absent). So "a Window has an InnerPanelInstance that fills it" is a property of one visual, not of Window. Any feature that depends on internal layout (e.g. sizing the content host to children) must live in a visual, never in the control, and cannot be assumed across visuals — which is why WindowVisual.MakeSizedToChildren() is on the visual. See gum-forms-default-visuals.

Two Construction Paths

Forms-first (new Button()): The default constructor calls GetGraphicalUiElementFor(this) which looks up DefaultFormsTemplates (or the older DefaultFormsComponents) to find the registered visual type, instantiates it with createFormsInternally: false, and assigns it as Visual. This path requires the type to be registered before the constructor runs.

Visual-first (new ButtonVisual()): The DefaultVisuals classes (in MonoGameGum/Forms/DefaultVisuals/) are InteractiveGue subclasses that construct all child runtimes, set up the state machine, and then call FormsControlAsObject = new Button(this) in their constructor. The two-bool constructor (bool fullInstantiation, bool tryCreateFormsObject) controls this — tryCreateFormsObject: false skips creating the Forms object, used when the visual is being instantiated by a Forms-first control.

ReactToVisualChanged

When Visual is assigned, ReactToVisualChanged() fires. Subclasses override this to grab references to named children:

protected override void ReactToVisualChanged()
{
    textComponent = Visual.GetGraphicalUiElementByName("TextInstance");
    coreTextObject = textComponent?.RenderableComponent as IText;
    base.ReactToVisualChanged();
}

Named child lookup is the standard pattern — controls depend on specific child names being present in the visual. Properties like Button.Text silently no-op (or throw in FULL_DIAGNOSTICS mode) if the expected child is absent.

ReactToVisualChanged runs only when a non-null visual is assigned, so an override can dereference Visual freely. Assigning Visual = null detaches the visual, and only ReactToVisualRemoved runs.

Visual States (Not WPF Styles)

Appearance changes are driven by a StateSaveCategory on the Visual. UpdateState() is called whenever interaction state changes and applies the correct state by name:

Visual.SetProperty("ButtonCategoryState", stateName);

Common state names are defined as constants on FrameworkElement (EnabledStateName, DisabledStateName, HighlightedStateName, PushedStateName, FocusedStateName, etc.). The GetState(string stateName) method searches all categories on the Visual.

To customize appearance, either replace the Visual with a custom one that has different state variable values, or get and modify states directly via control.GetState(...). For a deep dive into how variable values flow from save data through runtime application and how RefreshStyles pushes style changes to live Forms controls, see the gum-variable-deep-dive skill.

Class Hierarchy

FrameworkElement
├── ButtonBase (IInputReceiver)
│   ├── Button
│   ├── ToggleButton
│   ├── RadioButton
│   └── CheckBox
├── ItemsControl (→ ScrollViewer)
│   ├── ListBox
│   └── ComboBox
├── ScrollViewer
│   └── (also base of ItemsControl)
├── TextBoxBase (IInputReceiver)
│   ├── TextBox
│   └── PasswordBox
├── Panel
│   └── StackPanel
├── Label
├── Slider (RangeBase)
├── ScrollBar (RangeBase)
├── ListBoxItem
├── MenuItem
├── UserControl
└── Splitter

User-codegen'd screens and components also inherit from FrameworkElement when OutputLibrary is GumForms (the default for new projects). The generated partial class derives from FrameworkElement (or a matching built-in control when the element has Forms behaviors), so this inside CustomInitialize is a FrameworkElement — events like AfterRefreshStyles and overrides of SaveRuntimeProperties / ApplyRuntimeProperties are available on screens and components, not just on built-in controls like Button or Label. Only StandardElements (Container, Text, Sprite, etc.) remain non-Forms. See the gum-tool-codegen skill for how codegen picks the base class.

Key Files

PathPurpose
MonoGameGum/Forms/Controls/FrameworkElement.csBase class: Visual link, layout forwarding, state constants, construction
MonoGameGum/Forms/Controls/Primitives/ButtonBase.csPush/click/hold input handling
MonoGameGum/Forms/Controls/ItemsControl.csItems collection, InnerPanel management, ListBoxItemsInternal sync
MonoGameGum/Forms/DefaultVisuals/Pre-built InteractiveGue subclasses that create state machines and Forms objects
MonoGameGum/Forms/Controls/FrameworkElementExt.csExtension helpers (AddToRoot, etc.)

Non-Obvious Behaviors

Layout is Gum layout, not WPF layout. A Button with default Width = 128 and WidthUnits = Absolute is 128 pixels wide regardless of content — there is no WPF-style Auto sizing unless WidthUnits = RelativeToChildren. Do not expect WPF layout rules.

IsVisible vs Visibility: There is no Visibility enum. IsVisible maps directly to Visual.Visible (bool).

No color shortcut on the control. To change a button's color, either modify the state's variables on the Visual, or access the child runtime directly ((listBox.Visual as ButtonVisual)?.Background.Color = ...). There is no Background property on Button.

A control's constructor body runs after ReactToVisualChanged, so it must not overwrite a value a subclass set there. The Visual is assigned in FrameworkElement's constructor, and generated partial class X : Slider code runs CustomInitialize from ReactToVisualChanged. A derived constructor that assigns a default (Slider.Initialize, ScrollBar's orientation, RadioButton.GroupName) guards it with a "was it set" flag (IsMaximumSet, IsLargeChangeSet, hasAssignedOrientation) or relies on the field's own default. Do not re-assign a property to the value its field already holds.

ReactToVisualChanged can fire before child references exist. If Visual is reassigned at runtime, all GetGraphicalUiElementByName lookups re-run. Code that caches Visual children must refresh inside ReactToVisualChanged, not in the constructor.

ParentFrameworkElement walks the Visual parent chain, skipping non-Forms Gue nodes, until it finds a Gue whose FormsControlAsObject is a FrameworkElement. It does not just return the direct parent.

Re-adding a child is safe through the helpers, not through the raw collection. AddToRoot, GraphicalUiElement.AddChild (both overloads), FrameworkElementExt.AddChild, and Window/ScrollViewer.AddChild do nothing when the child is already under that parent, and move it when it is under another. They all funnel through GraphicalUiElement.AddChild(GraphicalUiElement); a raw Children.Add of an existing child still duplicates it.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.