'''
Tree View
=========
.. image:: images/treeview.png
:align: right
.. versionadded:: 1.0.4
:class:`TreeView` is a widget used to represent a tree structure. It is
currently very basic, supporting a minimal feature set.
Introduction
------------
A :class:`TreeView` is populated with :class:`TreeViewNode` instances, but you
cannot use a :class:`TreeViewNode` directly. You must combine it with another
widget, such as :class:`~kivy.uix.label.Label`,
:class:`~kivy.uix.button.Button` or even your own widget. The TreeView
always creates a default root node, based on :class:`TreeViewLabel`.
:class:`TreeViewNode` is a class object containing needed properties for
serving as a tree node. Extend :class:`TreeViewNode` to create custom node
types for use with a :class:`TreeView`.
For constructing your own subclass, follow the pattern of TreeViewLabel which
combines a Label and a TreeViewNode, producing a :class:`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
:attr:`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 :class:`~kivy.uix.button.Button` and a
:class:`TreeViewNode` as follows::
class TreeViewButton(Button, TreeViewNode):
pass
You must know that, for a given node, only the
:attr:`~kivy.uix.widget.Widget.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.
'''
from kivy.clock import Clock
from kivy.uix.label import Label
from kivy.uix.widget import Widget
from kivy.properties import BooleanProperty, ListProperty, ObjectProperty, \
AliasProperty, NumericProperty, ReferenceListProperty, ColorProperty
[docs]class TreeViewException(Exception):
'''Exception for errors in the :class:`TreeView`.
'''
pass
[docs]class TreeViewNode(object):
'''TreeViewNode class, used to build a node class for a TreeView object.
'''
def __init__(self, **kwargs):
if self.__class__ is TreeViewNode:
raise TreeViewException('You cannot use directly TreeViewNode.')
super(TreeViewNode, self).__init__(**kwargs)
is_leaf = BooleanProperty(True)
'''Boolean to indicate whether this node is a leaf or not. Used to adjust
the graphical representation.
:attr:`is_leaf` is a :class:`~kivy.properties.BooleanProperty` and defaults
to True. It is automatically set to False when child is added.
'''
is_open = BooleanProperty(False)
'''Boolean to indicate whether this node is opened or not, in case there
are child nodes. This is used to adjust the graphical representation.
.. warning::
This property is automatically set by the :class:`TreeView`. You can
read but not write it.
:attr:`is_open` is a :class:`~kivy.properties.BooleanProperty` and defaults
to False.
'''
is_loaded = BooleanProperty(False)
'''Boolean to indicate whether this node is already loaded or not. This
property is used only if the :class:`TreeView` uses asynchronous loading.
:attr:`is_loaded` is a :class:`~kivy.properties.BooleanProperty` and
defaults to False.
'''
is_selected = BooleanProperty(False)
'''Boolean to indicate whether this node is selected or not. This is used
adjust the graphical representation.
.. warning::
This property is automatically set by the :class:`TreeView`. You can
read but not write it.
:attr:`is_selected` is a :class:`~kivy.properties.BooleanProperty` and
defaults to False.
'''
no_selection = BooleanProperty(False)
'''Boolean used to indicate whether selection of the node is allowed or
not.
:attr:`no_selection` is a :class:`~kivy.properties.BooleanProperty` and
defaults to False.
'''
nodes = ListProperty([])
'''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 :class:`TreeView`. You can
read but not write it.
:attr:`nodes` is a :class:`~kivy.properties.ListProperty` and defaults to
[].
'''
parent_node = ObjectProperty(None, allownone=True)
'''Parent node. This attribute is needed because the :attr:`parent` can be
None when the node is not displayed.
.. versionadded:: 1.0.7
:attr:`parent_node` is an :class:`~kivy.properties.ObjectProperty` and
defaults to None.
'''
level = NumericProperty(-1)
'''Level of the node.
:attr:`level` is a :class:`~kivy.properties.NumericProperty` and defaults
to -1.
'''
color_selected = ColorProperty([.3, .3, .3, 1.])
'''Background color of the node when the node is selected.
:attr:`color_selected` is a :class:`~kivy.properties.ColorProperty` and
defaults to [.1, .1, .1, 1].
.. versionchanged:: 2.0.0
Changed from :class:`~kivy.properties.ListProperty` to
:class:`~kivy.properties.ColorProperty`.
'''
odd = BooleanProperty(False)
'''
This property is set by the TreeView widget automatically and is read-only.
:attr:`odd` is a :class:`~kivy.properties.BooleanProperty` and defaults to
False.
'''
odd_color = ColorProperty([1., 1., 1., .0])
'''Background color of odd nodes when the node is not selected.
:attr:`odd_color` is a :class:`~kivy.properties.ColorProperty` and defaults
to [1., 1., 1., 0.].
.. versionchanged:: 2.0.0
Changed from :class:`~kivy.properties.ListProperty` to
:class:`~kivy.properties.ColorProperty`.
'''
even_color = ColorProperty([0.5, 0.5, 0.5, 0.1])
'''Background color of even nodes when the node is not selected.
:attr:`bg_color` is a :class:`~kivy.properties.ColorProperty` ans defaults
to [.5, .5, .5, .1].
.. versionchanged:: 2.0.0
Changed from :class:`~kivy.properties.ListProperty` to
:class:`~kivy.properties.ColorProperty`.
'''
[docs]class TreeViewLabel(Label, TreeViewNode):
'''Combines a :class:`~kivy.uix.label.Label` and a :class:`TreeViewNode` to
create a :class:`TreeViewLabel` that can be used as a text node in the
tree.
See module documentation for more information.
'''
[docs]class TreeView(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
'''
__events__ = ('on_node_expand', 'on_node_collapse')
def __init__(self, **kwargs):
self._trigger_layout = Clock.create_trigger(self._do_layout, -1)
super(TreeView, self).__init__(**kwargs)
tvlabel = TreeViewLabel(text='Root', is_open=True, level=0)
for key, value in self.root_options.items():
setattr(tvlabel, key, value)
self._root = self.add_node(tvlabel, None)
trigger = self._trigger_layout
fbind = self.fbind
fbind('pos', trigger)
fbind('size', trigger)
fbind('indent_level', trigger)
fbind('indent_start', trigger)
trigger()
[docs] def add_node(self, node, parent=None):
'''Add a new node to the tree.
:Parameters:
`node`: instance of a :class:`TreeViewNode`
Node to add into the tree
`parent`: instance of a :class:`TreeViewNode`, defaults to None
Parent node to attach the new node. If `None`, it is added to
the :attr:`root` node.
:returns:
the node `node`.
'''
# check if the widget is "ok" for a node
if not isinstance(node, TreeViewNode):
raise TreeViewException(
'The node must be a subclass of TreeViewNode')
# create node
if parent is None and self._root:
parent = self._root
if parent:
parent.is_leaf = False
parent.nodes.append(node)
node.parent_node = parent
node.level = parent.level + 1
node.fbind('size', self._trigger_layout)
self._trigger_layout()
return node
[docs] def remove_node(self, node):
'''Removes a node from the tree.
.. versionadded:: 1.0.7
:Parameters:
`node`: instance of a :class:`TreeViewNode`
Node to remove from the tree. If `node` is :attr:`root`, it is
not removed.
'''
# check if the widget is "ok" for a node
if not isinstance(node, TreeViewNode):
raise TreeViewException(
'The node must be a subclass of TreeViewNode')
parent = node.parent_node
if parent is not None:
if node == self._selected_node:
node.is_selected = False
self._selected_node = None
nodes = parent.nodes
if node in nodes:
nodes.remove(node)
parent.is_leaf = not bool(len(nodes))
node.parent_node = None
node.funbind('size', self._trigger_layout)
self._trigger_layout()
def on_node_expand(self, node):
pass
def on_node_collapse(self, node):
pass
[docs] def select_node(self, node):
'''Select a node in the tree.
'''
if node.no_selection:
return
if self._selected_node:
self._selected_node.is_selected = False
node.is_selected = True
self._selected_node = node
[docs] def deselect_node(self, *args):
'''Deselect any selected node.
.. versionadded:: 1.10.0
'''
if self._selected_node:
self._selected_node.is_selected = False
self._selected_node = None
[docs] def toggle_node(self, node):
'''Toggle the state of the node (open/collapsed).
'''
node.is_open = not node.is_open
if node.is_open:
if self.load_func and not node.is_loaded:
self._do_node_load(node)
self.dispatch('on_node_expand', node)
else:
self.dispatch('on_node_collapse', node)
self._trigger_layout()
[docs] def get_node_at_pos(self, pos):
'''Get the node at the position (x, y).
'''
x, y = pos
for node in self.iterate_open_nodes(self.root):
if self.x <= x <= self.right and \
node.y <= y <= node.top:
return node
[docs] def iterate_open_nodes(self, node=None):
'''Generator to iterate over all the expended nodes starting from
`node` and down. If `node` is `None`, the generator start with
:attr:`root`.
To get all the open nodes::
treeview = TreeView()
# ... add nodes ...
for node in treeview.iterate_open_nodes():
print(node)
'''
if not node:
node = self.root
if self.hide_root and node is self.root:
pass
else:
yield node
if not node.is_open:
return
f = self.iterate_open_nodes
for cnode in node.nodes:
for ynode in f(cnode):
yield ynode
[docs] def iterate_all_nodes(self, node=None):
'''Generator to iterate over all nodes from `node` and down whether
expanded or not. If `node` is `None`, the generator start with
:attr:`root`.
'''
if not node:
node = self.root
yield node
f = self.iterate_all_nodes
for cnode in node.nodes:
for ynode in f(cnode):
yield ynode
#
# Private
#
def on_load_func(self, instance, value):
if value:
Clock.schedule_once(self._do_initial_load)
def _do_initial_load(self, *largs):
if not self.load_func:
return
self._do_node_load(None)
def _do_node_load(self, node):
gen = self.load_func(self, node)
if node:
node.is_loaded = True
if not gen:
return
for cnode in gen:
self.add_node(cnode, node)
def on_root_options(self, instance, value):
if not self.root:
return
for key, value in value.items():
setattr(self.root, key, value)
def _do_layout(self, *largs):
self.clear_widgets()
# display only the one who are is_open
self._do_open_node(self.root)
# now do layout
self._do_layout_node(self.root, 0, self.top)
# now iterate for calculating minimum size
min_width = min_height = 0
for count, node in enumerate(self.iterate_open_nodes(self.root)):
node.odd = False if count % 2 else True
min_width = max(min_width, node.right - self.x)
min_height += node.height
self.minimum_size = (min_width, min_height)
def _do_open_node(self, node):
if self.hide_root and node is self.root:
height = 0
else:
self.add_widget(node)
height = node.height
if not node.is_open:
return height
for cnode in node.nodes:
height += self._do_open_node(cnode)
return height
def _do_layout_node(self, node, level, y):
if self.hide_root and node is self.root:
level -= 1
else:
node.x = self.x + self.indent_start + level * self.indent_level
node.top = y
if node.size_hint_x:
node.width = (self.width - (node.x - self.x)) \
* node.size_hint_x
y -= node.height
if not node.is_open:
return y
for cnode in node.nodes:
y = self._do_layout_node(cnode, level + 1, y)
return y
[docs] def on_touch_down(self, touch):
node = self.get_node_at_pos(touch.pos)
if not node:
return
if node.disabled:
return
# toggle node or selection ?
if node.x - self.indent_start <= touch.x < node.x:
self.toggle_node(node)
elif node.x <= touch.x:
self.select_node(node)
node.dispatch('on_touch_down', touch)
return True
#
# Private properties
#
_root = ObjectProperty(None)
_selected_node = ObjectProperty(None, allownone=True)
#
# Properties
#
minimum_width = NumericProperty(0)
'''Minimum width needed to contain all children.
.. versionadded:: 1.0.9
:attr:`minimum_width` is a :class:`~kivy.properties.NumericProperty` and
defaults to 0.
'''
minimum_height = NumericProperty(0)
'''Minimum height needed to contain all children.
.. versionadded:: 1.0.9
:attr:`minimum_height` is a :class:`~kivy.properties.NumericProperty` and
defaults to 0.
'''
minimum_size = ReferenceListProperty(minimum_width, minimum_height)
'''Minimum size needed to contain all children.
.. versionadded:: 1.0.9
:attr:`minimum_size` is a :class:`~kivy.properties.ReferenceListProperty`
of (:attr:`minimum_width`, :attr:`minimum_height`) properties.
'''
indent_level = NumericProperty('16dp')
'''Width used for the indentation of each level except the first level.
Computation of indent for each level of the tree is::
indent = indent_start + level * indent_level
:attr:`indent_level` is a :class:`~kivy.properties.NumericProperty` and
defaults to 16.
'''
indent_start = NumericProperty('24dp')
'''Indentation width of the level 0 / root node. This is mostly the initial
size to accommodate a tree icon (collapsed / expanded). See
:attr:`indent_level` for more information about the computation of level
indentation.
:attr:`indent_start` is a :class:`~kivy.properties.NumericProperty` and
defaults to 24.
'''
hide_root = BooleanProperty(False)
'''Use this property to show/hide the initial root node. If True, the root
node will be appear as a closed node.
:attr:`hide_root` is a :class:`~kivy.properties.BooleanProperty` and
defaults to False.
'''
def get_selected_node(self):
return self._selected_node
selected_node = AliasProperty(get_selected_node, None,
bind=('_selected_node', ))
'''Node selected by :meth:`TreeView.select_node` or by touch.
:attr:`selected_node` is a :class:`~kivy.properties.AliasProperty` and
defaults to None. It is read-only.
'''
def get_root(self):
return self._root
root = AliasProperty(get_root, None, bind=('_root', ))
'''Root node.
By default, the root node widget is a :class:`TreeViewLabel` with text
'Root'. If you want to change the default options passed to the widget
creation, use the :attr:`root_options` property::
treeview = TreeView(root_options={
'text': 'Root directory',
'font_size': 15})
:attr:`root_options` will change the properties of the
:class:`TreeViewLabel` instance. However, you cannot change the class used
for root node yet.
:attr:`root` is an :class:`~kivy.properties.AliasProperty` and defaults to
None. It is read-only. However, the content of the widget can be changed.
'''
root_options = ObjectProperty({})
'''Default root options to pass for root widget. See :attr:`root` property
for more information about the usage of root_options.
:attr:`root_options` is an :class:`~kivy.properties.ObjectProperty` and
defaults to {}.
'''
load_func = ObjectProperty(None)
'''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)
:attr:`load_func` is a :class:`~kivy.properties.ObjectProperty` and
defaults to None.
'''
if __name__ == '__main__':
from kivy.app import App
class TestApp(App):
def build(self):
tv = TreeView(hide_root=True)
add = tv.add_node
root = add(TreeViewLabel(text='Level 1, entry 1', is_open=True))
for x in range(5):
add(TreeViewLabel(text='Element %d' % x), root)
root2 = add(TreeViewLabel(text='Level 1, entry 2', is_open=False))
for x in range(24):
add(TreeViewLabel(text='Element %d' % x), root2)
for x in range(5):
add(TreeViewLabel(text='Element %d' % x), root)
root2 = add(TreeViewLabel(text='Element childs 2', is_open=False),
root)
for x in range(24):
add(TreeViewLabel(text='Element %d' % x), root2)
return tv
TestApp().run()
