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
object
Responder
View
TreeView<T>
TreeView
Implements
Inherited Members
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

| Edit this page View Source

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()
| Edit this page View Source

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

| Edit this page View Source

Filter

Interface for filtering which lines of the tree are displayed e.g. to provide text searching. Defaults to null (no filtering).
Declaration
public ITreeViewFilter<T> Filter
Field Value
Type Description
ITreeViewFilter<T>
| Edit this page View Source

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
ustring

Properties

| Edit this page View Source

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
bool
| Edit this page View Source

AspectGetter

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

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
Func<T, ColorScheme>
| Edit this page View Source

ContentHeight

The current number of rows in the tree (ignoring the controls bounds).
Declaration
public int ContentHeight { get; }
Property Value
Type Description
int
| Edit this page View Source

DesiredCursorVisibility

Get / Set the wished cursor when the tree is focused. Only applies when MultiSelect is true. Defaults to Invisible.
Declaration
public CursorVisibility DesiredCursorVisibility { get; set; }
Property Value
Type Description
CursorVisibility
| Edit this page View Source

KeystrokeNavigator

Gets the CollectionNavigator that searches the Objects collection as the user types.
Declaration
public CollectionNavigator KeystrokeNavigator { get; }
Property Value
Type Description
CollectionNavigator
| Edit this page View Source

MaxDepth

Maximum number of nodes that can be expanded in any given branch.
Declaration
public int MaxDepth { get; set; }
Property Value
Type Description
int
| Edit this page View Source

MultiSelect

True to allow multiple objects to be selected at once.
Declaration
public bool MultiSelect { get; set; }
Property Value
Type Description
bool
| Edit this page View Source

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
MouseFlags?
| Edit this page View Source

ObjectActivationKey

Key which when pressed triggers ObjectActivated. Defaults to Enter.
Declaration
public Key ObjectActivationKey { get; set; }
Property Value
Type Description
Key
| Edit this page View Source

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
IEnumerable<T>
| Edit this page View Source

ScrollOffsetHorizontal

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

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
int
Remarks
Setting a value of less than 0 will result in a offset of 0. To see changes in the UI call SetNeedsDisplay().
| Edit this page View Source

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
| Edit this page View Source

Style

Contains options for changing how the tree is rendered.
Declaration
public TreeStyle Style { get; set; }
Property Value
Type Description
TreeStyle
| Edit this page View Source

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

| Edit this page View Source

ActivateSelectedObjectIfAny()

Triggers the ObjectActivated event with the SelectedObject.

This method also ensures that the selected object is visible.

Declaration
public void ActivateSelectedObjectIfAny()
| Edit this page View Source

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
| Edit this page View Source

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
IEnumerable<T> collection Objects to add as new root level objects.
| Edit this page View Source

AdjustSelection(int, bool)

The number of screen lines to move the currently selected object by. Supports negative values. offset. Each branch occupies 1 line on screen.
Declaration
public void AdjustSelection(int offset, bool expandSelection = false)
Parameters
Type Name Description
int offset Positive to move the selection down the screen, negative to move it up
bool 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.
| Edit this page View Source

AdjustSelectionToBranchEnd()

Moves the selection to the last child in the currently selected level.
Declaration
public void AdjustSelectionToBranchEnd()
| Edit this page View Source

AdjustSelectionToBranchStart()

Moves the selection to the first child in the currently selected level.
Declaration
public void AdjustSelectionToBranchStart()
| Edit this page View Source

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
char character The first character of the next item you want selected.
StringComparison caseSensitivity Case sensitivity of the search.
| Edit this page View Source

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
bool
| Edit this page View Source

ClearObjects()

Removes all objects from the tree and clears SelectedObject.
Declaration
public void ClearObjects()
| Edit this page View Source

Collapse()

Collapses the SelectedObject
Declaration
public void Collapse()
| Edit this page View Source

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.
| Edit this page View Source

CollapseAll()

Collapses all root nodes in the tree.
Declaration
public void CollapseAll()
| Edit this page View Source

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.
| Edit this page View Source

CollapseImpl(T, bool)

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
bool all
| Edit this page View Source

CursorLeft(bool)

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
bool ctrl
| Edit this page View Source

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
| Edit this page View Source

Expand()

Expands the currently SelectedObject.
Declaration
public void Expand()
| Edit this page View Source

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.
| Edit this page View Source

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()
| Edit this page View Source

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.
| Edit this page View Source

GetAllSelectedObjects()

Returns SelectedObject (if not null) and all multi selected objects if MultiSelect is true
Declaration
public IEnumerable<T> GetAllSelectedObjects()
Returns
Type Description
IEnumerable<T>
| Edit this page View Source

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
IEnumerable<T>
| Edit this page View Source

GetContentWidth(bool)

Returns the maximum width line in the tree including prefix and expansion symbols.
Declaration
public int GetContentWidth(bool visible)
Parameters
Type Name Description
bool 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
int
| Edit this page View Source

GetObjectOnRow(int)

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(int, int) to translate these into the client area of the TreeView<T>.
Declaration
public T GetObjectOnRow(int row)
Parameters
Type Name Description
int row The row of the Bounds of the TreeView<T>.
Returns
Type Description
T The object currently displayed on this row or null.
| Edit this page View Source

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
int?
| Edit this page View Source

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
| Edit this page View Source

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
int 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.
| Edit this page View Source

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
| Edit this page View Source

GoToEnd()

Changes the SelectedObject to the last object in the tree and scrolls so that it is visible.
Declaration
public void GoToEnd()
| Edit this page View Source

GoToFirst()

Changes the SelectedObject to the first root object and resets the ScrollOffsetVertical to 0.
Declaration
public void GoToFirst()
| Edit this page View Source

InvalidateLineMap()

Clears any cached results of the tree state.
Declaration
public void InvalidateLineMap()
| Edit this page View Source

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
bool
| Edit this page View Source

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
bool
| Edit this page View Source

MouseEvent(MouseEvent)

Method invoked when a mouse event is generated
Declaration
public override bool MouseEvent(MouseEvent me)
Parameters
Type Name Description
MouseEvent me
Returns
Type Description
bool true, if the event was handled, false otherwise.
Overrides
| Edit this page View Source

MovePageDown(bool)

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

MovePageUp(bool)

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

OnEnter(View)

Method invoked when a view gets focus.
Declaration
public override bool OnEnter(View view)
Parameters
Type Name Description
View view The view that is losing focus.
Returns
Type Description
bool true, if the event was handled, false otherwise.
Overrides
| Edit this page View Source

OnObjectActivated(ObjectActivatedEventArgs<T>)

Raises the ObjectActivated event.
Declaration
protected virtual void OnObjectActivated(ObjectActivatedEventArgs<T> e)
Parameters
Type Name Description
ObjectActivatedEventArgs<T> e
| Edit this page View Source

OnSelectionChanged(SelectionChangedEventArgs<T>)

Raises the SelectionChanged event.
Declaration
protected virtual void OnSelectionChanged(SelectionChangedEventArgs<T> e)
Parameters
Type Name Description
SelectionChangedEventArgs<T> e
| Edit this page View Source

PositionCursor()

Positions the cursor at the start of the selected objects line (if visible).
Declaration
public override void PositionCursor()
Overrides
| Edit this page View Source

ProcessKey(KeyEvent)

If the view is focused, gives the view a chance to process the keystroke.
Declaration
public override bool ProcessKey(KeyEvent keyEvent)
Parameters
Type Name Description
KeyEvent keyEvent Contains the details about the key that produced the event.
Returns
Type Description
bool
Overrides
Remarks

Views can override this method if they are interested in processing the given keystroke. If they consume the keystroke, they must return true to stop the keystroke from being processed by other widgets or consumed by the widget engine. If they return false, the keystroke will be passed using the ProcessColdKey method to other views to process.

The View implementation does nothing but return false, so it is not necessary to call base.ProcessKey if you derive directly from View, but you should if you derive other View subclasses.

| Edit this page View Source

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, bool)).
Declaration
public void RebuildTree()
| Edit this page View Source

Redraw(Rect)

Redraws this view and its subviews; only redraws the views that have been flagged for a re-display.
Declaration
public override void Redraw(Rect bounds)
Parameters
Type Name Description
Rect bounds The bounds (view-relative region) to redraw.
Overrides
Remarks

Always use Bounds (view-relative) when calling Redraw(Rect), NOT Frame (superview-relative).

Views should set the color that they want to use on entry, as otherwise this will inherit the last color that was set globally on the driver.

Overrides of Redraw(Rect) must ensure they do not set Driver.Clip to a clip region larger than the parameter, as this will cause the driver to clip the entire region.

| Edit this page View Source

RefreshObject(T, bool)

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
bool 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.
| Edit this page View Source

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
| Edit this page View Source

ScrollDown()

Scrolls the view area down a single line without changing the current selection.
Declaration
public void ScrollDown()
| Edit this page View Source

ScrollUp()

Scrolls the view area up a single line without changing the current selection.
Declaration
public void ScrollUp()
| Edit this page View Source

SelectAll()

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

Events

| Edit this page View Source

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
Action<ObjectActivatedEventArgs<T>>
| Edit this page View Source

SelectionChanged

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

Implements