Tree View

New in version 1.0.4.

Warning

This widget is still experimental, and his API is subject to change in a future version.

TreeView is a widget to represent tree list. It’s currently very basic, but support the minimal features set to be usable.

Introduction to the TreeView

A TreeView is populated with TreeViewNode, but you cannot use directly a TreeViewNode. You must combine it with another widget, such as Label, Button... or even your own widget. The TreeView always create a default root node, based on TreeViewLabel.

The TreeViewNode is just an class object that hold the needed property to successful use the other class as a node for the Tree. You can read the next section about how to create custom node to be used in the TreeView.

For you, we have combine Label + TreeViewNode: the result is a TreeViewLabel, that you can directly use as a node in the Tree.

For example, you can create 2 nodes, directly attached to root:

tv = TreeView()
tv.add_node(TreeViewLabel(text='My first item'))
tv.add_node(TreeViewLabel(text='My second item'))

If you want to create 2 nodes attached to another one, you can do:

tv = TreeView()
n1 = tv.add_node(TreeViewLabel(text='Item 1'))
tv.add_node(TreeViewLabel(text='SubItem 1'), n1)
tv.add_node(TreeViewLabel(text='SubItem 2'), n1)

The default root widget is always opened, and have a default text ‘Root’. If you want to change that, you can use TreeView.root_options property. This will pass options to the root widget:

tv = TreeView(root_options=dict(text='My root label'))

Create your own node widget

If you want to create a button node for example, you can just combine Button + TreeViewNode like this:

class TreeViewButton(Button, TreeViewNode):
    pass

You must know that only the size_hint_x will be honored. The allocated width will depend of the current width of the TreeView and the level of the node. For example, if your node is at level 4, the width allocated will be:

treeview.width - treeview.indent_start - treeview.indent_level * node.level

You might have some trouble with that, it’s on your side to correctly handle that case, and adapt the graphical representation of your node if needed

class kivy.uix.treeview.TreeView(**kwargs)

Bases: kivy.uix.widget.Widget

TreeView class. See module documentation for more information.

Events :
on_node_expand: (node, )

Fired when a node is being expended

on_node_collapse: (node, )

Fired when a node is being collapsed

add_node(node, parent=None)

Add a new node in the tree.

Parameters :
node: instance of a TreeViewNode

Node to add into the tree

parent: instance of a TreeViewNode, default to None

Parent node to attach the new node

get_node_at_pos(pos)

Get a node a at the position (x, y).

hide_root

Use this property to show/hide the initial root node. If True, the root node will be always considerate as an open node

hide_root is a BooleanProperty, default to False.

indent_level

Width used for identation of each level, except the first level.

Computation of spacing for eaching level of tree is:

:data:`indent_start` + level * :data:`indent_level`

indent_level is a NumericProperty, default to 16.

indent_start

Indentation width of the level 0 / root node. This is mostly the initial size to put an tree icon (collapsed / expanded). See indent_level for more information about the computation of level indentation.

indent_start is a NumericProperty, default to 24.

iterate_all_nodes(node=None)

Generate to iterate over all nodes, expanded or not.

iterate_open_nodes(node=None)

Generator to iterate over expanded nodes. Example for get all the node opened:

treeview = TreeView()
# ... add nodes ...
for node in treeview.iterate_open_nodes():
    print node
load_func

Callback to use for asynchronous loading. If set, the asynchronous will be automatically done. The callback must act as a Python generator function : use yield to send data back to the treeview.

The callback should be in the format:

def callback(treeview, node):
    for name in ('Item 1', 'Item 2'):
        yield TreeViewLabel(text=name)

load_func is a ObjectProperty, default to None.

minimum_height

Minimum height needed to contain all childrens.

New in version 1.0.9.

minimum_height is a kivy.properties.NumericProperty, default to 0.

minimum_size

Minimum size needed to contain all childrens.

New in version 1.0.9.

minimum_size is a ReferenceListProperty of (minimum_width, minimum_height) properties.

minimum_width

Minimum width needed to contain all childrens.

New in version 1.0.9.

minimum_width is a kivy.properties.NumericProperty, default to 0.

remove_node(node)

Remove a node in a tree.

New in version 1.0.7.

Parameters :
node: instance of a TreeViewNode

Node to remove from the tree

root

Root node.

By default, the root node widget is a TreeViewLabel, with the label ‘Root’. If you want to change the default options passed to the widget creation, you can use root_options property:

treeview = TreeView(root_options={
    'text': 'Root directory',
    'font_size': 15})

root_options will change the properties of the TreeViewLabel instance. However, you cannot change the class used for root node yet.

root is a AliasProperty, default to None, and is read-only. However, the content of the widget can be changed.

root_options

Default root options to pass for root widget. See root property for more information about the usage of root_options.

root_options is a ObjectProperty, default to {}.

select_node(node)

Select a node in the tree

selected_node

Node selected by TreeView.select_node(), or by touch.

selected_node is a AliasProperty, default to None, and is read-only.

toggle_node(node)

Toggle the state of the node (open/collapse)

class kivy.uix.treeview.TreeViewException

Bases: exceptions.Exception

Exception for errors in the TreeView

class kivy.uix.treeview.TreeViewLabel(**kwargs)

Bases: kivy.uix.label.Label, kivy.uix.treeview.TreeViewNode

Combine Label and TreeViewNode to create a TreeViewLabel, that can be used as a text node in the tree.

See module documentation for more information.

class kivy.uix.treeview.TreeViewNode(**kwargs)

Bases: object

TreeViewNode class, used to build node class for TreeView object.

color_selected

Background color of the node when the node is selected.

color_selected is a ListProperty, defaults to [.1, .1, .1, 1]

even_color

Background color of odd nodes when the node is not selected.

bg_color is a ListProperty, default to [.5, .5, .5, .1].

is_leaf

Boolean to indicate if this node is a leaf or not, used to adjust graphical representation.

is_leaf is a BooleanProperty, default to True, and automatically set to False when child is added.

is_loaded

Boolean to indicate if this node is already loaded or not. This property is used only if the TreeView use asynchronous loading.

is_loaded is a BooleanProperty, default to False

is_open

Boolean to indicate if this node is opened or not, in case if he contain children nodes. This is used for graphical representation.

Warning

This property is automatically setted by the TreeView. You can read it but not write on it.

is_open is a BooleanProperty, default to False.

is_selected

Boolean to indicate if this node is selected or not. This is used for graphical representation.

Warning

This property is automatically setted by the TreeView. You can read it but not write on it.

is_selected is a BooleanProperty, default to False.

level

Level of the node.

level is a NumericProperty, default to -1.

no_selection

Boolean to indicate if we allow selection of the node or not.

no_selection is a BooleanProperty, default to False

nodes

List of nodes. The nodes list is differents than children. Nodes represent a node on the tree, while children represent the widget associated to the current node.

Warning

This property is automatically setted by the TreeView. You can read it, but not write on it.

nodes is a ListProperty, default to [].

odd

This property is set by the TreeView widget automatically. Read-only. odd is a BooleanProperty, defaults to False.

odd_color

Background color of odd nodes when the node is not selected.

bg_color is a ListProperty, default to [1., 1., 1., 0.].

parent_node

Parent node. This attribute is needed because parent can be None when the node is not displayed.

New in version 1.0.7.

parent_node is a ObjectProperty, default to None.