Quick search

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 a tree structure. It is currently very basic, supporting a minimal feature set.

Introduction

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

TreeViewNode is a class object containing needed properties for serving as a tree node. Extend TreeViewNode to create custom a custom node type for use with TreeView.

For constructing your own subclass, follow the pattern of TreeViewLabel, which combines Label and TreeViewNode, producing TreeViewLabel for direct use in a TreeView instance.

To use the TreeViewLabel class, you could create two nodes, directly attached to root:

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

Or, create two nodes attached to a first:

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)

If you have a large tree structure, perhaps you would need a utility function to populate the tree view, as with:

def populate_tree_view(tree_view, parent, node):
    if parent is None:
        tree_node = tree_view.add_node(TreeViewLabel(text=node['node_id'],
                                                     is_open=True))
    else:
        tree_node = tree_view.add_node(TreeViewLabel(text=node['node_id'],
                                                     is_open=True), parent)

    for child_node in node['children']:
        populate_tree_view(tree_view, tree_node, child_node)


tree = {'node_id': '1',
        'children': [{'node_id': '1.1',
                      'children': [{'node_id': '1.1.1',
                                    'children': [{'node_id': '1.1.1.1',
                                                  'children': []}]},
                                   {'node_id': '1.1.2',
                                    'children': []},
                                   {'node_id': '1.1.3',
                                    'children': []}]},
                      {'node_id': '1.2',
                       'children': []}]}


class TreeWidget(FloatLayout):
    def __init__(self, **kwargs):
        super(TreeWidget, self).__init__(**kwargs)

        tv = TreeView(root_options=dict(text='Tree One'),
                      hide_root=False,
                      indent_level=4)

        populate_tree_view(tv, None, tree)

        self.add_widget(tv)

The root widget in the tree view is opened by default, and has a text set as ‘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'))

Creating Your Own Node Widget

For a button node type, combine Button + TreeViewNode like this:

class TreeViewButton(Button, TreeViewNode):
    pass

You must know that, for a given node, only the size_hint_x will be honored. The allocated width for the node will depend of the current width of the TreeView and the level of the node. For example, if a 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 is the developer’s responsibility to correctly handle adapting the graphical representation nodes, 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 expanded

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, defaults to None

Parent node to attach the new node

get_node_at_pos(pos)

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

hide_root

Use this property to show/hide the initial root node. If True, the root node will be appear as a closed node.

hide_root is a BooleanProperty, defaults 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, defaults to 16.

indent_start

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

indent_start is a NumericProperty, defaults to 24.

iterate_all_nodes(node=None)

Generator to iterate over all nodes, expanded or not.

iterate_open_nodes(node=None)

Generator to iterate over expanded nodes.

To get all the open nodes:

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

Callback to use for asynchronous loading. If set, asynchronous loading will be automatically done. The callback must act as a Python generator function, using 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, defaults to None.

minimum_height

Minimum height needed to contain all children.

New in version 1.0.9.

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

minimum_size

Minimum size needed to contain all children.

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 children.

New in version 1.0.9.

minimum_width is a kivy.properties.NumericProperty, defaults 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 text ‘Root’. If you want to change the default options passed to the widget creation, use the 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, defaults 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, defaults 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 even 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, defaults 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 uses 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 there are child nodes. This is used to adjust graphical representation.

Warning

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

is_open is a BooleanProperty, defaults 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 set by the TreeView. You can read but not write it.

is_selected is a BooleanProperty, default to False.

level

Level of the node.

level is a NumericProperty, defaults to -1.

no_selection

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

no_selection is a BooleanProperty, defaults to False

nodes

List of nodes. The nodes list is different than the children list. A node in the nodes list represents a node on the tree. An item in the children list represents the widget associated with the node.

Warning

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

nodes is a ListProperty, defaults 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.