Table of Contents

Class Tree

Namespace
Godot
Assembly
GodotSharp.dll

A control used to show a set of internal TreeItems in a hierarchical structure. The tree items can be selected, expanded and collapsed. The tree can have multiple columns with custom controls like LineEdits, buttons and popups. It can be useful for structured displays and interactions.

Trees are built via code, using TreeItem objects to create the structure. They have a single root, but multiple roots can be simulated with HideRoot:

public override void _Ready()
  {
      var tree = new Tree();
      TreeItem root = tree.CreateItem();
      tree.HideRoot = true;
      TreeItem child1 = tree.CreateItem(root);
      TreeItem child2 = tree.CreateItem(root);
      TreeItem subchild1 = tree.CreateItem(child1);
      subchild1.SetText(0, "Subchild1");
  }

To iterate over all the TreeItem objects in a Tree object, use GetNext() and GetFirstChild() after getting the root through GetRoot(). You can use Free() on a TreeItem to remove it from the Tree.

Incremental search: Like ItemList and PopupMenu, Tree supports searching within the list while the control is focused. Press a key that matches the first letter of an item's name to select the first item starting with the given letter. After that point, there are two ways to perform incremental search: 1) Press the same key again before the timeout duration to select the next item starting with the same letter. 2) Press letter keys that match the rest of the word before the timeout duration to match to select the item in question directly. Both of these actions will be reset to the beginning of the list if the timeout duration has passed since the last keystroke was registered. You can adjust the timeout duration by changing ProjectSettings.gui/timers/incremental_search_max_interval_msec.

public class Tree : Control, IDisposable
Inheritance
Tree
Implements
Inherited Members

Constructors

Tree() 

public Tree()

Properties

AllowReselect

If true, the currently selected cell may be selected again.

public bool AllowReselect { get; set; }

Property Value

bool

AllowRmbSelect

If true, a right mouse button click can select items.

public bool AllowRmbSelect { get; set; }

Property Value

bool

AllowSearch

If true, allows navigating the Tree with letter keys through incremental search.

public bool AllowSearch { get; set; }

Property Value

bool

ColumnTitlesVisible

If true, column titles are visible.

public bool ColumnTitlesVisible { get; set; }

Property Value

bool

Columns

The number of columns.

public int Columns { get; set; }

Property Value

int

DropModeFlags

The drop mode as an OR combination of flags. See Tree.DropModeFlagsEnum constants. Once dropping is done, reverts to Disabled. Setting this during _CanDropData(Vector2, Variant) is recommended.

This controls the drop sections, i.e. the decision and drawing of possible drop locations based on the mouse position.

public int DropModeFlags { get; set; }

Property Value

int

EnableRecursiveFolding

If true, recursive folding is enabled for this Tree. Holding down Shift while clicking the fold arrow collapses or uncollapses the TreeItem and all its descendants.

public bool EnableRecursiveFolding { get; set; }

Property Value

bool

HideFolding

If true, the folding arrow is hidden.

public bool HideFolding { get; set; }

Property Value

bool

HideRoot

If true, the tree's root is hidden.

public bool HideRoot { get; set; }

Property Value

bool

ScrollHorizontalEnabled

If true, enables horizontal scrolling.

public bool ScrollHorizontalEnabled { get; set; }

Property Value

bool

ScrollVerticalEnabled

If true, enables vertical scrolling.

public bool ScrollVerticalEnabled { get; set; }

Property Value

bool

SelectMode

Allows single or multiple selection. See the Tree.SelectModeEnum constants.

public Tree.SelectModeEnum SelectMode { get; set; }

Property Value

Tree.SelectModeEnum

Methods

Clear()

Clears the tree. This removes all items.

public void Clear()

CreateItem(TreeItem, int)

Creates an item in the tree and adds it as a child of parent, which can be either a valid TreeItem or null.

If parent is null, the root item will be the parent, or the new item will be the root itself if the tree is empty.

The new item will be the index-th child of parent, or it will be the last child if there are not enough siblings.

public TreeItem CreateItem(TreeItem parent = null, int index = -1)

Parameters

parent TreeItem
index int

Returns

TreeItem

DeselectAll()

Deselects all tree items (rows and columns). In Multi mode also removes selection cursor.

public void DeselectAll()

EditSelected(bool)

Edits the selected tree item as if it was clicked.

Either the item must be set editable with SetEditable(int, bool) or forceEdit must be true.

Returns true if the item could be edited. Fails if no item is selected.

public bool EditSelected(bool forceEdit = false)

Parameters

forceEdit bool

Returns

bool

EnsureCursorIsVisible()

Makes the currently focused cell visible.

This will scroll the tree if necessary. In Row mode, this will not do horizontal scrolling, as all the cells in the selected row is focused logically.

Note: Despite the name of this method, the focus cursor itself is only visible in Multi mode.

public void EnsureCursorIsVisible()

GetButtonIdAtPosition(Vector2)

Returns the button ID at position, or -1 if no button is there.

public int GetButtonIdAtPosition(Vector2 position)

Parameters

position Vector2

Returns

int

GetColumnAtPosition(Vector2)

Returns the column index at position, or -1 if no item is there.

public int GetColumnAtPosition(Vector2 position)

Parameters

position Vector2

Returns

int

GetColumnExpandRatio(int)

Returns the expand ratio assigned to the column.

public int GetColumnExpandRatio(int column)

Parameters

column int

Returns

int

GetColumnTitle(int)

Returns the column's title.

public string GetColumnTitle(int column)

Parameters

column int

Returns

string

GetColumnTitleAlignment(int)

Returns the column title alignment.

public HorizontalAlignment GetColumnTitleAlignment(int column)

Parameters

column int

Returns

HorizontalAlignment

GetColumnTitleDirection(int)

Returns column title base writing direction.

public Control.TextDirection GetColumnTitleDirection(int column)

Parameters

column int

Returns

Control.TextDirection

GetColumnTitleLanguage(int)

Returns column title language code.

public string GetColumnTitleLanguage(int column)

Parameters

column int

Returns

string

GetColumnWidth(int)

Returns the column's width in pixels.

public int GetColumnWidth(int column)

Parameters

column int

Returns

int

GetCustomPopupRect()

Returns the rectangle for custom popups. Helper to create custom cell controls that display a popup. See SetCellMode(int, TreeCellMode).

public Rect2 GetCustomPopupRect()

Returns

Rect2

GetDropSectionAtPosition(Vector2)

Returns the drop section at position, or -100 if no item is there.

Values -1, 0, or 1 will be returned for the "above item", "on item", and "below item" drop sections, respectively. See Tree.DropModeFlagsEnum for a description of each drop section.

To get the item which the returned drop section is relative to, use GetItemAtPosition(Vector2).

public int GetDropSectionAtPosition(Vector2 position)

Parameters

position Vector2

Returns

int

GetEdited()

Returns the currently edited item. Can be used with ItemEdited to get the item that was modified.

public override void _Ready()
  {
      GetNode<Tree>("Tree").ItemEdited += OnTreeItemEdited;
  }

public void OnTreeItemEdited()
{
GD.Print(GetNode<Tree>("Tree").GetEdited()); // This item just got edited (e.g. checked).
}
public TreeItem GetEdited()

Returns

TreeItem

GetEditedColumn()

Returns the column for the currently edited item.

public int GetEditedColumn()

Returns

int

GetItemAreaRect(TreeItem, int, int)

Returns the rectangle area for the specified TreeItem. If column is specified, only get the position and size of that column, otherwise get the rectangle containing all columns. If a button index is specified, the rectangle of that button will be returned.

public Rect2 GetItemAreaRect(TreeItem item, int column = -1, int buttonIndex = -1)

Parameters

item TreeItem
column int
buttonIndex int

Returns

Rect2

GetItemAtPosition(Vector2)

Returns the tree item at the specified position (relative to the tree origin position).

public TreeItem GetItemAtPosition(Vector2 position)

Parameters

position Vector2

Returns

TreeItem

GetNextSelected(TreeItem)

Returns the next selected TreeItem after the given one, or null if the end is reached.

If from is null, this returns the first selected item.

public TreeItem GetNextSelected(TreeItem from)

Parameters

from TreeItem

Returns

TreeItem

GetPressedButton()

Returns the last pressed button's index.

public int GetPressedButton()

Returns

int

GetRoot()

Returns the tree's root item, or null if the tree is empty.

public TreeItem GetRoot()

Returns

TreeItem

GetScroll()

Returns the current scrolling position.

public Vector2 GetScroll()

Returns

Vector2

GetSelected()

Returns the currently focused item, or null if no item is focused.

In Row and Single modes, the focused item is same as the selected item. In Multi mode, the focused item is the item under the focus cursor, not necessarily selected.

To get the currently selected item(s), use GetNextSelected(TreeItem).

public TreeItem GetSelected()

Returns

TreeItem

GetSelectedColumn()

Returns the currently focused column, or -1 if no column is focused.

In Single mode, the focused column is the selected column. In Row mode, the focused column is always 0 if any item is selected. In Multi mode, the focused column is the column under the focus cursor, and there are not necessarily any column selected.

To tell whether a column of an item is selected, use IsSelected(int).

public int GetSelectedColumn()

Returns

int

HasGodotClassMethod(in godot_string_name)

Check if the type contains a method with the given name. This method is used by Godot to check if a method exists before invoking it. Do not call or override this method.

protected override bool HasGodotClassMethod(in godot_string_name method)

Parameters

method godot_string_name

Name of the method to check for.

Returns

bool

HasGodotClassSignal(in godot_string_name)

Check if the type contains a signal with the given name. This method is used by Godot to check if a signal exists before raising it. Do not call or override this method.

protected override bool HasGodotClassSignal(in godot_string_name signal)

Parameters

signal godot_string_name

Name of the signal to check for.

Returns

bool

InvokeGodotClassMethod(in godot_string_name, NativeVariantPtrArgs, out godot_variant)

Invokes the method with the given name, using the given arguments. This method is used by Godot to invoke methods from the engine side. Do not call or override this method.

protected override bool InvokeGodotClassMethod(in godot_string_name method, NativeVariantPtrArgs args, out godot_variant ret)

Parameters

method godot_string_name

Name of the method to invoke.

args NativeVariantPtrArgs

Arguments to use with the invoked method.

ret godot_variant

Value returned by the invoked method.

Returns

bool

IsColumnClippingContent(int)

Returns true if the column has enabled clipping (see SetColumnClipContent(int, bool)).

public bool IsColumnClippingContent(int column)

Parameters

column int

Returns

bool

IsColumnExpanding(int)

Returns true if the column has enabled expanding (see SetColumnExpand(int, bool)).

public bool IsColumnExpanding(int column)

Parameters

column int

Returns

bool

ScrollToItem(TreeItem, bool)

Causes the Tree to jump to the specified TreeItem.

public void ScrollToItem(TreeItem item, bool centerOnItem = false)

Parameters

item TreeItem
centerOnItem bool

SetColumnClipContent(int, bool)

Allows to enable clipping for column's content, making the content size ignored.

public void SetColumnClipContent(int column, bool enable)

Parameters

column int
enable bool

SetColumnCustomMinimumWidth(int, int)

Overrides the calculated minimum width of a column. It can be set to 0 to restore the default behavior. Columns that have the "Expand" flag will use their "min_width" in a similar fashion to SizeFlagsStretchRatio.

public void SetColumnCustomMinimumWidth(int column, int minWidth)

Parameters

column int
minWidth int

SetColumnExpand(int, bool)

If true, the column will have the "Expand" flag of Control. Columns that have the "Expand" flag will use their expand ratio in a similar fashion to SizeFlagsStretchRatio (see SetColumnExpandRatio(int, int)).

public void SetColumnExpand(int column, bool expand)

Parameters

column int
expand bool

SetColumnExpandRatio(int, int)

Sets the relative expand ratio for a column. See SetColumnExpand(int, bool).

public void SetColumnExpandRatio(int column, int ratio)

Parameters

column int
ratio int

SetColumnTitle(int, string)

Sets the title of a column.

public void SetColumnTitle(int column, string title)

Parameters

column int
title string

SetColumnTitleAlignment(int, HorizontalAlignment)

Sets the column title alignment. Note that Fill is not supported for column titles.

public void SetColumnTitleAlignment(int column, HorizontalAlignment titleAlignment)

Parameters

column int
titleAlignment HorizontalAlignment

SetColumnTitleDirection(int, TextDirection)

Sets column title base writing direction.

public void SetColumnTitleDirection(int column, Control.TextDirection direction)

Parameters

column int
direction Control.TextDirection

SetColumnTitleLanguage(int, string)

Sets language code of column title used for line-breaking and text shaping algorithms, if left empty current locale is used instead.

public void SetColumnTitleLanguage(int column, string language)

Parameters

column int
language string

SetSelected(TreeItem, int)

Selects the specified TreeItem and column.

public void SetSelected(TreeItem item, int column)

Parameters

item TreeItem
column int

Events

ButtonClicked

Emitted when a button on the tree was pressed (see AddButton(int, Texture2D, int, bool, string)).

public event Tree.ButtonClickedEventHandler ButtonClicked

Event Type

Tree.ButtonClickedEventHandler

CellSelected

Emitted when a cell is selected.

public event Action CellSelected

Event Type

Action

CheckPropagatedToItem

Emitted when PropagateCheck(int, bool) is called. Connect to this signal to process the items that are affected when PropagateCheck(int, bool) is invoked. The order that the items affected will be processed is as follows: the item that invoked the method, children of that item, and finally parents of that item.

public event Tree.CheckPropagatedToItemEventHandler CheckPropagatedToItem

Event Type

Tree.CheckPropagatedToItemEventHandler

ColumnTitleClicked

Emitted when a column's title is clicked with either Left or Right.

public event Tree.ColumnTitleClickedEventHandler ColumnTitleClicked

Event Type

Tree.ColumnTitleClickedEventHandler

CustomItemClicked

Emitted when an item with Custom is clicked with a mouse button.

public event Tree.CustomItemClickedEventHandler CustomItemClicked

Event Type

Tree.CustomItemClickedEventHandler

CustomPopupEdited

Emitted when a cell with the Custom is clicked to be edited.

public event Tree.CustomPopupEditedEventHandler CustomPopupEdited

Event Type

Tree.CustomPopupEditedEventHandler

EmptyClicked

Emitted when a mouse button is clicked in the empty space of the tree.

public event Tree.EmptyClickedEventHandler EmptyClicked

Event Type

Tree.EmptyClickedEventHandler

ItemActivated

Emitted when an item is double-clicked, or selected with a ui_accept input event (e.g. using Enter or Space on the keyboard).

public event Action ItemActivated

Event Type

Action

ItemCollapsed

Emitted when an item is collapsed by a click on the folding arrow.

public event Tree.ItemCollapsedEventHandler ItemCollapsed

Event Type

Tree.ItemCollapsedEventHandler

ItemEdited

Emitted when an item is edited.

public event Action ItemEdited

Event Type

Action

ItemIconDoubleClicked

Emitted when an item's icon is double-clicked. For a signal that emits when any part of the item is double-clicked, see ItemActivated.

public event Action ItemIconDoubleClicked

Event Type

Action

ItemMouseSelected

Emitted when an item is selected with a mouse button.

public event Tree.ItemMouseSelectedEventHandler ItemMouseSelected

Event Type

Tree.ItemMouseSelectedEventHandler

ItemSelected

Emitted when an item is selected.

public event Action ItemSelected

Event Type

Action

MultiSelected

Emitted instead of ItemSelected if SelectMode is set to Multi.

public event Tree.MultiSelectedEventHandler MultiSelected

Event Type

Tree.MultiSelectedEventHandler

NothingSelected

Emitted when a left mouse button click does not select any item.

public event Action NothingSelected

Event Type

Action
Edit this page