Class Tree
A control used to show a set of internal TreeItems in a hierarchical structure.
- Inheritance
-
Tree
Remarks
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 hide_root:
func _ready():
var tree = Tree.new()
var root = tree.create_item()
tree.hide_root = true
var child1 = tree.create_item(root)
var child2 = tree.create_item(root)
var subchild1 = tree.create_item(child1)
subchild1.set_text(0, "Subchild1")
To iterate over all the TreeItem objects in a Tree object, use get_next and get_first_child after getting the root through get_root. 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 gui/timers/incremental_search_max_interval_msec.
Properties
allow_reselect
If true
, the currently selected cell may be selected again.
var allow_reselect : bool = false
Property Value
Remarks
allow_rmb_select
If true
, a right mouse button click can select items.
var allow_rmb_select : bool = false
Property Value
Remarks
allow_search
If true
, allows navigating the Tree with letter keys through incremental search.
var allow_search : bool = true
Property Value
Remarks
auto_tooltip
If true
, tree items with no tooltip assigned display their text as their tooltip. See also TreeItem.get_tooltip_text and TreeItem.get_button_tooltip_text.
var auto_tooltip : bool = true
Property Value
Remarks
column_titles_visible
If true
, column titles are visible.
var column_titles_visible : bool = false
Property Value
Remarks
columns
The number of columns.
var columns : int = 1
Property Value
Remarks
drop_mode_flags
The drop mode as an OR combination of flags. See DropModeFlags constants. Once dropping is done, reverts to Tree.DROP_MODE_DISABLED. Setting this during Control._can_drop_data is recommended.
This controls the drop sections, i.e. the decision and drawing of possible drop locations based on the mouse position.
var drop_mode_flags : int = 0
Property Value
Remarks
enable_recursive_folding
If true
, recursive folding is enabled for this Tree. Holding down Shift
while clicking the fold arrow or using ui_right
/ui_left
shortcuts collapses or uncollapses the TreeItem and all its descendants.
var enable_recursive_folding : bool = true
Property Value
Remarks
hide_folding
If true
, the folding arrow is hidden.
var hide_folding : bool = false
Property Value
Remarks
hide_root
If true
, the tree's root is hidden.
var hide_root : bool = false
Property Value
Remarks
scroll_horizontal_enabled
If true
, enables horizontal scrolling.
var scroll_horizontal_enabled : bool = true
Property Value
Remarks
scroll_vertical_enabled
If true
, enables vertical scrolling.
var scroll_vertical_enabled : bool = true
Property Value
Remarks
select_mode
Allows single or multiple selection. See the SelectMode constants.
var select_mode : int = 0
Property Value
Remarks
children_hl_line_color
= ``Color(0.27, 0.27, 0.27, 1)``
Property Value
custom_button_font_highlight
Theme Property
Text Color for a TreeItem.CELL_MODE_CUSTOM mode cell when it's hovered.
= ``Color(0.95, 0.95, 0.95, 1)``
Property Value
drop_position_color
Theme Property
Color used to draw possible drop locations. See DropModeFlags constants for further description of drop locations.
= ``Color(1, 1, 1, 1)``
Property Value
font_color
Theme Property
Default text Color of the item.
= ``Color(0.7, 0.7, 0.7, 1)``
Property Value
font_disabled_color
Theme Property
Text Color for a TreeItem.CELL_MODE_CHECK mode cell when it's non-editable (see TreeItem.set_editable).
= ``Color(0.875, 0.875, 0.875, 0.5)``
Property Value
font_hovered_color
Theme Property
Text Color used when the item is hovered.
= ``Color(0.95, 0.95, 0.95, 1)``
Property Value
font_hovered_dimmed_color
Theme Property
Text Color used when the item is hovered, while a button of the same item is hovered as the same time.
= ``Color(0.875, 0.875, 0.875, 1)``
Property Value
font_outline_color
Theme Property
The tint of text outline of the item.
= ``Color(0, 0, 0, 1)``
Property Value
font_selected_color
Theme Property
Text Color used when the item is selected.
= ``Color(1, 1, 1, 1)``
Property Value
guide_color
Theme Property
Color of the guideline.
= ``Color(0.7, 0.7, 0.7, 0.25)``
Property Value
parent_hl_line_color
= ``Color(0.27, 0.27, 0.27, 1)``
Property Value
relationship_line_color
Theme Property
The default Color of the relationship lines.
= ``Color(0.27, 0.27, 0.27, 1)``
Property Value
title_button_color
Theme Property
Default text Color of the title button.
= ``Color(0.875, 0.875, 0.875, 1)``
Property Value
button_margin
Theme Property
The horizontal space between each button in a cell.
= ``4``
Property Value
children_hl_line_width
Theme Property
The width of the relationship lines between the selected TreeItem and its children.
= ``1``
Property Value
draw_guides
Theme Property
Draws the guidelines if not zero, this acts as a boolean. The guideline is a horizontal line drawn at the bottom of each item.
= ``1``
Property Value
draw_relationship_lines
Theme Property
Draws the relationship lines if not zero, this acts as a boolean. Relationship lines are drawn at the start of child items to show hierarchy.
= ``0``
Property Value
h_separation
Theme Property
The horizontal space between item cells. This is also used as the margin at the start of an item when folding is disabled.
= ``4``
Property Value
icon_max_width
Theme Property
The maximum allowed width of the icon in item's cells. This limit is applied on top of the default size of the icon, but before the value set with TreeItem.set_icon_max_width. The height is adjusted according to the icon's ratio.
= ``0``
Property Value
inner_item_margin_bottom
Theme Property
The inner bottom margin of a cell.
= ``0``
Property Value
inner_item_margin_left
Theme Property
The inner left margin of a cell.
= ``0``
Property Value
inner_item_margin_right
Theme Property
The inner right margin of a cell.
= ``0``
Property Value
inner_item_margin_top
Theme Property
The inner top margin of a cell.
= ``0``
Property Value
item_margin
Theme Property
The horizontal margin at the start of an item. This is used when folding is enabled for the item.
= ``16``
Property Value
outline_size
Theme Property
The size of the text outline.
Note: If using a font with multichannel_signed_distance_field enabled, its msdf_pixel_range must be set to at least twice the value of outline_size for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.
= ``0``
Property Value
parent_hl_line_margin
Theme Property
The space between the parent relationship lines for the selected TreeItem and the relationship lines to its siblings that are not selected.
= ``0``
Property Value
parent_hl_line_width
Theme Property
The width of the relationship lines between the selected TreeItem and its parents.
= ``1``
Property Value
relationship_line_width
Theme Property
The default width of the relationship lines.
= ``1``
Property Value
scroll_border
Theme Property
The maximum distance between the mouse cursor and the control's border to trigger border scrolling when dragging.
= ``4``
Property Value
scroll_speed
Theme Property
The speed of border scrolling.
= ``12``
Property Value
scrollbar_h_separation
Theme Property
The horizontal separation of tree content and scrollbar.
= ``4``
Property Value
scrollbar_margin_bottom
Theme Property
The bottom margin of the scrollbars. When negative, uses panel bottom margin.
= ``-1``
Property Value
scrollbar_margin_left
Theme Property
The left margin of the horizontal scrollbar. When negative, uses panel left margin.
= ``-1``
Property Value
scrollbar_margin_right
Theme Property
The right margin of the scrollbars. When negative, uses panel right margin.
= ``-1``
Property Value
scrollbar_margin_top
Theme Property
The top margin of the vertical scrollbar. When negative, uses panel top margin.
= ``-1``
Property Value
scrollbar_v_separation
Theme Property
The vertical separation of tree content and scrollbar.
= ``4``
Property Value
v_separation
Theme Property
The vertical padding inside each item, i.e. the distance between the item's content and top/bottom border.
= ``4``
Property Value
font
Theme Property
Font of the item's text.
Font font
Property Value
title_button_font
Theme Property
Font of the title button's text.
Font title_button_font
Property Value
font_size
Theme Property
Font size of the item's text.
int font_size
Property Value
title_button_font_size
Theme Property
Font size of the title button's text.
int title_button_font_size
Property Value
arrow
Theme Property
The arrow icon used when a foldable item is not collapsed.
Texture2D arrow
Property Value
arrow_collapsed
Theme Property
The arrow icon used when a foldable item is collapsed (for left-to-right layouts).
Texture2D arrow_collapsed
Property Value
arrow_collapsed_mirrored
Theme Property
The arrow icon used when a foldable item is collapsed (for right-to-left layouts).
Texture2D arrow_collapsed_mirrored
Property Value
checked
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is checked and editable (see TreeItem.set_editable).
Texture2D checked
Property Value
checked_disabled
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is checked and non-editable (see TreeItem.set_editable).
Texture2D checked_disabled
Property Value
indeterminate
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is indeterminate and editable (see TreeItem.set_editable).
Texture2D indeterminate
Property Value
indeterminate_disabled
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is indeterminate and non-editable (see TreeItem.set_editable).
Texture2D indeterminate_disabled
Property Value
select_arrow
Theme Property
The arrow icon to display for the TreeItem.CELL_MODE_RANGE mode cell.
Texture2D select_arrow
Property Value
unchecked
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is unchecked and editable (see TreeItem.set_editable).
Texture2D unchecked
Property Value
unchecked_disabled
Theme Property
The check icon to display when the TreeItem.CELL_MODE_CHECK mode cell is unchecked and non-editable (see TreeItem.set_editable).
Texture2D unchecked_disabled
Property Value
updown
Theme Property
The updown arrow icon to display for the TreeItem.CELL_MODE_RANGE mode cell.
Texture2D updown
Property Value
button_hover
Theme Property
StyleBox used when a button in the tree is hovered.
StyleBox button_hover
Property Value
button_pressed
Theme Property
StyleBox used when a button in the tree is pressed.
StyleBox button_pressed
Property Value
cursor
Theme Property
StyleBox used for the cursor, when the Tree is being focused.
StyleBox cursor
Property Value
cursor_unfocused
Theme Property
StyleBox used for the cursor, when the Tree is not being focused.
StyleBox cursor_unfocused
Property Value
custom_button
Theme Property
Default StyleBox for a TreeItem.CELL_MODE_CUSTOM mode cell when button is enabled with TreeItem.set_custom_as_button.
StyleBox custom_button
Property Value
custom_button_hover
Theme Property
StyleBox for a TreeItem.CELL_MODE_CUSTOM mode button cell when it's hovered.
StyleBox custom_button_hover
Property Value
custom_button_pressed
Theme Property
StyleBox for a TreeItem.CELL_MODE_CUSTOM mode button cell when it's pressed.
StyleBox custom_button_pressed
Property Value
focus
Theme Property
The focused style for the Tree, drawn on top of everything.
StyleBox focus
Property Value
hovered
Theme Property
StyleBox for the item being hovered.
StyleBox hovered
Property Value
hovered_dimmed
Theme Property
StyleBox for the item being hovered, while a button of the same item is hovered as the same time.
StyleBox hovered_dimmed
Property Value
panel
Theme Property
The background style for the Tree.
StyleBox panel
Property Value
selected
Theme Property
StyleBox for the selected items, used when the Tree is not being focused.
StyleBox selected
Property Value
selected_focus
Theme Property
StyleBox for the selected items, used when the Tree is being focused.
StyleBox selected_focus
Property Value
title_button_hover
Theme Property
StyleBox used when the title button is being hovered.
StyleBox title_button_hover
Property Value
title_button_normal
Theme Property
Default StyleBox for the title button.
StyleBox title_button_normal
Property Value
title_button_pressed
Theme Property
StyleBox used when the title button is being pressed.
StyleBox title_button_pressed
Property Value
Methods
clear
Clears the tree. This removes all items.
void clear
create_item(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.
TreeItem create_item(TreeItem parent, int index)
Parameters
deselect_all
Deselects all tree items (rows and columns). In Tree.SELECT_MULTI mode also removes selection cursor.
void deselect_all
edit_selected(bool)
Edits the selected tree item as if it was clicked.
Either the item must be set editable with TreeItem.set_editable or force_edit
must be true
.
Returns true
if the item could be edited. Fails if no item is selected.
bool edit_selected(bool force_edit)
Parameters
force_edit
bool
ensure_cursor_is_visible
Makes the currently focused cell visible.
This will scroll the tree if necessary. In Tree.SELECT_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 Tree.SELECT_MULTI mode.
void ensure_cursor_is_visible
get_button_id_at_position(Vector2)
Qualifiers: const
Returns the button ID at position
, or -1 if no button is there.
int get_button_id_at_position(Vector2 position)
Parameters
position
Vector2
get_column_at_position(Vector2)
Qualifiers: const
Returns the column index at position
, or -1 if no item is there.
int get_column_at_position(Vector2 position)
Parameters
position
Vector2
get_column_expand_ratio(int)
Qualifiers: const
Returns the expand ratio assigned to the column.
int get_column_expand_ratio(int column)
Parameters
column
int
get_column_title(int)
Qualifiers: const
Returns the column's title.
String get_column_title(int column)
Parameters
column
int
get_column_title_alignment(int)
Qualifiers: const
Returns the column title alignment.
int get_column_title_alignment(int column)
Parameters
column
int
get_column_title_direction(int)
Qualifiers: const
Returns column title base writing direction.
int get_column_title_direction(int column)
Parameters
column
int
get_column_title_language(int)
Qualifiers: const
Returns column title language code.
String get_column_title_language(int column)
Parameters
column
int
get_column_width(int)
Qualifiers: const
Returns the column's width in pixels.
int get_column_width(int column)
Parameters
column
int
get_custom_popup_rect
Qualifiers: const
Returns the rectangle for custom popups. Helper to create custom cell controls that display a popup. See TreeItem.set_cell_mode.
Rect2 get_custom_popup_rect
get_drop_section_at_position(Vector2)
Qualifiers: const
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 DropModeFlags for a description of each drop section.
To get the item which the returned drop section is relative to, use Tree.get_item_at_position.
int get_drop_section_at_position(Vector2 position)
Parameters
position
Vector2
get_edited
Qualifiers: const
Returns the currently edited item. Can be used with item_edited to get the item that was modified.
TreeItem get_edited
get_edited_column
Qualifiers: const
Returns the column for the currently edited item.
int get_edited_column
get_item_area_rect(TreeItem, int, int)
Qualifiers: const
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.
Rect2 get_item_area_rect(TreeItem item, int column, int button_index)
Parameters
get_item_at_position(Vector2)
Qualifiers: const
Returns the tree item at the specified position (relative to the tree origin position).
TreeItem get_item_at_position(Vector2 position)
Parameters
position
Vector2
get_next_selected(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.
TreeItem get_next_selected(TreeItem from)
Parameters
from
TreeItem
get_pressed_button
Qualifiers: const
Returns the last pressed button's index.
int get_pressed_button
get_root
Qualifiers: const
Returns the tree's root item, or null
if the tree is empty.
TreeItem get_root
get_scroll
Qualifiers: const
Returns the current scrolling position.
Vector2 get_scroll
get_selected
Qualifiers: const
Returns the currently focused item, or null
if no item is focused.
In Tree.SELECT_ROW and Tree.SELECT_SINGLE modes, the focused item is same as the selected item. In Tree.SELECT_MULTI mode, the focused item is the item under the focus cursor, not necessarily selected.
To get the currently selected item(s), use Tree.get_next_selected.
TreeItem get_selected
get_selected_column
Qualifiers: const
Returns the currently focused column, or -1 if no column is focused.
In Tree.SELECT_SINGLE mode, the focused column is the selected column. In Tree.SELECT_ROW mode, the focused column is always 0 if any item is selected. In Tree.SELECT_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 TreeItem.is_selected.
int get_selected_column
is_column_clipping_content(int)
Qualifiers: const
Returns true
if the column has enabled clipping (see Tree.set_column_clip_content).
bool is_column_clipping_content(int column)
Parameters
column
int
is_column_expanding(int)
Qualifiers: const
Returns true
if the column has enabled expanding (see Tree.set_column_expand).
bool is_column_expanding(int column)
Parameters
column
int
scroll_to_item(TreeItem, bool)
Causes the Tree to jump to the specified TreeItem.
void scroll_to_item(TreeItem item, bool center_on_item)
Parameters
set_column_clip_content(int, bool)
Allows to enable clipping for column's content, making the content size ignored.
void set_column_clip_content(int column, bool enable)
Parameters
set_column_custom_minimum_width(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 size_flags_stretch_ratio.
void set_column_custom_minimum_width(int column, int min_width)
Parameters
set_column_expand(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 size_flags_stretch_ratio (see Tree.set_column_expand_ratio).
void set_column_expand(int column, bool expand)
Parameters
set_column_expand_ratio(int, int)
Sets the relative expand ratio for a column. See Tree.set_column_expand.
void set_column_expand_ratio(int column, int ratio)
Parameters
set_column_title(int, String)
Sets the title of a column.
void set_column_title(int column, String title)
Parameters
set_column_title_alignment(int, int)
Sets the column title alignment. Note that @GlobalScope.HORIZONTAL_ALIGNMENT_FILL is not supported for column titles.
void set_column_title_alignment(int column, int title_alignment)
Parameters
set_column_title_direction(int, int)
Sets column title base writing direction.
void set_column_title_direction(int column, int direction)
Parameters
set_column_title_language(int, String)
Sets language code of column title used for line-breaking and text shaping algorithms, if left empty current locale is used instead.
void set_column_title_language(int column, String language)
Parameters
set_selected(TreeItem, int)
Selects the specified TreeItem and column.
void set_selected(TreeItem item, int column)
Parameters
Events
button_clicked(TreeItem, int, int, int)
Emitted when a button on the tree was pressed (see TreeItem.add_button).
signal button_clicked(TreeItem item, int column, int id, int mouse_button_index)
Parameters
cell_selected
Emitted when a cell is selected.
signal cell_selected
check_propagated_to_item(TreeItem, int)
Emitted when TreeItem.propagate_check is called. Connect to this signal to process the items that are affected when TreeItem.propagate_check 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.
signal check_propagated_to_item(TreeItem item, int column)
Parameters
column_title_clicked(int, int)
Emitted when a column's title is clicked with either @GlobalScope.MOUSE_BUTTON_LEFT or @GlobalScope.MOUSE_BUTTON_RIGHT.
signal column_title_clicked(int column, int mouse_button_index)
Parameters
custom_item_clicked(int)
Emitted when an item with TreeItem.CELL_MODE_CUSTOM is clicked with a mouse button.
signal custom_item_clicked(int mouse_button_index)
Parameters
mouse_button_index
int
custom_popup_edited(bool)
Emitted when a cell with the TreeItem.CELL_MODE_CUSTOM is clicked to be edited.
signal custom_popup_edited(bool arrow_clicked)
Parameters
arrow_clicked
bool
empty_clicked(Vector2, int)
Emitted when a mouse button is clicked in the empty space of the tree.
signal empty_clicked(Vector2 click_position, int mouse_button_index)
Parameters
item_activated
Emitted when an item is double-clicked, or selected with a ui_accept
input event (e.g. using Enter
or Space
on the keyboard).
signal item_activated
item_collapsed(TreeItem)
Emitted when an item is collapsed by a click on the folding arrow.
signal item_collapsed(TreeItem item)
Parameters
item
TreeItem
item_edited
Emitted when an item is edited.
signal item_edited
item_icon_double_clicked
Emitted when an item's icon is double-clicked. For a signal that emits when any part of the item is double-clicked, see item_activated.
signal item_icon_double_clicked
item_mouse_selected(Vector2, int)
Emitted when an item is selected with a mouse button.
signal item_mouse_selected(Vector2 mouse_position, int mouse_button_index)
Parameters
item_selected
Emitted when an item is selected.
signal item_selected
multi_selected(TreeItem, int, bool)
Emitted instead of item_selected if select_mode is set to Tree.SELECT_MULTI.
signal multi_selected(TreeItem item, int column, bool selected)
Parameters
nothing_selected
Emitted when a left mouse button click does not select any item.
signal nothing_selected