Tree¶
Added in version 0.6.0
A tree control widget.
- Focusable
- Container
Example¶
The example below creates a simple tree.
from textual.app import App, ComposeResult
from textual.widgets import Tree
class TreeApp(App):
def compose(self) -> ComposeResult:
tree: Tree[dict] = Tree("Dune")
tree.root.expand()
characters = tree.root.add("Characters", expand=True)
characters.add_leaf("Paul")
characters.add_leaf("Jessica")
characters.add_leaf("Chani")
yield tree
if __name__ == "__main__":
app = TreeApp()
app.run()
Tree widgets have a "root" attribute which is an instance of a TreeNode. Call add() or add_leaf() to add new nodes underneath the root. Both these methods return a TreeNode for the child which you can use to add additional levels.
Reactive Attributes¶
Name | Type | Default | Description |
---|---|---|---|
show_root |
bool |
True |
Show the root node. |
show_guides |
bool |
True |
Show guide lines between levels. |
guide_depth |
int |
4 |
Amount of indentation between parent and child. |
Messages¶
Bindings¶
The tree widget defines the following bindings:
Key(s) | Description |
---|---|
enter | Select the current item. |
space | Toggle the expand/collapsed space of the current item. |
up | Move the cursor up. |
down | Move the cursor down. |
Component Classes¶
The tree widget provides the following component classes:
Class | Description |
---|---|
tree--cursor |
Targets the cursor. |
tree--guides |
Targets the indentation guides. |
tree--guides-hover |
Targets the indentation guides under the cursor. |
tree--guides-selected |
Targets the indentation guides that are selected. |
tree--highlight |
Targets the highlighted items. |
tree--highlight-line |
Targets the lines under the cursor. |
tree--label |
Targets the (text) labels of the items. |
textual.widgets.Tree
class
¶
Bases: Generic[TreeDataType]
, ScrollView
A widget for displaying and navigating data in a tree.
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
The label of the root node of the tree. |
required |
data |
TreeDataType | None
|
The optional data to associate with the root node of the tree. |
None
|
name |
str | None
|
The name of the Tree. |
None
|
id |
str | None
|
The ID of the tree in the DOM. |
None
|
classes |
str | None
|
The CSS classes of the tree. |
None
|
disabled |
bool
|
Whether the tree is disabled or not. |
False
|
BINDINGS
class-attribute
¶
BINDINGS: list[BindingType] = [
Binding("enter", "select_cursor", "Select", show=False),
Binding("space", "toggle_node", "Toggle", show=False),
Binding("up", "cursor_up", "Cursor Up", show=False),
Binding(
"down", "cursor_down", "Cursor Down", show=False
),
]
Key(s) | Description |
---|---|
enter | Select the current item. |
space | Toggle the expand/collapsed space of the current item. |
up | Move the cursor up. |
down | Move the cursor down. |
COMPONENT_CLASSES
class-attribute
¶
COMPONENT_CLASSES: set[str] = {
"tree--cursor",
"tree--guides",
"tree--guides-hover",
"tree--guides-selected",
"tree--highlight",
"tree--highlight-line",
"tree--label",
}
Class | Description |
---|---|
tree--cursor |
Targets the cursor. |
tree--guides |
Targets the indentation guides. |
tree--guides-hover |
Targets the indentation guides under the cursor. |
tree--guides-selected |
Targets the indentation guides that are selected. |
tree--highlight |
Targets the highlighted items. |
tree--highlight-line |
Targets the lines under the cursor. |
tree--label |
Targets the (text) labels of the items. |
auto_expand
class-attribute
instance-attribute
¶
Auto expand tree nodes when clicked.
cursor_line
class-attribute
instance-attribute
¶
The line with the cursor, or -1 if no cursor.
cursor_node
property
¶
The currently selected node, or None
if no selection.
guide_depth
class-attribute
instance-attribute
¶
The indent depth of tree nodes.
hover_line
class-attribute
instance-attribute
¶
The line number under the mouse pointer, or -1 if not under the mouse pointer.
show_guides
class-attribute
instance-attribute
¶
Enable display of tree guide lines.
show_root
class-attribute
instance-attribute
¶
Show the root of the tree.
NodeCollapsed
class
¶
NodeExpanded
class
¶
NodeHighlighted
class
¶
NodeSelected
class
¶
action_scroll_end
method
¶
Move the cursor to the bottom of the tree.
Note
Here bottom means vertically, not branch depth.
action_select_cursor
method
¶
Cause a select event for the target node.
Note
If auto_expand
is True
use of this action on a non-leaf node
will cause both an expand/collapse event to occur, as well as a
selected event.
action_toggle_node
method
¶
Toggle the expanded state of the target node.
clear
method
¶
Clear all nodes under root.
Returns
Type | Description |
---|---|
Self
|
The |
get_label_width
method
¶
Get the width of the nodes label.
The default behavior is to call render_node
and return the cell length. This method may be
overridden in a sub-class if it can be done more efficiently.
Parameters
Name | Type | Description | Default |
---|---|---|---|
node |
TreeNode[TreeDataType]
|
A node. |
required |
Returns
Type | Description |
---|---|
int
|
Width in cells. |
get_node_at_line
method
¶
get_node_by_id
method
¶
process_label
method
¶
Process a str
or Text
value into a label.
Maybe overridden in a subclass to change how labels are rendered.
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
Label. |
required |
Returns
Type | Description |
---|---|
Text
|
A Rich Text object. |
refresh_line
method
¶
Refresh (repaint) a given line in the tree.
Parameters
Name | Type | Description | Default |
---|---|---|---|
line |
int
|
Line number. |
required |
render_label
method
¶
Render a label for the given node. Override this to modify how labels are rendered.
Parameters
Name | Type | Description | Default |
---|---|---|---|
node |
TreeNode[TreeDataType]
|
A tree node. |
required |
base_style |
Style
|
The base style of the widget. |
required |
style |
Style
|
The additional style for the label. |
required |
Returns
Type | Description |
---|---|
Text
|
A Rich Text object containing the label. |
reset
method
¶
Clear the tree and reset the root node.
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
The label for the root node. |
required |
data |
TreeDataType | None
|
Optional data for the root node. |
None
|
Returns
Type | Description |
---|---|
Self
|
The |
scroll_to_line
method
¶
scroll_to_node
method
¶
select_node
method
¶
Move the cursor to the given node, or reset cursor.
Parameters
Name | Type | Description | Default |
---|---|---|---|
node |
TreeNode[TreeDataType] | None
|
A tree node, or None to reset cursor. |
required |
textual.widgets.tree.TreeNode
class
¶
Bases: Generic[TreeDataType]
An object that represents a "node" in a tree control.
Parameters
Name | Type | Description | Default |
---|---|---|---|
tree |
Tree[TreeDataType]
|
The tree that the node is being attached to. |
required |
parent |
TreeNode[TreeDataType] | None
|
The parent node that this node is being attached to. |
required |
id |
NodeID
|
The ID of the node. |
required |
label |
Text
|
The label for the node. |
required |
data |
TreeDataType | None
|
Optional data to associate with the node. |
None
|
expanded |
bool
|
Should the node be attached in an expanded state? |
True
|
allow_expand |
bool
|
Should the node allow being expanded by the user? |
True
|
add
method
¶
Add a node to the sub-tree.
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
The new node's label. |
required |
data |
TreeDataType | None
|
Data associated with the new node. |
None
|
expand |
bool
|
Node should be expanded. |
False
|
allow_expand |
bool
|
Allow use to expand the node via keyboard or mouse. |
True
|
Returns
Type | Description |
---|---|
TreeNode[TreeDataType]
|
A new Tree node |
add_leaf
method
¶
Add a 'leaf' node (a node that can not expand).
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
Label for the node. |
required |
data |
TreeDataType | None
|
Optional data. |
None
|
Returns
Type | Description |
---|---|
TreeNode[TreeDataType]
|
New node. |
collapse
method
¶
Collapse the node (hide its children).
Returns
Type | Description |
---|---|
Self
|
The |
collapse_all
method
¶
Collapse the node (hide its children) and all those below it.
Returns
Type | Description |
---|---|
Self
|
The |
expand
method
¶
Expand the node (show its children).
Returns
Type | Description |
---|---|
Self
|
The |
expand_all
method
¶
Expand the node (show its children) and all those below it.
Returns
Type | Description |
---|---|
Self
|
The |
remove
method
¶
Remove this node from the tree.
Raises
Type | Description |
---|---|
TreeNode.RemoveRootError
|
If there is an attempt to remove the root. |
set_label
method
¶
Set a new label for the node.
Parameters
Name | Type | Description | Default |
---|---|---|---|
label |
TextType
|
A |
required |
toggle
method
¶
Toggle the node's expanded state.
Returns
Type | Description |
---|---|
Self
|
The |
toggle_all
method
¶
Toggle the node's expanded state and make all those below it match.
Returns
Type | Description |
---|---|
Self
|
The |