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

gum-forms-behaviors

Skill659 starsChanged 2 months agoMITView on GitHub

Gum behaviors and the design-time to runtime Forms wrapping lifecycle, including FormsProperties (Forms-only properties shown as behavior variables on a visual in the tool). Triggers: BehaviorSave, FormsProperties, ElementBehaviorReference, BehaviorFormsPropertyApplier, StandardFormsBehaviorNames, RegisterFromFileFormRuntimeDefaults, DefaultFromFile*Runtime, Behavior category in the Variables tab, referencing a Forms property from a variable reference.

The file

Files
SKILL.md

Gum Forms Behaviors

What Behaviors Are

Behaviors are named capability contracts stored as .behx XML files in the project's Behaviors/ folder. Each behavior (BehaviorSave) declares: The Forms, visual and Renderable layers are in gum-architecture-layers; a variable reference that reads a FormsProperty is in "Two Layers in One Variable List" below.

  • A Name (e.g. "ButtonBehavior")
  • Required visual state Categories (with state names like Enabled/Disabled/Highlighted/Pushed)
    • A control assigns its logical state names on purpose and chooses which states it implements; the visual state for an unimplemented one is thrown away as intended, so a state name that does not exist is never reported.
  • Optional RequiredVariables and RequiredInstances
  • A DefaultImplementation path pointing to the default visual (e.g. "Controls/ButtonStandard")

An ElementSave (component or screen) opts into a behavior via a List<ElementBehaviorReference>, where each reference holds only a BehaviorName string. This is the signal used at runtime to select which Forms control wraps the visual.

The Wrapping Lifecycle

At project load time, call order is:

  1. FormsUtilities.RegisterFromFileFormRuntimeDefaults() iterates every component in the loaded GumProjectSave, checks each component's Behaviors list against constants in StandardFormsBehaviorNames, and calls ElementSaveExtensions.RegisterGueInstantiationType(component.Name, typeof(DefaultFromFileXxxRuntime)) for each match.
  2. DefaultFromFileXxxRuntime (in MonoGameGum/Forms/DefaultFromFileVisuals/) is an InteractiveGue subclass selected as the runtime type. Its AfterFullCreation() override fires after the full visual tree is instantiated. Inside AfterFullCreation(), the runtime sets FormsControlAsObject = new Button(this) (passing itself as the visual), completing the pairing.
  3. ReactToVisualChanged() fires on the Forms control when its Visual is assigned. The control caches named child references (Visual.GetGraphicalUiElementByName(...)) and base.ReactToVisualChanged() subscribes to input events and calls UpdateState().

The DefaultFromFileXxxRuntime classes exist solely to bridge the file-loading path into the Forms object model. They are distinct from the DefaultVisuals classes (which serve the code-only construction path).

Behavior → Forms Control Mapping

StandardFormsBehaviorNames constants → DefaultFromFile runtime registered:

Behavior name constantRuntime type
ButtonBehaviorNameDefaultFromFileButtonRuntime
CheckBoxBehaviorNameDefaultFromFileCheckBoxRuntime
ToggleBehaviorNameDefaultFromFileToggleButtonRuntime
DialogBoxBehaviorNameDefaultFromFileDialogBoxRuntime
UserControlBehaviorNameDefaultFromFileUserControlRuntime
ComboBoxBehaviorNameDefaultFromFileComboBoxRuntime
ListBoxBehaviorNameDefaultFromFileListBoxRuntime
TextBoxBehaviorNameDefaultFromFileTextBoxRuntime
LabelBehaviorNameDefaultFromFileLabelRuntime / DefaultFromFileLabelTextRuntime
ItemsControlBehaviorNameDefaultFromFileItemsControlRuntime
RadioButtonBehaviorNameDefaultFromFileRadioButtonRuntime
SliderBehaviorNameDefaultFromFileSliderRuntime
ScrollBarBehaviorNameDefaultFromFileScrollBarRuntime
ScrollViewerBehaviorNameDefaultFromFileScrollViewerRuntime
MenuBehaviorNameDefaultFromFileMenuRuntime
MenuItemBehaviorNameDefaultFromFileMenuItemRuntime
PasswordBoxBehaviorNameDefaultFromFilePasswordBoxRuntime
PanelBehaviorNameDefaultFromFilePanelRuntime
StackPanelBehaviorNameDefaultFromFileStackPanelRuntime
WindowBehaviorNameDefaultFromFileWindowRuntime

The Property Promotion Gap (closed for logical + state-mapped)

The Gum tool operates at the visual layer — layout, colors, fonts, dimensions saved as VariableSave entries. The Forms behavioral layer (state, data, interaction) is added at runtime. Two mechanisms now bridge the save model into Forms semantics: FormsProperties for the value-on-the-control half, and ToolOnlyVariableReferences for the design-time visual-state preview half.

Two Layers in One Variable List

  • Selecting an instance in the tool lists every visual variable (X, XUnits, origins, ...) and, in a "Behavior" category, the FormsProperties of its behaviors. In code a Button is only the Forms control and the visual is button.Visual, so the tool's list mixes the two layers.
  • A FormsProperty is not a variable of the visual. It lives on the FrameworkElement and BehaviorFormsPropertyApplier sets it by reflection. The tool still stores an edit as an Instance.Name variable in the owner's state (Slider.Minimum), and a VariableReferences line can read it.
  • A user VariableReferences line reads a FormsProperty of an instance of its own element: in a game from the live Forms control, in the tool from the stored variable, else the behavior default (FormsBehaviorChain.BuildFormsPropertyDefaultsFallback, the same three tiers). Text = Slider.Minimum gives "1" when 1 is stored and "0" when only the default exists. A read through an exposed name, a nested instance or another element still needs a stored value. At runtime a double into a float or string variable arrives only with expression evaluation on (GumExpressionService.Initialize()); without it the type mismatch is reported and the line is not applied.
  • GUM0009 (HeadlessErrorChecker) resolves Instance.Var through the same chain as the evaluator: a variable stored under that exact name on the owner or its base components with SetsValue true and no ExposedAsName, an exposed entry that has a stored Value and names a FormsProperty declared on the instance type chain, then the instance type and its bases. It has no behavior-default fallback, so a line that reads only a default is reported, matching what the tool applies. The layers themselves are in gum-architecture-layers.

BehaviorSave.FormsProperties (v1)

A List<VariableSave> declaring design-time properties that flow through to the wrapped FrameworkElement at runtime via reflection. Each entry's Name must match a property on the control (e.g. ToolTip, IsEnabled); Value is the declared default (used as a fallback tier — see below).

The variable grid synthesizes a "Behavior" category for these declarations on both the component definition and any instance (ElementSaveDisplayer.AddBehaviorFormsPropertyMembers). When a component sets a default on a promoted property under General, the displayer relocates it into "Behavior" to keep categorization consistent.

BehaviorSave.ToolOnlyVariableReferences (v2)

A List<string> of variable-reference assignments evaluated only at design time to drive wireframe preview. Example on ButtonBehavior:

ButtonCategoryState = IsEnabled ? "Enabled" : "Disabled"

Tool-time apply (BehaviorToolOnlyReferencesApplier, in the variable-grid plugin) walks every linked behavior's ToolOnlyVariableReferences, evaluates the RHS via EvaluatedSyntax against the component's effective state, and writes the resolved value back into the state via SetValue. For instances, bare RHS identifiers are auto-qualified with the instance name. Hooked into VariableReferenceLogic.DoVariableReferenceReaction immediately after the existing state-level apply.

The runtime apply path never traverses this list — that's what the ToolOnly name encodes structurally. At runtime, the Forms control's own setter (e.g. FrameworkElement.IsEnabled → UpdateState()) owns the visual; applying the reference again would double-write.

Every reference's left-hand variable must be in VariablesHiddenFromInstances on each template component using the behavior. Otherwise an instance can set the visual state directly: the tool shows it, while the runtime still follows the Forms property. TemplateDerivedVariablesHiddenTests enforces this for the Standard template and every theme. Hide every other state category the control drives at runtime too (ScrollViewerCategoryState, OrientationCategoryState), not only reference targets. TemplateDerivedVariablesHiddenTests fails for any category on a behavior-bearing component that is neither hidden nor in its InstanceAuthoredCategories list (SizingCategory, TextCategory: states an instance is meant to set). A hidden variable with no reference stays visible on instances that already author it; one that a reference drives never does. Container-structure variables (ContainedType, ChildrenLayout, ClipsChildren, IsRenderTarget, ExposeChildrenEvents) are exposed on an instance only when the control is the visual itself, a bare container (Panel, UserControl, StackPanel). A control with something internal (ItemsControl, ListBox, ScrollViewer, Window, DialogBox, SettingsView, every other control) hides all five. StackPanel also hides ChildrenLayout because its Orientation reference drives it. TemplateDerivedVariablesHiddenTests enforces this against an explicit per-control table (MustHideStructureVariables); a new template control needs an entry there. Hiding is tool-only, so an instance that already authored one of them keeps the value in the tool, at runtime, and in generated code (CodeGenerator skips a hidden variable only when a behavior reference drives it, IObjectFinder.IsVariableDrivenByToolOnlyReference). BehaviorFormsPropertyCatalogTests (MonoGameGum.Tests) pins that each declared FormsProperty exists on the control and that its declared default equals a new control's, because the applier writes that default onto every authored control.

Three-tier default resolution

Both apply paths plus the variable-grid display getter consult the same priority order:

  1. Parent-state instance override (e.g. screen state "ButtonInstance.IsEnabled")
  2. Component's own default state value
  3. Behavior-declared FormsProperty.Value (the implicit default)

Tier 3 is virtual — never written to state, never appears in .gusx. State-empty stays state-empty. The fallback machinery:

  • RecursiveVariableFinder.Fallback (Func<string, object?>?) — consulted when state lookup returns null.
  • EvaluatedSyntax.FromSyntaxNode takes an optional fallback parameter threaded through every recursive evaluation.
  • BehaviorToolOnlyReferencesApplier builds a per-element fallback that walks every linked behavior's FormsProperties and resolves bare or instance-qualified identifiers to declared Value.
  • BehaviorFormsPropertyApplier.Apply adds the third tier inline: ReadEffectiveValue(...) ?? declaration.Value.

Each tier-2/3 default is applied once, at the control's own build, never re-applied by an ancestor. SetGraphicalUiElement calls InitialFormsPropertiesNotifier(built, true) for the element it just built (all three tiers) and (instance, false) for that element's own instances only (Apply(..., authoredOverridesOnly: true): just a value the container's default state, or a base of it, explicitly authors for the instance; no fall-through to the instance's component and no declared default). An instance owned by a nested element is skipped, so code that ran in that element's CustomInitialize (which runs in AfterFullCreation, after the control exists) keeps what it set, at any nesting depth. A value the container authors still wins over CustomInitialize, since the container's pass runs after it. InitialStateAppliedNotifier (the UpdateState re-sync) still walks every descendant. The built element's own control gets its values where it is created: every DefaultFromFile*Runtime.AfterFullCreation calls BehaviorFormsPropertyApplier.ApplyToCreatedControl(this) right after FormsControlAsObject = new X(this), and ApplyOnceAtBuild (a ConditionalWeakTable mark) makes the build's root pass a no-op for that control. So a custom runtime deriving a DefaultFromFile*Runtime that sets a Forms property after base.AfterFullCreation() keeps it. A runtime type that creates its own control instead of deriving one gets no creation-time apply and keeps the old behavior (the root pass applies after its AfterFullCreation).

  • A control whose children the owning screen parents in after the control is built can defer a default it cannot take yet: Apply offers each non-authored value to FrameworkElement.TryDeferDesignDefault, and TabControl keeps SelectedIndex 0 until its first tab arrives (the tool previews tab 0 selected; a code-created control keeps -1).
  • StateReferencingInstanceMember.DefaultValueFallback lets the variable grid show the declared default in the checkbox/text without writing into state. IsDefault still returns true (state empty), preserving the grid's italic/grey styling.

Codegen (FullyInCode GumForms) mirrors tiers 1 and 2 only (and a Forms property authored in a category state, which ApplyState also writes onto the control): it assigns authored values on the control and relies on tier 3 equalling the control's code default (see CodeGenerator.FillWithFormsPropertyAssignments, gum-tool-codegen).

VariableSave.Description (v3)

Authored documentation persisted alongside the FormsProperty declaration in the .behx. ElementSaveDisplayer.AddBehaviorFormsPropertyMembers seeds each row's srim.DetailText from the declaration's Description when surfacing behavior-promoted variables, so the variable grid shows authored docs by default. Distinct from the [XmlIgnore] DetailText field, which holds transient state-dependent hints set by tool/plugin code at runtime; see the cross-referencing XML docs on both fields. Use Description only when a property's name is ambiguous, has overlapping siblings (e.g. MaxLength vs MaxLettersToShow), or assumes prior framework knowledge.

Covered today

Snapshot, not a live reference. Standard Forms behaviors (.behx) and components (.gucx) are copied into the project when Forms controls are added — the Add Forms dialog (and new-project setup) copies the chosen theme into the project via FormsFileService. Two themes ship, and a fix usually belongs in both: Tools/Gum.ProjectServices/Templates/FormsTemplate/ — exposed as the Standard theme, so the source folder name differs from the theme name — and Tools/Gum.ProjectServices/Templates/FormsThemes/Bubblegum/. (GumFormsPlugin's post-build stages both under Content/FormsThemes/{Standard,Bubblegum}/, which is what FormsFileService reads.) Later improvements — new FormsProperty declarations, new ToolOnlyVariableReferences, additional VariablesHiddenFromInstances entries — do not retroactively reach controls already copied into a project; only controls added afterward from an updated tool build get them. So a "feature works in a new project but not mine" report usually means the project's copy predates the improvement. (Concrete case: a project whose TextBoxBehavior lacks the TextWrapping FormsProperty and whose Controls/TextBox.gucx doesn't yet hide LineModeCategoryState — the user set the raw visual line-mode to Multi, the text wraps, but the forms line-mode never engages and the caret stays single-line.)

State-mapped (FormsProperty + ToolOnlyVariableReference, three-tier default resolution):

  • IsEnabled — every standard Forms behavior. Behaviors with no Disabled visual still get the FormsProperty (runtime reflection works) but no reference (no visual state to drive).
  • IsChecked — CheckBox, RadioButton, Toggle, with nested-ternary references combining IsEnabled and IsChecked into the appropriate <X>CategoryState slot.
  • VerticalScrollBarVisibility — ScrollViewer, mapped to the existing ScrollBarVisibility category via ScrollBarVisibilityState = VerticalScrollBarVisibility == "Hidden" ? "NoScrollBar" : "VerticalScrollVisible". The == comparison relies on the enum↔string bridge in EvaluatedSyntax.AreEqual — see the gum-tool-save-classes skill for the int-on-disk vs boxed-enum-in-memory roundtrip. Project-side state authoring decides what each state actually changes visually.
  • Orientation — ScrollBar. OrientationCategoryState = Orientation == "Horizontal" ? "Horizontal" : "Vertical", default Vertical; the state is hidden on instances. A bar authored before the property existed (instance or element with only OrientationCategoryState = Horizontal) gets the matching Orientation on load from MigrateScrollBarOrientationStateToProperty (in GumProjectSaveExtensionMethods.Initialize, so the runtime sees it too); the tool-time apply would otherwise delete that state as stale. A component that holds a horizontal bar (ScrollViewer's HorizontalScrollBarInstance) authors both Orientation and the state.
  • TextWrapping + AcceptsReturn — TextBox. The line-mode pair: both drive the visual LineModeCategory (Single/Multi) via LineModeCategoryState = TextWrapping == "Wrap" ? "Multi" : (AcceptsReturn ? "Multi" : "Single"), mirroring the runtime's TextBoxBase.UpdateStateForSingleOrMultiLine. LineModeCategoryState is hidden via VariablesHiddenFromInstances on Controls/TextBox.gucx so the forms properties are the single source of truth. The TextBox component has only Single/Multi (no MultiNoWrap), so the AcceptsReturn-only case collapses to Multi, matching the runtime fallback. Caret/line math keys off these forms properties (TextBoxBase.IsSingleLineMode), not the visual state — so a project that sets the visual LineModeCategoryState directly (e.g. an older project where it isn't hidden) wraps the text but leaves the caret single-line. PasswordBox declares both FormsProperties but its component has no LineModeCategory, so no reference is wired there.

Logical-only (FormsProperty only — runtime reflects directly):

  • ToolTip — every standard Forms behavior.
  • TextBox/PasswordBox: AcceptsTab, IsReadOnly, Placeholder, MaxLength (int?).
  • TextBox-only: MaxLettersToShow (int?), MaxNumberOfLines (int?).
  • Slider/ScrollBar (RangeBase): Minimum, Maximum, Value, SmallChange, LargeChange.
  • ScrollBar/ScrollViewer LargeChange is declared double? with no default: unauthored, the runtime computes it from the viewport. SmallChange keeps its declared default of 10. A value set in code or authored marks that property as set (RangeBase.IsLargeChangeSet/IsSmallChangeSet), and the runtime's own writes go through SetComputedLargeChange/SetComputedSmallChange, which skip once set, so a Visual swap keeps it. A new runtime write to either must use those.
  • Slider-only: TicksFrequency, IsSnapToTickEnabled.
  • ScrollViewer: SmallChange, LargeChange (fanned to inner scroll bars by ScrollViewer's setters), HorizontalScrollBarVisibility.
  • ItemsControl/ListBox: Orientation (Orientation?).

Value-alias (FormsProperty name ≠ the underlying visual variable name — needs both a reference and hiding):

  • Spacing → StackSpacing — StackPanel. Same value, two names (the Forms Spacing setter is a pass-through to the visual StackSpacing). BehaviorFormsPropertyApplier resolves by the FormsProperty name (Spacing), so it never sees an authored StackSpacing and writes the behx default — silently clobbering the authored value at runtime. Bridge with a StackSpacing = Spacing ToolOnlyVariableReference for design-time preview, and hide StackSpacing via VariablesHiddenFromInstances on Controls/StackPanel.gucx (mirrors ButtonStandard.gucx hiding ButtonCategoryState) so Spacing is the single source of truth. Without the hiding, both names stay editable and the reference overwrites a hand-set StackSpacing on the next reaction.
  • Orientation → ChildrenLayout — StackPanel. Enum→enum mapping: ChildrenLayout = Orientation == "Horizontal" ? "LeftToRightStack" : "TopToBottomStack". Unlike the float-identity Spacing case, this depends on variable-reference enum coercion (EvaluatedSyntax.CastTo parses the string name into the boxed ChildrenLayout — see [[gum-tool-variable-references]]); without it the materialized string is dropped by the typed ChildrenLayout setter. ChildrenLayout is hidden on instances alongside StackSpacing. (Orientation's setter already forces a stack layout at runtime, so hiding it loses no honored capability.)

Wireframe incremental-update gotcha (value-alias). A value-alias name (Spacing, Orientation) is not a real GraphicalUiElement property, so the editor's incremental preview path (MainEditorTabPlugin.HandleVariableSetLate, gated by PropertiesSupportingIncrementalChange) can't push it onto the live GUE. Left unhandled, every scrub tick of the alias falls back to a full WireframeObjectManager.RefreshAll rebuild (~1 fps — issue #3191). The bridge is BehaviorToolOnlyReferencesApplier.GetUnderlyingMembersDrivenBy(element, instance, changedMember): it resolves the alias to the underlying visual variable(s) the behavior reference drives (Spacing→StackSpacing), whose already-materialized value is then pushed via gue.SetProperty. The underlying name (not the alias) is what belongs in PropertiesSupportingIncrementalChange.

Nullable type declarations. When a Forms control's property is int? (or Orientation?) and null is meaningful, declare the ? in FormsProperty.Type (e.g. Type="int?", Type="Orientation?") so the variable grid renders the nullable editor and authors can clear back to null. The runtime applier reflects on prop.PropertyType regardless, so coercion works either way.

Enum-typed FormsProperty declarations. Author the default Value as a string (<Value xsi:type="xsd:string">Auto</Value>) — the applier's IsEnum branch parses it via Enum.Parse. The variable grid resolves the enum's name string (e.g. Type="ScrollBarVisibility") via TypeManager.GetTypeFromString, so the type must live in or be linked into an assembly TypeManager.Initialize scans (GumCommon, where TypeManager is compiled, plus the assemblies holding VerticalAlignment and DimensionUnitType). TextWrapping, ScrollBarVisibility, and Orientation are physically in MonoGameGum/Forms/ but <Compile Include>-linked into GumCommon.

Reflection apply is generic, so any new logical-only FormsProperty declaration flows through without runtime changes. State-mapped properties beyond what's listed follow the same shape: declare the FormsProperty(/ies) plus a ToolOnlyVariableReference driving the appropriate <X>CategoryState.

Key Files

PathPurpose
GumDataTypes/Behaviors/BehaviorSave.csBehavior definition model (.behx)
GumDataTypes/Behaviors/ElementBehaviorReference.csPer-element reference holding only BehaviorName
GumDataTypes/Behaviors/StandardFormsBehaviorNames.csString constants for all standard behavior names
GumDataTypes/ElementSave.csBehaviors list on components/screens
MonoGameGum/Forms/FormsUtilities.csRegisterFromFileFormRuntimeDefaults() — drives the mapping; sets InitialFormsPropertiesNotifier (invokes BehaviorFormsPropertyApplier) and InitialStateAppliedNotifier (UpdateState)
MonoGameGum/Forms/DefaultFromFileVisuals/DefaultFromFileXxxRuntime classes — AfterFullCreation() creates Forms objects
MonoGameGum/Forms/BehaviorFormsPropertyApplier.csReflects BehaviorSave.FormsProperties values onto the wrapped FrameworkElement (with three-tier default resolution)
Gum/Plugins/InternalPlugins/VariableGrid/BehaviorToolOnlyReferencesApplier.csTool-only design-time apply pass for ToolOnlyVariableReferences. Strictly tool-only — never invoked from runtime / generated code.
Gum/Plugins/InternalPlugins/VariableGrid/ElementSaveDisplayer.csAddBehaviorFormsPropertyMembers — surfaces FormsProperties in the variable grid; sets DefaultValueFallback on each SRIM so the grid shows the declared default; seeds srim.DetailText from the FormsProperty's Description.
GumDataTypes/Variables/VariableSave.csDescription (persisted, XML-serialized) and DetailText ([XmlIgnore], transient) fields with cross-referencing XML docs.
Gum/Plugins/InternalPlugins/VariableGrid/StateReferencingInstanceMember.csDefaultValueFallback final tier in the value getter for grid display.
Runtimes/GumExpressions/EvaluatedSyntax.csOptional fallback parameter on FromSyntaxNode threaded through evaluation.
Gum/DataTypes/RecursiveVariableFinder.csFallback property consulted when state lookup returns null.
GumRuntime/InteractiveGue.csFormsControlAsObject back-link property

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.