Gum Tool Tree View

Gum Tool Tree View Reference

The left-hand panel listing Screens, Components, Standard Elements, Behaviors, and the instances inside an open element. The model and logic are framework-neutral in Tool/TreeViewPlugin.Core (net10.0, shared by both heads); each head supplies only the panel, through IElementTreeView.

File map

The states tree (center-top "States" tab) shares StateTreePluginBase, StateTreeRightClickService and StateTreeKeyboardHandler in Tools/Gum.Presentation/Plugins/InternalPlugins/StatePlugin/; MainStatePlugin (WPF) and AvaloniaStatePlugin only build their tree control.

ElementTreeViewManager and its RightClick partial speak ITreeNode/ITreeNodeMutable, delegating to headless twins in Tools/Gum.Presentation/Managers/ (TreeNodeImageLogic, the TreeNode*Extensions families, TreeNodeExpansionPaths). Prefer adding logic there over growing the manager.

Selection is on the model, not the container

TreeView enforces a single selected item and clears the previous one on every change, so TreeViewItem.IsSelected is deliberately never set. TreeSelectionModel tracks the selection and the row visuals bind to GumTreeNode.IsSelected. The Avalonia tree goes further and is a flat, virtualized row list rather than a TreeView. Consequences:

• Keyboard navigation is TreeSelectionModel.HandleKeyDown, called from each control's key handler.
• A change to selection behavior goes in TreeSelectionModel (with a test), never in one head's control.
• IsExpanded is ordinary two-way bound state, so expansion survives a rebuild without being captured and replayed.

Icons

TreeIconRegistry maps an index (the shared TreeNodeImageIndices constants, produced by the headless TreeNodeImageLogic) to a pack URI plus a theme color key; TreeNodeIcon renders the pair.

• Source PNGs must be white-on-transparent, alpha carrying the shading. Tinting fills a shape with the theme brush and uses the artwork as an OpacityMask, so a colored source multiplies wrong.
• Adding an icon is a constant in TreeNodeImageIndices plus an entry in TreeIconRegistry — in any position. The numbering is not tied to load order.
• Icons re-tint on theme change via TreeIconRegistry.NotifyThemeChanged(); nothing is regenerated.

Refresh model

RefreshUi() is diff-based — existing nodes are reused and only differing ImageIndex/position/Tag/ Text are written. Replacing nodes wholesale would drop selection and scroll position.

Tag distinguishes node kinds: folder/container nodes have Tag == null; element nodes carry an ElementSave/BehaviorSave; instance nodes an InstanceSave.

MainTreeViewPlugin.HandleElementImported requests a refresh through a RefreshCoalescer rather than calling RefreshUi() directly, so importing N elements in one batch (Forms theme, .gumx import) produces one refresh instead of N.

Gotchas

• Reordering within one collection must be remove-then-insert. GumTreeNodeCollection throws if a node is inserted into the collection it already belongs to, because detaching first would shift the index the caller computed. Reparenting across collections is a plain add.
• Drag payloads travel in TreeDragPayload, not on the drag data. Gum's *Save types aren't [Serializable], so anything put on a WPF data object comes back null; the data carries only a marker format (TreeDragPayload.DataFormat in WPF, AvaloniaDragFormats.TreeNodes in Avalonia). Both heads' canvas drop readers and search-result lists use the same static.
• ITreeNode.FullPath is backslash-separated. CopyPasteLogic slices a "Components\\" prefix off it.
• Persisted expansion state is forward-slash-joined node Text paths (TreeNodeExpansionPaths). Changing either the separator or the use of Text silently discards every user's saved state.
• Virtualization is off (the WPF TreeView default). That is what makes GumTreeView.ContainerFor/EnsureVisible reliable — turning it on would break container lookup for off-screen nodes.
• GumTreeView.EnsureVisible defers to a Loaded dispatcher callback, since a newly-expanded ancestor's child has no container until layout runs.