Class TreeView<T>

Hierarchical tree view with expandable branches. Branch objects are dynamically determined when expanded using a user defined ITreeBuilder<T> See TreeView Deep Dive for more information.
Inheritance
System.Object
Responder
View
TreeView<T>
TreeView
Implements
System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Terminal.Gui
Assembly: Terminal.Gui.dll
Syntax
public class TreeView<T> : View, IDisposable, ISupportInitializeNotification, ISupportInitialize, ITreeView where T : class
Type Parameters
Name Description
T

Constructors

TreeView()

Creates a new tree view with absolute positioning. Use AddObjects(IEnumerable<T>) to set set root objects for the tree. Children will not be rendered until you set TreeBuilder
Declaration
public TreeView()

TreeView(ITreeBuilder<T>)

Initialises TreeBuilder.Creates a new tree view with absolute positioning. Use AddObjects(IEnumerable<T>) to set set root objects for the tree.
Declaration
public TreeView(ITreeBuilder<T> builder)
Parameters
Type Name Description
ITreeBuilder<T> builder

Fields

NoBuilderError

Error message to display when the control is not properly initialized at draw time (nodes added but no tree builder set)
Declaration
public static ustring NoBuilderError
Field Value
Type Description
NStack.ustring

Properties

AllowLetterBasedNavigation

True makes a letter key press navigate to the next visible branch that begins with that letter/digit
Declaration
public bool AllowLetterBasedNavigation { get; set; }
Property Value
Type Description
System.Boolean

AspectGetter

Returns the string representation of model objects hosted in the tree. Default implementation is to call System.Object.ToString()
Declaration
public AspectGetterDelegate<T> AspectGetter { get; set; }
Property Value
Type Description
AspectGetterDelegate<T>

ColorGetter

Delegate for multi colored tree views. Return the ColorScheme to use for each passed object or null to use the default.
Declaration
public Func<T, ColorScheme> ColorGetter { get; set; }
Property Value
Type Description
System.Func<T, ColorScheme>

ContentHeight

The current number of rows in the tree (ignoring the controls bounds)
Declaration
public int ContentHeight { get; }
Property Value
Type Description
System.Int32

DesiredCursorVisibility

Get / Set the wished cursor when the tree is focused
Declaration
public CursorVisibility DesiredCursorVisibility { get; set; }
Property Value
Type Description
CursorVisibility

MultiSelect

True to allow multiple objects to be selected at once
Declaration
public bool MultiSelect { get; set; }
Property Value
Type Description
System.Boolean

ObjectActivationButton

Mouse event to trigger ObjectActivated. Defaults to double click (Button1DoubleClicked). Set to null to disable this feature.
Declaration
public MouseFlags? ObjectActivationButton { get; set; }
Property Value
Type Description
System.Nullable<MouseFlags>

ObjectActivationKey

Key which when pressed triggers ObjectActivated. Defaults to Enter
Declaration
public Key ObjectActivationKey { get; set; }
Property Value
Type Description
Key

Objects

The root objects in the tree, note that this collection is of root objects only
Declaration
public IEnumerable<T> Objects { get; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<T>

ScrollOffsetHorizontal

The amount of tree view that has been scrolled to the right (horizontally)
Declaration
public int ScrollOffsetHorizontal { get; set; }
Property Value
Type Description
System.Int32
Remarks
Setting a value of less than 0 will result in a offset of 0. To see changes in the UI call SetNeedsDisplay()

ScrollOffsetVertical

The amount of tree view that has been scrolled off the top of the screen (by the user scrolling down)
Declaration
public int ScrollOffsetVertical { get; set; }
Property Value
Type Description
System.Int32
Remarks
Setting a value of less than 0 will result in a offset of 0. To see changes in the UI call SetNeedsDisplay()

SelectedObject

The currently selected object in the tree. When MultiSelect is true this is the object at which the cursor is at
Declaration
public T SelectedObject { get; set; }
Property Value
Type Description
T

Style

Contains options for changing how the tree is rendered
Declaration
public TreeStyle Style { get; set; }
Property Value
Type Description
TreeStyle

TreeBuilder

Determines how sub branches of the tree are dynamically built at runtime as the user expands root nodes
Declaration
public ITreeBuilder<T> TreeBuilder { get; set; }
Property Value
Type Description
ITreeBuilder<T>

Methods

ActivateSelectedObjectIfAny()

Triggers the ObjectActivated event with the SelectedObject.

This method also ensures that the selected object is visible

Declaration
public void ActivateSelectedObjectIfAny()

AddObject(T)

Adds a new root level object unless it is already a root of the tree
Declaration
public void AddObject(T o)
Parameters
Type Name Description
T o

AddObjects(IEnumerable<T>)

Adds many new root level objects. Objects that are already root objects are ignored
Declaration
public void AddObjects(IEnumerable<T> collection)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<T> collection Objects to add as new root level objects

AdjustSelection(Int32, Boolean)

The number of screen lines to move the currently selected object by. Supports negative offset. Each branch occupies 1 line on screen
Declaration
public void AdjustSelection(int offset, bool expandSelection = false)
Parameters
Type Name Description
System.Int32 offset Positive to move the selection down the screen, negative to move it up
System.Boolean expandSelection True to expand the selection (assuming MultiSelect is enabled). False to replace
Remarks
If nothing is currently selected or the selected object is no longer in the tree then the first object in the tree is selected instead

AdjustSelectionToBranchEnd()

Moves the selection to the last child in the currently selected level
Declaration
public void AdjustSelectionToBranchEnd()

AdjustSelectionToBranchStart()

Moves the selection to the first child in the currently selected level
Declaration
public void AdjustSelectionToBranchStart()

AdjustSelectionToNextItemBeginningWith(Char, StringComparison)

Moves the SelectedObject to the next item that begins with character

This method will loop back to the start of the tree if reaching the end without finding a match

Declaration
public void AdjustSelectionToNextItemBeginningWith(char character, StringComparison caseSensitivity = StringComparison.CurrentCultureIgnoreCase)
Parameters
Type Name Description
System.Char character The first character of the next item you want selected
System.StringComparison caseSensitivity Case sensitivity of the search

CanExpand(T)

Returns true if the given object o is exposed in the tree and can be expanded otherwise false
Declaration
public bool CanExpand(T o)
Parameters
Type Name Description
T o
Returns
Type Description
System.Boolean

ClearObjects()

Removes all objects from the tree and clears SelectedObject
Declaration
public void ClearObjects()

Collapse()

Collapses the SelectedObject
Declaration
public void Collapse()

Collapse(T)

Collapses the supplied object if it is currently expanded
Declaration
public void Collapse(T toCollapse)
Parameters
Type Name Description
T toCollapse The object to collapse

CollapseAll()

Collapses all root nodes in the tree
Declaration
public void CollapseAll()

CollapseAll(T)

Collapses the supplied object if it is currently expanded. Also collapses all children branches (this will only become apparent when/if the user expands it again)
Declaration
public void CollapseAll(T toCollapse)
Parameters
Type Name Description
T toCollapse The object to collapse

CollapseImpl(T, Boolean)

Implementation of Collapse(T) and CollapseAll(T). Performs operation and updates selection if disapeared
Declaration
protected void CollapseImpl(T toCollapse, bool all)
Parameters
Type Name Description
T toCollapse
System.Boolean all

CursorLeft(Boolean)

Determines systems behaviour when the left arrow key is pressed. Default behaviour is to collapse the current tree node if possible otherwise changes selection to current branches parent
Declaration
protected virtual void CursorLeft(bool ctrl)
Parameters
Type Name Description
System.Boolean ctrl

EnsureVisible(T)

Adjusts the ScrollOffsetVertical to ensure the given model is visible. Has no effect if already visible
Declaration
public void EnsureVisible(T model)
Parameters
Type Name Description
T model

Expand()

Expands the currently SelectedObject
Declaration
public void Expand()

Expand(T)

Expands the supplied object if it is contained in the tree (either as a root object or as an exposed branch object)
Declaration
public void Expand(T toExpand)
Parameters
Type Name Description
T toExpand The object to expand

ExpandAll()

Fully expands all nodes in the tree, if the tree is very big and built dynamically this may take a while (e.g. for file system)
Declaration
public void ExpandAll()

ExpandAll(T)

Expands the supplied object and all child objects
Declaration
public void ExpandAll(T toExpand)
Parameters
Type Name Description
T toExpand The object to expand

GetAllSelectedObjects()

Returns SelectedObject (if not null) and all multi selected objects if MultiSelect is true
Declaration
public IEnumerable<T> GetAllSelectedObjects()
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

GetChildren(T)

Returns the currently expanded children of the passed object. Returns an empty collection if the branch is not exposed or not expanded
Declaration
public IEnumerable<T> GetChildren(T o)
Parameters
Type Name Description
T o An object in the tree
Returns
Type Description
System.Collections.Generic.IEnumerable<T>

GetContentWidth(Boolean)

Returns the maximum width line in the tree including prefix and expansion symbols
Declaration
public int GetContentWidth(bool visible)
Parameters
Type Name Description
System.Boolean visible True to consider only rows currently visible (based on window bounds and ScrollOffsetVertical. False to calculate the width of every exposed branch in the tree
Returns
Type Description
System.Int32

GetObjectOnRow(Int32)

Returns the object in the tree list that is currently visible at the provided row. Returns null if no object is at that location. If you have screen coordinates then use ScreenToView(Int32, Int32) to translate these into the client area of the TreeView<T>.
Declaration
public T GetObjectOnRow(int row)
Parameters
Type Name Description
System.Int32 row The row of the Bounds of the TreeView<T>
Returns
Type Description
T The object currently displayed on this row or null

GetObjectRow(T)

Returns the Y coordinate within the Bounds of the tree at which toFind would be displayed or null if it is not currently exposed (e.g. its parent is collapsed).

Note that the returned value can be negative if the TreeView is scrolled down and the toFind object is off the top of the view.

Declaration
public int? GetObjectRow(T toFind)
Parameters
Type Name Description
T toFind
Returns
Type Description
System.Nullable<System.Int32>

GetParent(T)

Returns the parent object of o in the tree. Returns null if the object is not exposed in the tree
Declaration
public T GetParent(T o)
Parameters
Type Name Description
T o An object in the tree
Returns
Type Description
T

GetScrollOffsetOf(T)

Returns the index of the object o if it is currently exposed (it's parent(s) have been expanded). This can be used with ScrollOffsetVertical and SetNeedsDisplay() to scroll to a specific object
Declaration
public int GetScrollOffsetOf(T o)
Parameters
Type Name Description
T o An object that appears in your tree and is currently exposed
Returns
Type Description
System.Int32 The index the object was found at or -1 if it is not currently revealed or not in the tree at all
Remarks
Uses the Equals method and returns the first index at which the object is found or -1 if it is not found

GoTo(T)

Changes the SelectedObject to toSelect and scrolls to ensure it is visible. Has no effect if toSelect is not exposed in the tree (e.g. its parents are collapsed)
Declaration
public void GoTo(T toSelect)
Parameters
Type Name Description
T toSelect

GoToEnd()

Changes the SelectedObject to the last object in the tree and scrolls so that it is visible
Declaration
public void GoToEnd()

GoToFirst()

Changes the SelectedObject to the first root object and resets the ScrollOffsetVertical to 0
Declaration
public void GoToFirst()

InvalidateLineMap()

Clears any cached results of Terminal.Gui.TreeView`1.BuildLineMap
Declaration
protected void InvalidateLineMap()

IsExpanded(T)

Returns true if the given object o is exposed in the tree and expanded otherwise false
Declaration
public bool IsExpanded(T o)
Parameters
Type Name Description
T o
Returns
Type Description
System.Boolean

IsSelected(T)

Returns true if the model is either the SelectedObject or part of a MultiSelect
Declaration
public bool IsSelected(T model)
Parameters
Type Name Description
T model
Returns
Type Description
System.Boolean

MouseEvent(MouseEvent)

Declaration
public override bool MouseEvent(MouseEvent me)
Parameters
Type Name Description
MouseEvent me
Returns
Type Description
System.Boolean
Overrides

MovePageDown(Boolean)

Moves the selection down by the height of the control (1 page).
Declaration
public void MovePageDown(bool expandSelection = false)
Parameters
Type Name Description
System.Boolean expandSelection True if the navigation should add the covered nodes to the selected current selection
Exceptions
Type Condition
System.NotImplementedException

MovePageUp(Boolean)

Moves the selection up by the height of the control (1 page).
Declaration
public void MovePageUp(bool expandSelection = false)
Parameters
Type Name Description
System.Boolean expandSelection True if the navigation should add the covered nodes to the selected current selection
Exceptions
Type Condition
System.NotImplementedException

OnEnter(View)

Declaration
public override bool OnEnter(View view)
Parameters
Type Name Description
View view
Returns
Type Description
System.Boolean
Overrides

OnObjectActivated(ObjectActivatedEventArgs<T>)

Raises the ObjectActivated event
Declaration
protected virtual void OnObjectActivated(ObjectActivatedEventArgs<T> e)
Parameters
Type Name Description
ObjectActivatedEventArgs<T> e

OnSelectionChanged(SelectionChangedEventArgs<T>)

Raises the SelectionChanged event
Declaration
protected virtual void OnSelectionChanged(SelectionChangedEventArgs<T> e)
Parameters
Type Name Description
SelectionChangedEventArgs<T> e

PositionCursor()

Positions the cursor at the start of the selected objects line (if visible)
Declaration
public override void PositionCursor()
Overrides

ProcessKey(KeyEvent)

Declaration
public override bool ProcessKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent
Returns
Type Description
System.Boolean
Overrides

RebuildTree()

Rebuilds the tree structure for all exposed objects starting with the root objects. Call this method when you know there are changes to the tree but don't know which objects have changed (otherwise use RefreshObject(T, Boolean))
Declaration
public void RebuildTree()

Redraw(Rect)

Declaration
public override void Redraw(Rect bounds)
Parameters
Type Name Description
Rect bounds
Overrides

RefreshObject(T, Boolean)

Refreshes the state of the object o in the tree. This will recompute children, string representation etc
Declaration
public void RefreshObject(T o, bool startAtTop = false)
Parameters
Type Name Description
T o
System.Boolean startAtTop True to also refresh all ancestors of the objects branch (starting with the root). False to refresh only the passed node
Remarks
This has no effect if the object is not exposed in the tree.

Remove(T)

Removes the given root object from the tree
Declaration
public void Remove(T o)
Parameters
Type Name Description
T o
Remarks
If o is the currently SelectedObject then the selection is cleared

ScrollDown()

Scrolls the view area down a single line without changing the current selection
Declaration
public void ScrollDown()

ScrollUp()

Scrolls the view area up a single line without changing the current selection
Declaration
public void ScrollUp()

SelectAll()

Selects all objects in the tree when MultiSelect is enabled otherwise does nothing
Declaration
public void SelectAll()

Events

ObjectActivated

This event is raised when an object is activated e.g. by double clicking or pressing ObjectActivationKey
Declaration
public event Action<ObjectActivatedEventArgs<T>> ObjectActivated
Event Type
Type Description
System.Action<ObjectActivatedEventArgs<T>>

SelectionChanged

Called when the SelectedObject changes
Declaration
public event EventHandler<SelectionChangedEventArgs<T>> SelectionChanged
Event Type
Type Description
System.EventHandler<SelectionChangedEventArgs<T>>

Implements

System.IDisposable
System.ComponentModel.ISupportInitializeNotification
System.ComponentModel.ISupportInitialize