gum-tool-tree-view

---

name: gum-tool-tree-view description: Gum main element tree view (Screens/Components/Standard/Behaviors panel). Triggers: tree view icons, ImageList, ElementTreeViewManager, ElementTreeViewCreator, MainTreeViewPlugin, MultiSelectTreeView, node add/refresh/theming. For '!' overlay see gum-tool-errors; for selection plumbing see gum-tool-selection.

Gum Tool Tree View Reference

The element tree view is the left-hand panel listing Screens, Components, Standard Elements, Behaviors, and the instances inside an open element. It is a WinForms MultiSelectTreeView hosted inside a WPF WindowsFormsHost.

Key types

• MultiSelectTreeView (Gum/CommonFormsAndControls/MultiSelectTreeView.cs) — derived from System.Windows.Forms.TreeView. Owns the underlying ImageList field _elementTreeImages (initialized empty in InitializeComponent). Exposed as ElementTreeImageList.
• ElementTreeViewCreator (Gum/Plugins/InternalPlugins/TreeView/ElementTreeViewCreator.cs) — builds the WPF Grid containing the tree view, search box, collapse buttons, and flat search list. Owns icon loading/tinting.
• ElementTreeViewManager (Gum/Plugins/InternalPlugins/TreeView/ElementTreeViewManager.cs) — constructor-injected (not a .Self singleton). Builds, refreshes, and selects nodes. This is the bloated central class — most icon assignments happen here, via TreeNodeImageIndices/TreeNodeImageLogic (Tools/Gum.Presentation/Managers/, headless — no System.Windows.Forms). Its own node-construction/search/refresh/selection logic is ITreeNode/ITreeNodeMutable-typed, delegating to headless twins keyed off IElementTreeRoots in Tools/Gum.Presentation/Managers/; ElementTreeViewManager.RightClick.cs (its sibling partial) is fully ITreeNode-clean too. MultiSelectTreeView, TreeNodeWrapper (the adapter seam), and GumTreeNode's GetFullFilePath() remain WinForms-typed — the latter still calls a WinForms-only helper in TreeNodeExtensionMethods at the bottom of ElementTreeViewManager.cs, since porting it headless would also require changing TreeNodeWrapper.
• MainTreeViewPlugin — wires plugin events (InstanceAdd, ElementSelected, VariableSet, AfterUndo, etc.) to ElementTreeViewManager.RefreshUi(...) and to UpdateErrorIndicatorsForElement(...).
• TreeViewStateService — captures/restores expanded-node state across sessions via user project settings.

Icon system

Tree-view icons are one of three icon pipelines in Gum (PNG ImageList here; GumIcon/PathGeometry for other WPF chrome; sprite sheet for Forms runtime). For the umbrella overview and routing, see gum-icons.

How icons end up in the ImageList

The ImageList is not populated at construction. The flow:

1. MultiSelectTreeView..ctor creates an empty ImageList (_elementTreeImages) with Depth32Bit and transparent color.
2. ElementTreeViewCreator.CreateObjectTreeView assigns ObjectTreeView.ImageList = ObjectTreeView.ElementTreeImageList.
3. ApplyThemeColors() calls UpdateTreeviewIcons(scale). This is the real loader — it runs on theme apply and on font-size change. It:
   • Calls InjectDynamicIcons() to load PNGs from pack://application:,,,/Gum;component/Content/Icons/... into _originalImages (Dictionary<string, Image>), keyed by filename. Idempotent — TryInjectIcon early-outs if the key exists.
   • Calls GetCurrentColorMap() to read theme resources (Frb.Colors.Icon.Manilla/Green/Blue/Red/Purple) and map them to icon keys.
   • Calls BuildTintedImageList(...) which, for each original image, resizes and tints in one pass via a ColorMatrix (white-source images are multiplied by the tint RGB), and adds to a fresh ImageList. The tree view's ImageList is replaced wholesale each call.
   • Forces ObjectTreeView.Indent = baseImageSize because on certain .NET versions the indent does not auto-adjust on first load.

The icons are intentionally white/grayscale source PNGs so they can be re-tinted by the theme.

ImageIndex constants

Defined as public const int on TreeNodeImageIndices (Tools/Gum.Presentation/Managers/TreeNodeImageIndices.cs); ElementTreeViewManager consumes them via using static. They map to insertion order in InjectDynamicIcons() — the order of the TryInjectIcon calls must match these indices:

Index	Constant	File key
0	TransparentImageIndex	transparent.png
1	FolderImageIndex	Folder.png
2	ComponentImageIndex	Component.png
3	InstanceImageIndex	Instance.png
4	ScreenImageIndex	Screen.png
5	StandardElementImageIndex	StandardElement.png
6	ExclamationIndex	redExclamation.png
7	StateImageIndex	state.png
8	BehaviorImageIndex	behavior.png
9	DerivedInstanceImageIndex	InheritedInstance.png
10	LockedInstanceImageIndex	instance_locked.png

Authoring new icons (artist-facing)

• Author at 512×512 PNG, white-on-transparent (alpha for shading; never use non-white RGB — the runtime tints by RGB multiplication).
• Theme color (Manilla/Green/Blue/Red/Purple) is chosen on the code side, not by the artist.
• SVG masters (if any) are not auto-converted to PNGs for the tree view. The GumFigmaIconRipper only processes Gum/Content/Svg/*.svg into XAML geometries for the variable-grid icons, not this pipeline. Export PNGs manually; keep SVG sources in Gum/Content/Svg/TreeView/ if desired.

Adding a new icon

1. Drop the PNG into Gum/Content/Icons/UpdatedTreeViewIcons/. Set the build action so it ships in the WPF resource pack.
2. Add a TryInjectIcon("YourKey.png", "pack://...") call to InjectDynamicIcons at the position matching the next image index.
3. Add a public const int YourImageIndex = N; to TreeNodeImageIndices.
4. If the icon should be theme-colored, add an entry to GetCurrentColorMap() keyed by the same filename. Otherwise it falls back to Frb.Colors.Primary.
5. Assign treeNode.ImageIndex = YourImageIndex; from wherever the node is created/refreshed.

Icon decision logic (state → ImageIndex)

The same node may swap between several icons over its lifetime. Call sites are scattered across ElementTreeViewManager; the per-type mapping tables and decision rules they call into are centralized in TreeNodeImageLogic (Tools/Gum.Presentation/Managers/TreeNodeImageLogic.cs). Hot spots:

• Element nodes (UpdateErrorIndicatorsForElement, ElementTreeViewManager.cs ~L447): picks Screen / Component / StandardElement by type, then overrides to Exclamation if IsSourceFileMissing or has errors.
• Instance nodes (AddTreeNodeForInstance ~L1790, instance refresh ~L1720): default Instance; LockedInstance if instance.Locked; Exclamation if BaseType element is missing/missing source; DerivedInstance if instance.DefinedByBase (instance contributed by a base element).
• Folder containers (Screens / Components / Standard / Behaviors top-level + subfolders): always FolderImageIndex.

MainTreeViewPlugin wires VariableSet → if variableName == nameof(instance.Locked), calls RefreshUi(instance) so the lock icon updates immediately.

Theming / DPI / font-size scaling

UpdateTreeviewIcons(scale) is called from:

• ApplyThemeColors() — runs on initial creation and theme changes.
• MainTreeViewPlugin.Receive(UiBaseFontSizeChangedMessage) → UpdateCollapseButtonSizes (collapse buttons use Material Design PackIcon, separate from the tree image list).

Base size is 16px * (DpiX / 96f) * scale. Re-tinting and resizing happen together; any change to theme color or font size rebuilds the entire ImageList.

Tree refresh model

ElementTreeViewManager.RefreshUi() is the workhorse — overloads accept an IInstanceContainer, an InstanceSave, or nothing (full rebuild). It performs diff-based updates: existing tree nodes are reused and only their ImageIndex / position / Tag / Text are updated when they differ. This matters because:

• Replacing nodes wholesale would lose expansion state and selection.
• ImageIndex is only assigned when it differs from the desired value (avoids redraw flicker).
• Expanded-instance state is captured before edits and reapplied after (expandedInstances local).

Plugin events that trigger refresh (MainTreeViewPlugin.AssignEvents):

• Add/Delete/Duplicate/Reload of elements, instances, behaviors, categories, states.
• ProjectLoad — full rebuild + TreeViewStateService.LoadAndApplyState.
• AfterUndo — refreshes selected behavior + error indicators.
• VariableSet — error indicator refresh, plus instance refresh when Locked changes.
• RefreshElementTreeView — explicit refresh request from other plugins.

Gotchas

• Icon cache lives in _originalImages on ElementTreeViewCreator, not on MultiSelectTreeView. The image list on the tree view is replaced; the cached source Image objects persist across rebuilds.
• The PNGs are tinted; original is expected to be white. A new colored icon will be multiplied by the theme color and look wrong. Author icons as alpha-on-white.
• Index constants and TryInjectIcon call order are coupled. Inserting a new icon in the middle of the list shifts every subsequent constant — easier to append.
• Tag distinguishes node types: folder/container nodes have Tag == null; element nodes have an ElementSave/BehaviorSave; instance nodes have an InstanceSave. Used by CollapseElementNodesRecursively and selection logic.
• MainTreeViewPlugin suppresses re-entrant selection cascades via _elementTreeViewManager.SuppressCallAfterClickSelect.
• Hot-tracking + custom hover/selected colors are theme-driven via Frb.Brushes.Primary*. The tree view does not use the OS default selection colors.