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.