Tree View¶

New in version 1.0.4.

TreeView is a widget used 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 node types for use with a TreeView.

For constructing your own subclass, follow the pattern of TreeViewLabel which combines a Label and a TreeViewNode, producing a 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:

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 text set as ‘Root’. If you want to change that, you can use the 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 a Button and a TreeViewNode as follows:

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 to 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. If None, it is added to the root node.

Returns:

the node node.

deselect_node(*args)¶: Deselect any selected node.

New in version 1.10.0.

get_node_at_pos(pos)¶: Get the node at the position (x, y).

iterate_all_nodes(node=None)¶: Generator to iterate over all nodes from node and down whether expanded or not. If node is None, the generator start with root.

iterate_open_nodes(node=None)¶

Generator to iterate over all the expended nodes starting from node and down. If node is None, the generator start with root.

To get all the open nodes:

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

on_touch_down(touch)¶

Receive a touch down event.

Parameters:

touch: MotionEvent class: Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.

Returns:

bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.

remove_node(node)¶

Removes a node from the tree.

New in version 1.0.7.

Parameters:

node: instance of a TreeViewNode: Node to remove from the tree. If node is root, it is not removed.

select_node(node)¶: Select a node in the tree.

toggle_node(node)¶: Toggle the state of the node (open/collapsed).

exception kivy.uix.treeview.TreeViewException¶

Bases: Exception

Exception for errors in the TreeView.

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

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

Combines a Label and a 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: builtins.object

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

« Toggle button

Video »

Version

Quick search

Table Of Contents

Tree View¶

Introduction¶

Creating Your Own Node Widget¶