1 # -*- Mode: Python; py-indent-offset: 4 -*-
2 # generictreemodel - GenericTreeModel implementation for pygtk compatibility.
3 # Copyright (C) 2013 Simon Feltman
5 # generictreemodel.py: GenericTreeModel implementation for pygtk compatibility
7 # This library is free software; you can redistribute it and/or
8 # modify it under the terms of the GNU Lesser General Public
9 # License as published by the Free Software Foundation; either
10 # version 2.1 of the License, or (at your option) any later version.
12 # This library is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 # Lesser General Public License for more details.
17 # You should have received a copy of the GNU Lesser General Public
18 # License along with this library; if not, see <http://www.gnu.org/licenses/>.
29 from gi
.repository
import GObject
30 from gi
.repository
import Gtk
33 class _CTreeIter(ctypes
.Structure
):
34 _fields_
= [('stamp', ctypes
.c_int
),
35 ('user_data', ctypes
.c_void_p
),
36 ('user_data2', ctypes
.c_void_p
),
37 ('user_data3', ctypes
.c_void_p
)]
40 def from_iter(cls
, iter):
41 offset
= sys
.getsizeof(object()) # size of PyObject_HEAD
42 return ctypes
.POINTER(cls
).from_address(id(iter) + offset
)
45 if platform
.python_implementation() == "PyPy":
46 def _get_user_data_as_pyobject(iter):
47 raise NotImplementedError("Not yet supported under PyPy")
49 def _get_user_data_as_pyobject(iter):
50 citer
= _CTreeIter
.from_iter(iter)
51 return ctypes
.cast(citer
.contents
.user_data
, ctypes
.py_object
).value
54 def handle_exception(default_return
):
55 """Returns a function which can act as a decorator for wrapping exceptions and
56 returning "default_return" upon an exception being thrown.
58 This is used to wrap Gtk.TreeModel "do_" method implementations so we can return
59 a proper value from the override upon an exception occurring with client code
60 implemented by the "on_" methods.
63 def wrapped_func(*args
, **kargs
):
65 return func(*args
, **kargs
)
67 # Use excepthook directly to avoid any printing to the screen
68 # if someone installed an except hook.
69 sys
.excepthook(*sys
.exc_info())
75 class GenericTreeModel(GObject
.GObject
, Gtk
.TreeModel
):
76 """A base implementation of a Gtk.TreeModel for python.
78 The GenericTreeModel eases implementing the Gtk.TreeModel interface in Python.
79 The class can be subclassed to provide a TreeModel implementation which works
80 directly with Python objects instead of iterators.
82 All of the on_* methods should be overridden by subclasses to provide the
83 underlying implementation a way to access custom model data. For the purposes of
84 this API, all custom model data supplied or handed back through the overridable
85 API will use the argument names: node, parent, and child in regards to user data
88 The create_tree_iter, set_user_data, invalidate_iters, iter_is_valid methods are
89 available to help manage Gtk.TreeIter objects and their Python object references.
91 GenericTreeModel manages a pool of user data nodes that have been used with iters.
92 This pool stores a references to user data nodes as a dictionary value with the
93 key being the integer id of the data. This id is what the Gtk.TreeIter objects
94 use to reference data in the pool.
95 References will be removed from the pool when the model is deleted or explicitly
96 by using the optional "node" argument to the "row_deleted" method when notifying
97 the model of row deletion.
100 leak_references
= GObject
.Property(default
=True, type=bool,
101 blurb
="If True, strong references to user data attached to iters are "
102 "stored in a dictionary pool (default). Otherwise the user data is "
103 "stored as a raw pointer to a python object without a reference.")
109 """Initialize. Make sure to call this from derived classes if overridden."""
110 super(GenericTreeModel
, self
).__init
__()
113 #: Dictionary of (id(user_data): user_data), used when leak-refernces=False
114 self
._held
_refs
= dict()
117 self
.invalidate_iters()
119 def iter_depth_first(self
):
120 """Depth-first iteration of the entire TreeModel yielding the python nodes."""
121 stack
= collections
.deque([None])
125 yield self
.get_user_data(it
)
126 children
= [self
.iter_nth_child(it
, i
) for i
in range(self
.iter_n_children(it
))]
127 stack
.extendleft(reversed(children
))
129 def invalidate_iter(self
, iter):
130 """Clear user data and its reference from the iter and this model."""
133 if iter.user_data
in self
._held
_refs
:
134 del self
._held
_refs
[iter.user_data
]
135 iter.user_data
= None
137 def invalidate_iters(self
):
139 This method invalidates all TreeIter objects associated with this custom tree model
140 and frees their locally pooled references.
142 self
.stamp
= random
.randint(-2147483648, 2147483647)
143 self
._held
_refs
.clear()
145 def iter_is_valid(self
, iter):
148 True if the gtk.TreeIter specified by iter is valid for the custom tree model.
150 return iter.stamp
== self
.stamp
152 def get_user_data(self
, iter):
153 """Get the user_data associated with the given TreeIter.
155 GenericTreeModel stores arbitrary Python objects mapped to instances of Gtk.TreeIter.
156 This method allows to retrieve the Python object held by the given iterator.
158 if self
.leak_references
:
159 return self
._held
_refs
[iter.user_data
]
161 return _get_user_data_as_pyobject(iter)
163 def set_user_data(self
, iter, user_data
):
164 """Applies user_data and stamp to the given iter.
166 If the models "leak_references" property is set, a reference to the
167 user_data is stored with the model to ensure we don't run into bad
168 memory problems with the TreeIter.
170 iter.user_data
= id(user_data
)
172 if user_data
is None:
173 self
.invalidate_iter(iter)
175 iter.stamp
= self
.stamp
176 if self
.leak_references
:
177 self
._held
_refs
[iter.user_data
] = user_data
179 def create_tree_iter(self
, user_data
):
180 """Create a Gtk.TreeIter instance with the given user_data specific for this model.
182 Use this method to create Gtk.TreeIter instance instead of directly calling
183 Gtk.Treeiter(), this will ensure proper reference managment of wrapped used_data.
185 iter = Gtk
.TreeIter()
186 self
.set_user_data(iter, user_data
)
189 def _create_tree_iter(self
, data
):
190 """Internal creation of a (bool, TreeIter) pair for returning directly
191 back to the view interfacing with this model."""
195 it
= self
.create_tree_iter(data
)
198 def row_deleted(self
, path
, node
=None):
199 """Notify the model a row has been deleted.
201 Use the node parameter to ensure the user_data reference associated
202 with the path is properly freed by this model.
206 Path to the row that has been deleted.
208 Python object used as the node returned from "on_get_iter". This is
209 optional but ensures the model will not leak references to this object.
211 super(GenericTreeModel
, self
).row_deleted(path
)
213 if node_id
in self
._held
_refs
:
214 del self
._held
_refs
[node_id
]
217 # GtkTreeModel Interface Implementation
220 def do_get_flags(self
):
221 """Internal method."""
222 return self
.on_get_flags()
225 def do_get_n_columns(self
):
226 """Internal method."""
227 return self
.on_get_n_columns()
229 @handle_exception(GObject
.TYPE_INVALID
)
230 def do_get_column_type(self
, index
):
231 """Internal method."""
232 return self
.on_get_column_type(index
)
234 @handle_exception((False, None))
235 def do_get_iter(self
, path
):
236 """Internal method."""
237 return self
._create
_tree
_iter
(self
.on_get_iter(path
))
239 @handle_exception(False)
240 def do_iter_next(self
, iter):
241 """Internal method."""
243 next_data
= self
.on_iter_next(None)
245 next_data
= self
.on_iter_next(self
.get_user_data(iter))
247 self
.set_user_data(iter, next_data
)
248 return next_data
is not None
250 @handle_exception(None)
251 def do_get_path(self
, iter):
252 """Internal method."""
253 path
= self
.on_get_path(self
.get_user_data(iter))
257 return Gtk
.TreePath(path
)
259 @handle_exception(None)
260 def do_get_value(self
, iter, column
):
261 """Internal method."""
262 return self
.on_get_value(self
.get_user_data(iter), column
)
264 @handle_exception((False, None))
265 def do_iter_children(self
, parent
):
266 """Internal method."""
267 data
= self
.get_user_data(parent
) if parent
else None
268 return self
._create
_tree
_iter
(self
.on_iter_children(data
))
270 @handle_exception(False)
271 def do_iter_has_child(self
, parent
):
272 """Internal method."""
273 return self
.on_iter_has_child(self
.get_user_data(parent
))
276 def do_iter_n_children(self
, iter):
277 """Internal method."""
279 return self
.on_iter_n_children(None)
280 return self
.on_iter_n_children(self
.get_user_data(iter))
282 @handle_exception((False, None))
283 def do_iter_nth_child(self
, parent
, n
):
284 """Internal method."""
286 data
= self
.on_iter_nth_child(None, n
)
288 data
= self
.on_iter_nth_child(self
.get_user_data(parent
), n
)
289 return self
._create
_tree
_iter
(data
)
291 @handle_exception((False, None))
292 def do_iter_parent(self
, child
):
293 """Internal method."""
294 return self
._create
_tree
_iter
(self
.on_iter_parent(self
.get_user_data(child
)))
296 @handle_exception(None)
297 def do_ref_node(self
, iter):
298 self
.on_ref_node(self
.get_user_data(iter))
300 @handle_exception(None)
301 def do_unref_node(self
, iter):
302 self
.on_unref_node(self
.get_user_data(iter))
305 # Python Subclass Overridables
307 def on_get_flags(self
):
310 :Returns Gtk.TreeModelFlags:
311 The flags for this model. See: Gtk.TreeModelFlags
313 raise NotImplementedError
315 def on_get_n_columns(self
):
319 The number of columns for this model.
321 raise NotImplementedError
323 def on_get_column_type(self
, index
):
327 The column type for the given index.
329 raise NotImplementedError
331 def on_get_iter(self
, path
):
335 A python object (node) for the given TreePath.
337 raise NotImplementedError
339 def on_iter_next(self
, node
):
344 Node at current level.
347 A python object (node) following the given node at the current level.
349 raise NotImplementedError
351 def on_get_path(self
, node
):
355 A TreePath for the given node.
357 raise NotImplementedError
359 def on_get_value(self
, node
, column
):
365 Column index to get the value from.
368 The value of the column for the given node."""
369 raise NotImplementedError
371 def on_iter_children(self
, parent
):
375 The first child of parent or None if parent has no children.
376 If parent is None, return the first node of the model.
378 raise NotImplementedError
380 def on_iter_has_child(self
, node
):
384 True if the given node has children.
386 raise NotImplementedError
388 def on_iter_n_children(self
, node
):
392 The number of children for the given node. If node is None,
393 return the number of top level nodes.
395 raise NotImplementedError
397 def on_iter_nth_child(self
, parent
, n
):
403 Index of child within parent.
406 The child for the given parent index starting at 0. If parent None,
407 return the top level node corresponding to "n".
408 If "n" is larger then available nodes, return None.
410 raise NotImplementedError
412 def on_iter_parent(self
, child
):
416 The parent node of child or None if child is a top level node."""
417 raise NotImplementedError
419 def on_ref_node(self
, node
):
422 def on_unref_node(self
, node
):