Index · Object → TreeItem

TreeItem

An internal control for a single item inside Tree.

Class Description

A single item of a Tree control. It can contain other TreeItems as children, which allows it to create a hierarchy. It can also contain text and buttons. TreeItem is not a Node, it is internal to the Tree.

To create a TreeItem, use Tree.create_item() or create_child(). To remove a TreeItem, use Object.free().

Note: The ID values used for buttons are 32-bit, unlike int which is always 64-bit. They go from -2147483648 to 2147483647.

Properties

var collapsed: bool

If true, the TreeItem is collapsed.

var custom_minimum_height: int

The custom minimum height.

var disable_folding: bool

If true, folding is disabled for this TreeItem.

var visible: bool

If true, the TreeItem is visible (default).

Note that if a TreeItem is set to not be visible, none of its children will be visible either.

Methods

func add_button(column: int, button: Texture2D, id: int = -1, disabled: bool = false, tooltip_text: String = "", description: String = "") -> void

Adds a button with Texture2D button to the end of the cell at column column. The id is used to identify the button in the according Tree.button_clicked signal and can be different from the buttons index. If not specified, the next available index is used, which may be retrieved by calling get_button_count() immediately before this method. Optionally, the button can be disabled and have a tooltip_text. description is used as the button description for assistive apps.

func add_child(child: TreeItem) -> void

Adds a previously unparented TreeItem as a direct child of this one. The child item must not be a part of any Tree or parented to any TreeItem. See also remove_child().

func call_recursive(method: StringName) -> void

Calls the method on the actual TreeItem and its children recursively. Pass parameters as a comma separated list.

func clear_buttons() -> void

Removes all buttons from all columns of this item.

func clear_custom_bg_color(column: int) -> void

Resets the background color for the given column to default.

func clear_custom_color(column: int) -> void

Resets the color for the given column to default.

func create_child(index: int = -1) -> TreeItem

Creates an item and adds it as a child.

The new item will be inserted as position index (the default value -1 means the last position), or it will be the last child if index is higher than the child count.

func deselect(column: int) -> void

Deselects the given column.

func erase_button(column: int, button_index: int) -> void

Removes the button at index button_index in column column.

func get_auto_translate_mode(column: int) -> Node.AutoTranslateMode

Returns the column's auto translate mode.

func get_autowrap_mode(column: int) -> TextServer.AutowrapMode

Returns the text autowrap mode in the given column. By default it is TextServer.AUTOWRAP_OFF.

func get_autowrap_trim_flags(column: int) -> TextServer.LineBreakFlag

Returns the autowrap trim flags for the given column. By default, both TextServer.BREAK_TRIM_START_EDGE_SPACES and TextServer.BREAK_TRIM_END_EDGE_SPACES are enabled.

func get_button(column: int, button_index: int) -> Texture2D

Returns the Texture2D of the button at index button_index in column column.

func get_button_by_id(column: int, id: int) -> int

Returns the button index if there is a button with ID id in column column, otherwise returns -1.

func get_button_color(column: int, id: int) -> Color

Returns the color of the button with ID id in column column. If the specified button does not exist, returns Color.BLACK.

func get_button_count(column: int) -> int

Returns the number of buttons in column column.

func get_button_id(column: int, button_index: int) -> int

Returns the ID for the button at index button_index in column column.

func get_button_tooltip_text(column: int, button_index: int) -> String

Returns the tooltip text for the button at index button_index in column column.

func get_cell_mode(column: int) -> TreeItem.TreeCellMode

Returns the column's cell mode.

func get_child(index: int) -> TreeItem

Returns a child item by its index (see get_child_count()). This method is often used for iterating all children of an item.

Negative indices access the children from the last one.

func get_child_count() -> int

Returns the number of child items.

func get_children() -> TreeItem[]

Returns an array of references to the item's children.

func get_custom_bg_color(column: int) -> Color

Returns the custom background color of column column.

func get_custom_color(column: int) -> Color

Returns the custom color of column column.

func get_custom_draw_callback(column: int) -> Callable

Returns the custom callback of column column.

func get_custom_font(column: int) -> Font

Returns custom font used to draw text in the column column.

func get_custom_font_size(column: int) -> int

Returns custom font size used to draw text in the column column.

func get_custom_stylebox(column: int) -> StyleBox

Returns the given column's custom StyleBox used to draw the background.

func get_description(column: int) -> String

Returns the given column's description for assistive apps.

func get_expand_right(column: int) -> bool

Returns true if expand_right is set.

func get_first_child() -> TreeItem

Returns the TreeItem's first child.

func get_icon(column: int) -> Texture2D

Returns the given column's icon Texture2D. Error if no icon is set.

func get_icon_max_width(column: int) -> int

Returns the maximum allowed width of the icon in the given column.

func get_icon_modulate(column: int) -> Color

Returns the Color modulating the column's icon.

func get_icon_overlay(column: int) -> Texture2D

Returns the given column's icon overlay Texture2D.

func get_icon_region(column: int) -> Rect2

Returns the icon Texture2D region as Rect2.

func get_index() -> int

Returns the node's order in the tree. For example, if called on the first child item the position is 0.

func get_language(column: int) -> String

Returns item's text language code.

func get_metadata(column: int) -> Variant

Returns the metadata value that was set for the given column using set_metadata().

func get_next() -> TreeItem

Returns the next sibling TreeItem in the tree or a null object if there is none.

func get_next_in_tree(wrap: bool = false) -> TreeItem

Returns the next TreeItem in the tree (in the context of a depth-first search) or a null object if there is none.

If wrap is enabled, the method will wrap around to the first element in the tree when called on the last element, otherwise it returns null.

func get_next_visible(wrap: bool = false) -> TreeItem

Returns the next visible TreeItem in the tree (in the context of a depth-first search) or a null object if there is none.

If wrap is enabled, the method will wrap around to the first visible element in the tree when called on the last visible element, otherwise it returns null.

func get_parent() -> TreeItem

Returns the parent TreeItem or a null object if there is none.

func get_prev() -> TreeItem

Returns the previous sibling TreeItem in the tree or a null object if there is none.

func get_prev_in_tree(wrap: bool = false) -> TreeItem

Returns the previous TreeItem in the tree (in the context of a depth-first search) or a null object if there is none.

If wrap is enabled, the method will wrap around to the last element in the tree when called on the first visible element, otherwise it returns null.

func get_prev_visible(wrap: bool = false) -> TreeItem

Returns the previous visible sibling TreeItem in the tree (in the context of a depth-first search) or a null object if there is none.

If wrap is enabled, the method will wrap around to the last visible element in the tree when called on the first visible element, otherwise it returns null.

func get_range(column: int) -> float

Returns the value of a CELL_MODE_RANGE column.

func get_range_config(column: int) -> Dictionary

Returns a dictionary containing the range parameters for a given column. The keys are "min", "max", "step", and "expr".

func get_structured_text_bidi_override(column: int) -> TextServer.StructuredTextParser

Returns the BiDi algorithm override set for this cell.

func get_structured_text_bidi_override_options(column: int) -> Array

Returns the additional BiDi options set for this cell.

func get_suffix(column: int) -> String

Gets the suffix string shown after the column value.

func get_text(column: int) -> String

Returns the given column's text.

func get_text_alignment(column: int) -> HorizontalAlignment

Returns the given column's text alignment.

func get_text_direction(column: int) -> Control.TextDirection

Returns item's text base writing direction.

func get_text_overrun_behavior(column: int) -> TextServer.OverrunBehavior

Returns the clipping behavior when the text exceeds the item's bounding rectangle in the given column. By default it is TextServer.OVERRUN_TRIM_ELLIPSIS.

func get_tooltip_text(column: int) -> String

Returns the given column's tooltip text.

func get_tree() -> Tree

Returns the Tree that owns this TreeItem.

func is_accepting_children() -> bool

Returns true if this TreeItem is allowed to accept children.

func is_any_collapsed(only_visible: bool = false) -> bool

Returns true if this TreeItem, or any of its descendants, is collapsed.

If only_visible is true it ignores non-visible TreeItems.

func is_button_disabled(column: int, button_index: int) -> bool

Returns true if the button at index button_index for the given column is disabled.

func is_checked(column: int) -> bool

Returns true if the given column is checked.

func is_custom_set_as_button(column: int) -> bool

Returns true if the cell was made into a button with set_custom_as_button().

func is_edit_multiline(column: int) -> bool

Returns true if the given column is multiline editable.

func is_editable(column: int) -> bool

Returns true if the given column is editable.

func is_indeterminate(column: int) -> bool

Returns true if the given column is indeterminate.

func is_selectable(column: int) -> bool

Returns true if the given column is selectable.

func is_selected(column: int) -> bool

Returns true if the given column is selected.

func is_visible_in_tree() -> bool

Returns true if visible is true and all its ancestors are also visible.

func move_after(item: TreeItem) -> void

Moves this TreeItem right after the given item.

Note: You can't move to the root or move the root.

func move_before(item: TreeItem) -> void

Moves this TreeItem right before the given item.

Note: You can't move to the root or move the root.

func propagate_check(column: int, emit_signal: bool = true) -> void

Propagates this item's checked status to its children and parents for the given column. It is possible to process the items affected by this method call by connecting to Tree.check_propagated_to_item. The order that the items affected will be processed is as follows: the item invoking this method, children of that item, and finally parents of that item. If emit_signal is false, then Tree.check_propagated_to_item will not be emitted.

func remove_child(child: TreeItem) -> void

Removes the given child TreeItem and all its children from the Tree. Note that it doesn't free the item from memory, so it can be reused later (see add_child()). To completely remove a TreeItem use Object.free().

Note: If you want to move a child from one Tree to another, then instead of removing and adding it manually you can use move_before() or move_after().

func select(column: int, set_as_cursor: bool = true) -> void

Selects the given column. If set_as_cursor is true, the Tree's cursor will be moved to this item (only matters if Tree.select_mode is set to Tree.SELECT_MULTI).

func set_accept_children(allowed: bool) -> void

Sets TreeItem's ability to accept children.

func set_auto_translate_mode(column: int, mode: Node.AutoTranslateMode) -> void

Sets the given column's auto translate mode to mode.

All columns use Node.AUTO_TRANSLATE_MODE_INHERIT by default, which uses the same auto translate mode as the Tree itself.

func set_autowrap_mode(column: int, autowrap_mode: TextServer.AutowrapMode) -> void

Sets the autowrap mode in the given column. If set to something other than TextServer.AUTOWRAP_OFF, the text gets wrapped inside the cell's bounding rectangle.

func set_autowrap_trim_flags(column: int, flags: TextServer.LineBreakFlag) -> void

Sets the autowrap trim flags for the given column. These flags control whether leading and trailing spaces are trimmed on wrapped lines. Set to 0 to disable all trimming.

func set_button(column: int, button_index: int, button: Texture2D) -> void

Sets the given column's button Texture2D at index button_index to button.

func set_button_color(column: int, button_index: int, color: Color) -> void

Sets the given column's button color at index button_index to color.

func set_button_description(column: int, button_index: int, description: String) -> void

Sets the given column's button description at index button_index for assistive apps.

func set_button_disabled(column: int, button_index: int, disabled: bool) -> void

If true, disables the button at index button_index in the given column.

func set_button_tooltip_text(column: int, button_index: int, tooltip: String) -> void

Sets the tooltip text for the button at index button_index in the given column.

func set_cell_mode(column: int, mode: TreeItem.TreeCellMode) -> void

Sets the given column's cell mode to mode. This determines how the cell is displayed and edited.

func set_checked(column: int, checked: bool) -> void

If checked is true, the given column is checked. Clears column's indeterminate status.

func set_collapsed_recursive(enable: bool) -> void

Collapses or uncollapses this TreeItem and all the descendants of this item.

func set_custom_as_button(column: int, enable: bool) -> void

Makes a cell with CELL_MODE_CUSTOM display as a non-flat button with a StyleBox.

func set_custom_bg_color(column: int, color: Color, just_outline: bool = false) -> void

Sets the given column's custom background color and whether to just use it as an outline.

Note: If a custom StyleBox is set, the background color will be drawn behind it.

func set_custom_color(column: int, color: Color) -> void

Sets the given column's custom color.

func set_custom_draw(column: int, object: Object, callback: StringName) -> void

Sets the given column's custom draw callback to the callback method on object.

The method named callback should accept two arguments: the TreeItem that is drawn and its position and size as a Rect2.

func set_custom_draw_callback(column: int, callback: Callable) -> void

Sets the given column's custom draw callback. Use an empty Callable ([code skip-lint]Callable()[/code]) to clear the custom callback. The cell has to be in CELL_MODE_CUSTOM to use this feature.

The callback should accept two arguments: the TreeItem that is drawn and its position and size as a Rect2.

To draw custom content over the native style, please use Tree.get_custom_drawing_canvas_item().

func set_custom_font(column: int, font: Font) -> void

Sets custom font used to draw text in the given column.

func set_custom_font_size(column: int, font_size: int) -> void

Sets custom font size used to draw text in the given column.

func set_custom_stylebox(column: int, stylebox: StyleBox) -> void

Sets the given column's custom StyleBox used to draw the background.

Note: If a custom background color is set, the StyleBox will be drawn in front of it.

func set_description(column: int, description: String) -> void

Sets the given column's description for assistive apps.

func set_edit_multiline(column: int, multiline: bool) -> void

If multiline is true, the given column is multiline editable.

Note: This option only affects the type of control (LineEdit or TextEdit) that appears when editing the column. You can set multiline values with set_text() even if the column is not multiline editable.

func set_editable(column: int, enabled: bool) -> void

If enabled is true, the given column is editable.

func set_expand_right(column: int, enable: bool) -> void

If enable is true, the given column is expanded to the right.

func set_icon(column: int, texture: Texture2D) -> void

Sets the given cell's icon Texture2D. If the cell is in CELL_MODE_ICON mode, the icon is displayed in the center of the cell. Otherwise, the icon is displayed before the cell's text. CELL_MODE_RANGE does not display an icon.

func set_icon_max_width(column: int, width: int) -> void

Sets the maximum allowed width of the icon in the given column. This limit is applied on top of the default size of the icon and on top of Tree.icon_max_width. The height is adjusted according to the icon's ratio.

func set_icon_modulate(column: int, modulate: Color) -> void

Modulates the given column's icon with modulate.

func set_icon_overlay(column: int, texture: Texture2D) -> void

Sets the given cell's icon overlay Texture2D. The cell has to be in CELL_MODE_ICON mode, and icon has to be set. Overlay is drawn on top of icon, in the bottom left corner.

func set_icon_region(column: int, region: Rect2) -> void

Sets the given column's icon's texture region.

func set_indeterminate(column: int, indeterminate: bool) -> void

If indeterminate is true, the given column is marked indeterminate.

Note: If set true from false, then column is cleared of checked status.

func set_language(column: int, language: String) -> void

Sets the language code of the given column's text to language. This is used for line-breaking and text shaping algorithms. If language is empty, the current locale is used.

func set_metadata(column: int, meta: Variant) -> void

Sets the metadata value for the given column, which can be retrieved later using get_metadata(). This can be used, for example, to store a reference to the original data.

func set_range(column: int, value: float) -> void

Sets the value of a CELL_MODE_RANGE column.

func set_range_config(column: int, min: float, max: float, step: float, expr: bool = false) -> void

Sets the range of accepted values for a column. The column must be in the CELL_MODE_RANGE mode.

If expr is true, the edit mode slider will use an exponential scale as with Range.exp_edit.

func set_selectable(column: int, selectable: bool) -> void

If selectable is true, the given column is selectable.

func set_structured_text_bidi_override(column: int, parser: TextServer.StructuredTextParser) -> void

Set BiDi algorithm override for the structured text. Has effect for cells that display text.

func set_structured_text_bidi_override_options(column: int, args: Array) -> void

Set additional options for BiDi override. Has effect for cells that display text.

func set_suffix(column: int, text: String) -> void

Sets a string to be shown after a column's value (for example, a unit abbreviation).

func set_text(column: int, text: String) -> void

Sets the given column's text value.

func set_text_alignment(column: int, text_alignment: HorizontalAlignment) -> void

Sets the given column's text alignment to text_alignment.

func set_text_direction(column: int, direction: Control.TextDirection) -> void

Sets item's text base writing direction.

func set_text_overrun_behavior(column: int, overrun_behavior: TextServer.OverrunBehavior) -> void

Sets the clipping behavior when the text exceeds the item's bounding rectangle in the given column.

func set_tooltip_text(column: int, tooltip: String) -> void

Sets the given column's tooltip text.

func uncollapse_tree() -> void

Uncollapses all TreeItems necessary to reveal this TreeItem, i.e. all ancestor TreeItems.

Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum TreeCellMode
CELL_MODE_STRING = 0

Cell shows a string label, optionally with an icon. When editable, the text can be edited using a LineEdit, or a TextEdit popup if set_edit_multiline() is used.

CELL_MODE_CHECK = 1

Cell shows a checkbox, optionally with text and an icon. The checkbox can be pressed, released, or indeterminate (via set_indeterminate()). The checkbox can't be clicked unless the cell is editable.

CELL_MODE_RANGE = 2

Cell shows a numeric range. When editable, it can be edited using a range slider. Use set_range() to set the value and set_range_config() to configure the range.

This cell can also be used in a text dropdown mode when you assign a text with set_text(). Separate options with a comma, e.g. "Option1,Option2,Option3".

CELL_MODE_ICON = 3

Cell shows an icon. It can't be edited nor display text. The icon is always centered within the cell.

CELL_MODE_CUSTOM = 4

Cell shows as a clickable button. It will display an arrow similar to OptionButton, but doesn't feature a dropdown (for that you can use CELL_MODE_RANGE). Clicking the button emits the Tree.item_edited signal. The button is flat by default, you can use set_custom_as_button() to display it with a StyleBox.

This mode also supports custom drawing using set_custom_draw_callback().