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

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.

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
  1. Very specific:

    When set, DisplayMemberPath causes listBoxItem.UpdateToObject(property_value_as_string) instead of UpdateToObject(the_object_itself).

    line 117

≈ “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.

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

ItemsControl and ListBox Reference

Key Files

FilePurpose
MonoGameGum/Forms/Controls/ItemsControl.csBase class: Items property, template resolution, InnerPanel sync
MonoGameGum/Forms/Controls/ListBox.csAdds ListBoxItems tracking, selection, and ListBoxItem creation
MonoGameGum/Forms/Controls/ListBoxItem.csIndividual row control; holds IsSelected, IsHighlighted, events
MonoGameGum/Forms/VisualTemplate.csCreates GraphicalUiElement instances (visual-first)
MonoGameGum/Forms/FrameworkElementTemplate.csCreates FrameworkElement instances (forms-first)

The Two Collections

Items and ListBoxItems are separate and can get out of sync.

  • Items (IList, default ObservableCollection<object>) — the logical data collection. Can hold anything: strings, view models, ListBoxItem instances, or any FrameworkElement / GraphicalUiElement.
  • ListBoxItems (ReadOnlyCollection<ListBoxItem>) — the visual row controls actually shown. Wraps ListBoxItemsInternal (a List<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:

  1. HandleItemsCollectionChanged — responds to Items. Creates or locates a visual and inserts it into InnerPanel.Children.
  2. HandleInnerPanelCollectionChanged — responds to InnerPanel.Children. Calls HandleCollectionNewItemCreated(frameworkElement, index).
  3. HandleCollectionNewItemCreated (ListBox override) — if the item is a ListBoxItem, inserts it into ListBoxItemsInternal and calls AssignListBoxEvents.

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 ItemsWhat happens
FrameworkElementIts .Visual is inserted into InnerPanel directly — no new wrapper created
GraphicalUiElementInserted into InnerPanel directly — no wrapper
Any other data object AND VisualTemplate is setVisualTemplate.CreateContent(item, createFormsInternally:false) is called; result inserted
Any other data object, no VisualTemplateCreateNewItemFrameworkElement(item) is called

ListBox overrides CreateNewItemFrameworkElement with additional logic:

Item typeListBox behavior
ListBoxItemUsed as-is — no template, no wrapping
Anything elseCalls 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>, or Func<object, bool, GraphicalUiElement>.
  • Used by CreateNewVisual. When constructed from a Type, calls it with (true, false) — createFormsInternally:false prevents 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 Type or Func<FrameworkElement>.
  • Used by CreateNewItemFrameworkElement. For ListBox, the result must be a ListBoxItem subclass 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.

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.