gtk.GenericTreeModel
Prev | The gtk Class Reference | Next

## gtk.GenericTreeModel

gtk.GenericTreeModel — a TreeView model that helps create tree models in Python

## Synopsis

    class gtk.GenericTreeModel(gobject.GObject, gtk.TreeModel):
        gtk.GenericTreeModel()
        def invalidate_iters()
        def iter_is_valid(iter)
        def get_user_data(iter)
        def create_tree_iter(user_data)

## Ancestry

    +-- gobject.GObject
      +-- gtk.GenericTreeModel (implements gtk.TreeModel)

## Properties

"leak-references" | Read-Write | If `True`, creating a `gtk.TreeIter` will bump the reference count of the object used as the internal row reference. This may cause a memory leak but will prevent problems with objects being destroyed while still in use in a `gtk.TreeIter`. Set this to `False` only if the model saves the objects used in tree iters.

## Description

The `gtk.GenericTreeModel` helps in the creation of `gtk.TreeView` tree models in Python. The `gtk.GenericTreeModel` is subclassed to provide a new tree model that provides the tree model behavior using methods with predefined names that are called by the `gtk.GenericTreeModel` methods as required to provide the various tree model operations. The methods that need to be defined by the programmer in Python are:

`def on_get_flags(`self`)`
`def on_get_n_columns(`self`)`
`def on_get_column_type(`self`, `index`)`
`def on_get_iter(`self`, `path`)`
`def on_get_path(`self`, `rowref`)`
`def on_get_value(`self`, `rowref`, `column`)`
`def on_iter_next(`self`, `rowref`)`
`def on_iter_children(`self`, `parent`)`
`def on_iter_has_child(`self`, `rowref`)`
`def on_iter_n_children(`self`, `rowref`)`
`def on_iter_nth_child(`self`, `parent`, `n`)`
`def on_iter_parent(`self`, `child`)`

See the `gtk.TreeModel` description for details of the above methods.

In PyGTK 2.4 and above the `invalidate_iters`() and `iter_is_valid`() methods are available to help manage the `gtk.TreeIter` objects and their Python object references. These are particularly useful when the "leak-references" property is set to `False`.

The tree models derived from `gtk.GenericTreeModel` are protected from problems with out of date `gtk.TreeIter` objects because `gtk.TreeIter` objects are automatically checked for validity with the tree model.

If a custom tree model doesn't support persistent iters (i.e. `gtk.TREE_MODEL_ITERS_PERSIST` is not set in the return from the `gtk.TreeModel.get_flags`() method), it can call the `invalidate_iters`() method to invalidate all its outstanding `gtk.TreeIter` objects when it changes the model (e.g. after inserting a new row). The tree model can also dispose of any Python objects that it passed references to `gtk.TreeIter` objects after calling the `invalidate_iters`() method.

Applications can use the `iter_is_valid`() method to determine if a `gtk.TreeIter` is still valid for the custom tree model.

## Constructor

        gtk.GenericTreeModel()

Returns : | a new `gtk.GenericTreeModel` object

Creates a new `gtk.GenericTreeModel` object

## Methods

### gtk.GenericTreeModel.invalidate_iters

        def invalidate_iters()

### Note

This method is available in PyGTK 2.4 and above.

The `invalidate_iters`() method invalidates all the `gtk.TreeIter` objects for the custom tree model.

### gtk.GenericTreeModel.iter_is_valid

        def iter_is_valid(iter)

`iter` : | a `gtk.TreeIter`
Returns : | `True` if `iter` is valid for the tree model; otherwise, `False` is returned.

### Note

This method is available in PyGTK 2.4 and above.

The `iter_is_valid`() method returns `True` if the `gtk.TreeIter` specified by `iter` is valid for the custom tree model.

### gtk.GenericTreeModel.get_user_data

        def get_user_data(iter)

`iter` : | a `gtk.TreeIter` created by this tree model.
Returns : | Python object reference that is wrapped by this `gtk.TreeIter`.

### Warning

This method should be treated as protected. It should only be used by derived classes.

`gtk.GenericTreeModel` transparently wraps arbitrary Python objects to instances of `gtk.TreeIter`. E.g. you return anything from `on_get_iter` and the model wraps the value, so `get_iter` method returns a `gtk.TreeIter`. This method allows to retrieve the Python object used to construct given iterator.

### gtk.GenericTreeModel.create_tree_iter

        def create_tree_iter(user_data)

`user_data` : | a Python object, the same you would return from e.g. `on_get_iter`.
Returns : | a `gtk.TreeIter`.

### Warning

This method should be treated as protected. It should only be used by derived classes.

`gtk.GenericTreeModel` transparently wraps arbitrary Python objects to instances of `gtk.TreeIter`. E.g. you return anything from `on_get_iter` and the model wraps the value, so `get_iter` method returns a `gtk.TreeIter`. This method allows you to perform this wrapping explicitly, not just from a predefined set of methods.

Prev | Up | Next
gtk.GenericCellRenderer | Home | gtk.HandleBox