pygtkcompat/generictreemodel.py

   1 # -*- Mode: Python; py-indent-offset: 4 -*-
   2 # generictreemodel - GenericTreeModel implementation for pygtk compatibility.
   3 # Copyright (C) 2013 Simon Feltman
   4 #
   5 #   generictreemodel.py: GenericTreeModel implementation for pygtk compatibility
   6 #
   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.
  11 #
  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.
  16 #
  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/>.
  19
  20
  21 # System
  22 import sys
  23 import random
  24 import collections
  25 import ctypes
  26 import platform
  27
  28 # GObject
  29 from gi.repository import GObject
  30 from gi.repository import Gtk
  31
  32
  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)]
  38
  39     @classmethod
  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)
  43
  44
  45 if platform.python_implementation() == "PyPy":
  46     def _get_user_data_as_pyobject(iter):
  47         raise NotImplementedError("Not yet supported under PyPy")
  48 else:
  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
  52
  53
  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.
  57
  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.
  61     """
  62     def decorator(func):
  63         def wrapped_func(*args, **kargs):
  64             try:
  65                 return func(*args, **kargs)
  66             except:
  67                 # Use excepthook directly to avoid any printing to the screen
  68                 # if someone installed an except hook.
  69                 sys.excepthook(*sys.exc_info())
  70             return default_return
  71         return wrapped_func
  72     return decorator
  73
  74
  75 class GenericTreeModel(GObject.GObject, Gtk.TreeModel):
  76     """A base implementation of a Gtk.TreeModel for python.
  77
  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.
  81
  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
  86     python objects.
  87
  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.
  90
  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.
  98     """
  99
 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.")
 104
 105     #
 106     # Methods
 107     #
 108     def __init__(self):
 109         """Initialize. Make sure to call this from derived classes if overridden."""
 110         super(GenericTreeModel, self).__init__()
 111         self.stamp = 0
 112
 113         #: Dictionary of (id(user_data): user_data), used when leak-refernces=False
 114         self._held_refs = dict()
 115
 116         # Set initial stamp
 117         self.invalidate_iters()
 118
 119     def iter_depth_first(self):
 120         """Depth-first iteration of the entire TreeModel yielding the python nodes."""
 121         stack = collections.deque([None])
 122         while stack:
 123             it = stack.popleft()
 124             if it is not 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))
 128
 129     def invalidate_iter(self, iter):
 130         """Clear user data and its reference from the iter and this model."""
 131         iter.stamp = 0
 132         if iter.user_data:
 133             if iter.user_data in self._held_refs:
 134                 del self._held_refs[iter.user_data]
 135             iter.user_data = None
 136
 137     def invalidate_iters(self):
 138         """
 139         This method invalidates all TreeIter objects associated with this custom tree model
 140         and frees their locally pooled references.
 141         """
 142         self.stamp = random.randint(-2147483648, 2147483647)
 143         self._held_refs.clear()
 144
 145     def iter_is_valid(self, iter):
 146         """
 147         :Returns:
 148             True if the gtk.TreeIter specified by iter is valid for the custom tree model.
 149         """
 150         return iter.stamp == self.stamp
 151
 152     def get_user_data(self, iter):
 153         """Get the user_data associated with the given TreeIter.
 154
 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.
 157         """
 158         if self.leak_references:
 159             return self._held_refs[iter.user_data]
 160         else:
 161             return _get_user_data_as_pyobject(iter)
 162
 163     def set_user_data(self, iter, user_data):
 164         """Applies user_data and stamp to the given iter.
 165
 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.
 169         """
 170         iter.user_data = id(user_data)
 171
 172         if user_data is None:
 173             self.invalidate_iter(iter)
 174         else:
 175             iter.stamp = self.stamp
 176             if self.leak_references:
 177                 self._held_refs[iter.user_data] = user_data
 178
 179     def create_tree_iter(self, user_data):
 180         """Create a Gtk.TreeIter instance with the given user_data specific for this model.
 181
 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.
 184         """
 185         iter = Gtk.TreeIter()
 186         self.set_user_data(iter, user_data)
 187         return iter
 188
 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."""
 192         if data is None:
 193             return (False, None)
 194         else:
 195             it = self.create_tree_iter(data)
 196             return (True, it)
 197
 198     def row_deleted(self, path, node=None):
 199         """Notify the model a row has been deleted.
 200
 201         Use the node parameter to ensure the user_data reference associated
 202         with the path is properly freed by this model.
 203
 204         :Parameters:
 205             path : Gtk.TreePath
 206                 Path to the row that has been deleted.
 207             node : object
 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.
 210         """
 211         super(GenericTreeModel, self).row_deleted(path)
 212         node_id = id(node)
 213         if node_id in self._held_refs:
 214             del self._held_refs[node_id]
 215
 216     #
 217     # GtkTreeModel Interface Implementation
 218     #
 219     @handle_exception(0)
 220     def do_get_flags(self):
 221         """Internal method."""
 222         return self.on_get_flags()
 223
 224     @handle_exception(0)
 225     def do_get_n_columns(self):
 226         """Internal method."""
 227         return self.on_get_n_columns()
 228
 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)
 233
 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))
 238
 239     @handle_exception(False)
 240     def do_iter_next(self, iter):
 241         """Internal method."""
 242         if iter is None:
 243             next_data = self.on_iter_next(None)
 244         else:
 245             next_data = self.on_iter_next(self.get_user_data(iter))
 246
 247         self.set_user_data(iter, next_data)
 248         return next_data is not None
 249
 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))
 254         if path is None:
 255             return None
 256         else:
 257             return Gtk.TreePath(path)
 258
 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)
 263
 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))
 269
 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))
 274
 275     @handle_exception(0)
 276     def do_iter_n_children(self, iter):
 277         """Internal method."""
 278         if iter is None:
 279             return self.on_iter_n_children(None)
 280         return self.on_iter_n_children(self.get_user_data(iter))
 281
 282     @handle_exception((False, None))
 283     def do_iter_nth_child(self, parent, n):
 284         """Internal method."""
 285         if parent is None:
 286             data = self.on_iter_nth_child(None, n)
 287         else:
 288             data = self.on_iter_nth_child(self.get_user_data(parent), n)
 289         return self._create_tree_iter(data)
 290
 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)))
 295
 296     @handle_exception(None)
 297     def do_ref_node(self, iter):
 298         self.on_ref_node(self.get_user_data(iter))
 299
 300     @handle_exception(None)
 301     def do_unref_node(self, iter):
 302         self.on_unref_node(self.get_user_data(iter))
 303
 304     #
 305     # Python Subclass Overridables
 306     #
 307     def on_get_flags(self):
 308         """Overridable.
 309
 310         :Returns Gtk.TreeModelFlags:
 311             The flags for this model. See: Gtk.TreeModelFlags
 312         """
 313         raise NotImplementedError
 314
 315     def on_get_n_columns(self):
 316         """Overridable.
 317
 318         :Returns:
 319             The number of columns for this model.
 320         """
 321         raise NotImplementedError
 322
 323     def on_get_column_type(self, index):
 324         """Overridable.
 325
 326         :Returns:
 327             The column type for the given index.
 328         """
 329         raise NotImplementedError
 330
 331     def on_get_iter(self, path):
 332         """Overridable.
 333
 334         :Returns:
 335             A python object (node) for the given TreePath.
 336         """
 337         raise NotImplementedError
 338
 339     def on_iter_next(self, node):
 340         """Overridable.
 341
 342         :Parameters:
 343             node : object
 344                 Node at current level.
 345
 346         :Returns:
 347             A python object (node) following the given node at the current level.
 348         """
 349         raise NotImplementedError
 350
 351     def on_get_path(self, node):
 352         """Overridable.
 353
 354         :Returns:
 355             A TreePath for the given node.
 356         """
 357         raise NotImplementedError
 358
 359     def on_get_value(self, node, column):
 360         """Overridable.
 361
 362         :Parameters:
 363             node : object
 364             column : int
 365                 Column index to get the value from.
 366
 367         :Returns:
 368             The value of the column for the given node."""
 369         raise NotImplementedError
 370
 371     def on_iter_children(self, parent):
 372         """Overridable.
 373
 374         :Returns:
 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.
 377         """
 378         raise NotImplementedError
 379
 380     def on_iter_has_child(self, node):
 381         """Overridable.
 382
 383         :Returns:
 384             True if the given node has children.
 385         """
 386         raise NotImplementedError
 387
 388     def on_iter_n_children(self, node):
 389         """Overridable.
 390
 391         :Returns:
 392             The number of children for the given node. If node is None,
 393             return the number of top level nodes.
 394         """
 395         raise NotImplementedError
 396
 397     def on_iter_nth_child(self, parent, n):
 398         """Overridable.
 399
 400         :Parameters:
 401             parent : object
 402             n : int
 403                 Index of child within parent.
 404
 405         :Returns:
 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.
 409         """
 410         raise NotImplementedError
 411
 412     def on_iter_parent(self, child):
 413         """Overridable.
 414
 415         :Returns:
 416             The parent node of child or None if child is a top level node."""
 417         raise NotImplementedError
 418
 419     def on_ref_node(self, node):
 420         pass
 421
 422     def on_unref_node(self, node):
 423         pass