gum-forms-itemscontrol
Skill659 starsChanged 2 months agoMITView on GitHub
ItemsControl and ListBox — Items/ListBoxItems relationship, templates, InnerPanel sync. Triggers: ItemsControl, ListBox, ListBoxItem, VisualTemplate, FrameworkElementTemplate, Items collection, ListBoxItems desync, list box item add/remove.
In this repository69 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- debuggingSkill
- frb-build-verificationSkill
- frb-pixel-harnessSkill
- gum-architecture-layersSkill
- gum-bundleSkill
- gum-cliSkill
- gum-cross-platform-unificationSkill
- gum-docs-writingSkill
- gum-file-pathsSkill
- gum-forms-behaviorsSkill
- gum-forms-controlsSkill
- gum-forms-default-visualsSkill
- gum-forms-theme-importSkill
- gum-iconsSkill
- gum-issue-creationSkill
- gum-kernsmith-integrationsSkill
- gum-layout-engineSkill
- gum-layoutSkill
- gum-localizationSkill
- gum-monogame-renderingSkill
- gum-monthly-releaseSkill
- gum-project-versioningSkill
- gum-property-assignmentSkill
- gum-raylib-renderingSkill
- gum-releaseSkill
- gum-runtime-animation-chainsSkill
- gum-runtime-bindingSkill
- gum-runtime-fontsSkill
- gum-runtime-hot-reloadSkill
- gum-runtime-syntax-versionSkill
- gum-runtime-systemmanagers-initSkill
- gum-runtime-topologySkill
- gum-runtime-variable-referencesSkill
- gum-samplesSkill
- gum-serviceSkill
- gum-source-linked-projectSkill
- gum-themingSkill
- gum-tool-animationsSkill
- gum-tool-codegenSkill
- gum-tool-copy-pasteSkill
- gum-tool-delete-logicSkill
- gum-tool-dialogsSkill
- gum-tool-errorsSkill
- gum-tool-file-watchSkill
- gum-tool-font-generationSkill
- gum-tool-import-from-gumxSkill
- gum-tool-loggingSkill
- gum-tool-outputSkill
- gum-tool-pluginsSkill
- gum-tool-save-classesSkill
- gum-tool-screenshotsSkill
- gum-tool-selectionSkill
- gum-tool-tree-viewSkill
- gum-tool-undoSkill
- gum-tool-variable-gridSkill
- gum-tool-variable-referencesSkill
- gum-tool-viewmodelsSkill
- gum-unit-testsSkill
- gum-variable-deep-diveSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 117
When set, DisplayMemberPath causes listBoxItem.UpdateToObject(property_value_as_string) instead of UpdateToObject(the_object_itself).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.
Files
ItemsControl and ListBox Reference
Key Files
| File | Purpose |
MonoGameGum/Forms/Controls/ItemsControl.cs | Base class: Items property, template resolution, InnerPanel sync |
MonoGameGum/Forms/Controls/ListBox.cs | Adds ListBoxItems tracking, selection, and ListBoxItem creation |
MonoGameGum/Forms/Controls/ListBoxItem.cs | Individual row control; holds IsSelected, IsHighlighted, events |
MonoGameGum/Forms/VisualTemplate.cs | Creates GraphicalUiElement instances (visual-first) |
MonoGameGum/Forms/FrameworkElementTemplate.cs | Creates FrameworkElement instances (forms-first) |
The Two Collections
Items and ListBoxItems are separate and can get out of sync.
Items(IList, defaultObservableCollection<object>) — the logical data collection. Can hold anything: strings, view models,ListBoxIteminstances, or anyFrameworkElement/GraphicalUiElement.ListBoxItems(ReadOnlyCollection<ListBoxItem>) — the visual row controls actually shown. WrapsListBoxItemsInternal(aList<ListBoxItem>).
In normal usage (adding data objects to Items) they stay in sync. They diverge in several cases — see Desync Gotchas below.
Data Flow: Items → InnerPanel → ListBoxItems
Adding to Items triggers a two-stage pipeline:
HandleItemsCollectionChanged— responds toItems. Creates or locates a visual and inserts it intoInnerPanel.Children.HandleInnerPanelCollectionChanged— responds toInnerPanel.Children. CallsHandleCollectionNewItemCreated(frameworkElement, index).HandleCollectionNewItemCreated(ListBox override) — if the item is aListBoxItem, inserts it intoListBoxItemsInternaland callsAssignListBoxEvents.
HandleCollectionNewItemCreated is NOT called directly from step 1. It is only triggered by InnerPanel firing its own CollectionChanged. This indirection is intentional.
What Gets Created Per Item Type
HandleItemsCollectionChanged dispatches based on what was added to Items:
Item type added to Items | What happens |
FrameworkElement | Its .Visual is inserted into InnerPanel directly — no new wrapper created |
GraphicalUiElement | Inserted into InnerPanel directly — no wrapper |
Any other data object AND VisualTemplate is set | VisualTemplate.CreateContent(item, createFormsInternally:false) is called; result inserted |
Any other data object, no VisualTemplate | CreateNewItemFrameworkElement(item) is called |
ListBox overrides CreateNewItemFrameworkElement with additional logic:
| Item type | ListBox behavior |
ListBoxItem | Used as-is — no template, no wrapping |
| Anything else | Calls CreateNewVisual(vm) (uses VisualTemplate or DefaultFormsTemplates[typeof(ListBoxItem)]), then wraps result in a ListBoxItem via CreateNewListBoxItem. BindingContext and UpdateToObject are called on the result. |
Templates
There are two template types with different roles:
VisualTemplate — produces a GraphicalUiElement (visual-first).
- Constructed with a
Type(must have(bool, bool)or no-arg constructor),Func<GraphicalUiElement>,Func<object, GraphicalUiElement>, orFunc<object, bool, GraphicalUiElement>. - Used by
CreateNewVisual. When constructed from aType, calls it with(true, false)—createFormsInternally:falseprevents the visual from creating its own Forms object, since the ListBox will wrap it. - Set on
ItemsControl.VisualTemplate. Changing it clears and rebuilds all visuals.
FrameworkElementTemplate — produces a FrameworkElement (forms-first).
- Constructed with a
TypeorFunc<FrameworkElement>. - Used by
CreateNewItemFrameworkElement. For ListBox, the result must be aListBoxItemsubclass or an exception is thrown. - Set on
ItemsControl.FrameworkElementTemplate.
Global fallback — if neither template is set, DefaultFormsTemplates[typeof(ListBoxItem)] is used (set during app initialization). This is the normal path for default apps.
Setting a template clears and rebuilds all existing items — both VisualTemplate and FrameworkElementTemplate setters call ClearVisualsInternal() and replay the Items collection.
Desync Gotchas
1. Adding a non-ListBoxItem FrameworkElement to Items
When a Button, CheckBox, or other FrameworkElement is added to Items, its Visual is inserted into InnerPanel. HandleInnerPanelCollectionChanged fires, but asGue.FormsControlAsObject is the Button (not a ListBoxItem), so HandleCollectionNewItemCreated is called with a Button. ListBox's override only inserts into ListBoxItemsInternal if the item is ListBoxItem, so the Button is silently skipped. Items.Count increases but ListBoxItems.Count does not.
2. Adding directly to InnerPanel.Children
HandleInnerPanelCollectionChanged fires and can populate ListBoxItemsInternal if the child's FormsControlAsObject is a ListBoxItem. But Items is never updated — it stays at 0 (or whatever it was). This is the case when a ListBox's visual is constructed by the Gum tool with pre-filled children.
3. Gum tool pre-filled ListBox and Menu (IsAuthoredRow / AdoptAuthoredRow)
When a Visual with an InnerPanel is assigned, ItemsControl.ReactToVisualChanged finds the panel children whose control passes IsAuthoredRow (ListBoxItem in ListBox, MenuItem in Menu) and calls AdoptAuthoredRow for each, which puts them at the front of Items and the row list and hooks their events. Adopted items are tracked through AdoptVisualAuthoredItem; MenuItem adopts its SubItemContainerInstance children the same way. Adoption runs only on assignment, so later direct panel adds follow the normal panel path.
Adoption happens only while Items is the control's own default collection. Once Items has been assigned (a bound ObservableCollection, for example), CanAdoptVisualAuthoredItems is false: authored rows are taken out of the new panel (put back when the Visual is removed) and a MenuItem leaves its authored sub-items alone, so the assigned collection is never written to by a Visual swap.
On a Visual swap, the old Visual's adopted items are dropped from Items and items added in code are re-added after the new Visual's own children. Rows for data objects are recreated, and a ListBox keeps its selection by data object.
A direct InnerPanel.Children.Move (hot reload does this) reaches HandleInnerPanelChildMovedExternally. ListBox syncs Items/ListBoxItems only for self-backed rows (DataObject == row); a data-backed row's move leaves both collections untouched. Code that moves the panel and syncs itself sets IsMovingInnerPanelChildInternally around the move so the sync doesn't run twice.
4. Index alignment assumption
HandleItemSelected resolves the data object via Items[ListBoxItemsInternal.IndexOf(listBoxItem)]. If Items and ListBoxItems have drifted (any of the above cases), selection silently fails or selects the wrong item — the check clickedIndex >= Items.Count causes an early return.
5. AssignListBoxEvents idempotency
ListBoxItem.AssignListBoxEvents is guarded by hasHadListBoxEventsAssigned. A ListBoxItem that bypasses normal item creation (e.g., added to InnerPanel directly without going through Items) may or may not have its events assigned. If events are missing, the item renders but clicking it produces no selection change.
Authoring Items In The Gum Tool
Items placed in a ListBox, ComboBox or any container instance in the tool are parented to the instance's Default Slot, never to the instance itself: the demo screens set ListBoxItemInstance.Parent to ResolutionBox.InnerPanelInstance, not ResolutionBox. When writing a screen's .gusj or .gusx by hand (or generating one), read the component's Default Slot and parent to that child; a direct child of the control bypasses InnerPanel and the items never appear in the list. See docs/gum-tool/gum-elements/component/default-child-container.md.
Selection
SelectedItems is an ObservableCollection<object> (not replaceable, only modified). SelectedObject and SelectedIndex are convenience properties that read/write the first entry in SelectedItems.
SyncIsSelectedFromSelectedItems walks ListBoxItemsInternal and reconciles IsSelected on each item. It runs whenever SelectedItems changes or SelectedObject/SelectedIndex are set.
SelectionMode controls click behavior: Single (default), Multiple (each click toggles), Extended (Ctrl/Shift modifier keys). Gamepad/keyboard input always uses single-selection behavior regardless of mode.
Selection resolves rows through ListBoxItem.DataObject, so every row-creation path must set it: CreateNewItemFrameworkElement and HandleCreatedItemVisual (the VisualTemplate path) both do. A row that removal discards while selected is reported through HandleCollectionItemsRemoved, which raises SelectionChanged with RemovedItems; ComboBox relies on that event to clear its text.
DisplayMemberPath
When set, DisplayMemberPath causes listBoxItem.UpdateToObject(property_value_as_string) instead of UpdateToObject(the_object_itself). This applies both on initial creation and when DisplayMemberPath is changed after items are already loaded.
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
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.

