Table of Contents

Class TreeView

Namespace
Icy.UI.Controls
Assembly
IcyUI.dll

Shows hierarchical data as an indented, expandable list. Only visible rows are realized, however large the tree.

[ContentProperty("Items")]
public class TreeView : Control, INotifyPropertyChanging, IBindingTarget, INotifyPropertyChanged, INotifyFocusChanged, IContainerLayout
Inheritance
TreeView
Implements
Inherited Members
Extension Methods

Remarks

Where the roots come from: ItemsSource, or the inline Items (not both).

Where an item's children come from (the first configured source wins):

  1. ChildrenSelector, when set;
  2. otherwise the ChildrenPath of the item's template;
  3. otherwise Children, for a TreeViewNode;
  4. otherwise none.

Expansion state belongs to the tree, keyed by item reference. For a TreeViewNode it's the node's own IsExpanded. An item that appears under two parents is expanded in both places.

Internally the tree keeps the visible rows as a flat list. Expanding or collapsing an item inserts or removes its visible subtree as one change, and only the rows on screen have containers (see ItemsControl). null items aren't supported.

Constructors

TreeView()

Initializes a new instance of the TreeView class.

public TreeView()

Properties

ChildrenSelector

Gets or sets a function that returns an item's children, or null for none. When set, it's the only source of children.

public Func<object, IEnumerable?>? ChildrenSelector { get; set; }

Property Value

Func<object, IEnumerable>

Indent

Gets or sets how far each level is indented, in layout units. Defaults to 16.

[Range(0, Infinity)]
public float Indent { get; set; }

Property Value

float

Exceptions

ArgumentOutOfRangeException

The value is negative.

IsItemSelectable

Gets or sets a function that decides whether an item can be selected. When unset, a TreeViewNode uses its IsSelectable and every other item is selectable.

public Func<object, bool>? IsItemSelectable { get; set; }

Property Value

Func<object, bool>

Remarks

Tapping a non-selectable item with children expands or collapses it instead.

ItemTemplate

Gets or sets the template for each row's content. A HierarchicalDataTemplate also supplies children. Without one, a row shows its item's text.

public DataTemplate? ItemTemplate { get; set; }

Property Value

DataTemplate

ItemTemplateSelector

Gets or sets a function that picks a template per item, overriding ItemTemplate.

public Func<object, DataTemplate>? ItemTemplateSelector { get; set; }

Property Value

Func<object, DataTemplate>

Items

Gets the inline root items, the markup content of the tree. Used when ItemsSource isn't set.

public ObservableCollection<object> Items { get; }

Property Value

ObservableCollection<object>

Exceptions

InvalidOperationException

An item is added while ItemsSource is set.

ItemsSource

Gets or sets the root items. An INotifyCollectionChanged source is followed live.

public IEnumerable? ItemsSource { get; set; }

Property Value

IEnumerable

Exceptions

InvalidOperationException

A source is set while Items isn't empty.

SelectedItem

Gets or sets the selected data item, or null for none.

[BindingOverride(BindingMode.TwoWay)]
public object? SelectedItem { get; set; }

Property Value

object

Remarks

  • Setting a selectable item reveals it (see Reveal(object)) and selects it.
  • Setting an item that isn't in the tree, or can't be selected, clears the selection.
  • Collapsing an ancestor keeps the selection; removing the item from the data clears it.

Methods

Collapse(object)

Collapses item. Its descendants keep their own expansion, so expanding it again restores the subtree as it was.

public void Collapse(object item)

Parameters

item object

The item.

Exceptions

ArgumentNullException

item is null.

Expand(object)

Expands item. Every visible row of it shows its children. An item that isn't visible keeps the state for when it becomes visible.

public void Expand(object item)

Parameters

item object

The item.

Exceptions

ArgumentNullException

item is null.

IsExpanded(object)

Gets a value indicating whether item is expanded.

public bool IsExpanded(object item)

Parameters

item object

The item.

Returns

bool

true when the item shows its children (or would, once visible).

Exceptions

ArgumentNullException

item is null.

OnActivate()

Expands or collapses the current row (Enter, gamepad A).

protected override bool OnActivate()

Returns

bool

true when the current row has children and was toggled.

OnAttached()

Raises the Attached event.

protected override void OnAttached()

Remarks

Propagates Canvas to every element in GetVisualChildren() - this is what makes attaching a whole pre-built subtree (the common pattern: build children, then attach the root once via Add(UIElement)) reach every descendant, not just the immediate root. Each child's own Canvas setter recurses into its children the same way, so this walks the full subtree regardless of depth. Container-specific child-add paths (e.g. OnChildAdded(object?, GenericEventArgs<UIElement>)) still assign Canvas directly for children added after the parent is already attached - this cascade is what covers everything built beforehand.

OnDetached()

Raises the Detached event.

protected override void OnDetached()

Remarks

Propagates null to every element in GetVisualChildren(), mirroring OnAttached() - see its remarks.

OnNavigate(Vector2)

Moves through the rows, following the usual tree conventions.

protected override bool OnNavigate(Vector2 direction)

Parameters

direction Vector2

The pressed direction.

Returns

bool

true when the tree used the press.

Remarks

  • Up and Down move to the previous and next row.
  • Right expands a collapsed branch, or moves from an expanded branch to its first child.
  • Left collapses an expanded branch, or moves from a child to its parent.

A press the tree can't use isn't claimed, so focus moves on to the next control: Up on the first row, Down on the last row, Right on a leaf, and Left on a collapsed root.

Reveal(object)

Makes item visible: expands every ancestor on its path from a root, then scrolls its row into view.

public bool Reveal(object item)

Parameters

item object

The item.

Returns

bool

false when the item isn't anywhere in the tree.

Remarks

An item that is already visible only scrolls. Otherwise the tree searches its data depth-first through child resolution, which is O(n) in the number of items; the search never revisits an item, so cyclic data terminates.

Exceptions

ArgumentNullException

item is null.

Events

ItemCollapsed

Occurs when an item is collapsed, through the API, the UI, or a visible TreeViewNode's IsExpanded.

public event EventHandler<TreeViewItemEventArgs>? ItemCollapsed

Event Type

EventHandler<TreeViewItemEventArgs>

ItemExpanded

Occurs when an item is expanded, through the API, the UI, or a visible TreeViewNode's IsExpanded.

public event EventHandler<TreeViewItemEventArgs>? ItemExpanded

Event Type

EventHandler<TreeViewItemEventArgs>

SelectionChanged

Occurs when SelectedItem changes.

public event EventHandler? SelectionChanged

Event Type

EventHandler