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.