gtk.TreeModel

gtk.TreeModel
Prev	The gtk Class Reference	Next

gtk.TreeModel — the tree interface used by gtk.TreeView

Synopsis

class gtk.TreeModel(gobject.GInterface):
    def get_flags()
    def get_n_columns()
    def get_column_type(index)
    def get_iter(path)
    def get_iter_from_string(path_string)
    def get_string_from_iter(iter)
    def get_iter_root()
    def get_iter_first()
    def get_path(iter)
    def get_value(iter, column)
    def iter_next(iter)
    def iter_children(parent)
    def iter_has_child(iter)
    def iter_n_children(iter)
    def iter_nth_child(parent, n)
    def iter_parent(child)
    def ref_node(iter)
    def unref_node(iter)
    def get(iter, column, ...)
    def foreach(func, user_data)
    def row_changed(path, iter)
    def row_inserted(path, iter)
    def row_has_child_toggled(path, iter)
    def row_deleted(path)
    def rows_reordered(path, iter, new_order)
    def filter_new(root=None)

Functions

    def gtk.tree_row_reference_inserted(proxy, path)
    def gtk.tree_row_reference_deleted(proxy, path)

gtk.TreeModel Signal Prototypes

"row-changed"	`def callback(treemodel, path, iter, user_param1, ...)`
"row-deleted"	`def callback(treemodel, path, user_param1, ...)`
"row-has-child-toggled"	`def callback(treemodel, path, iter, user_param1, ...)`
"row-inserted"	`def callback(treemodel, path, iter, user_param1, ...)`
"rows-reordered"	`def callback(treemodel, path, iter, new_order, user_param1, ...)`

Description

The gtk.TreeModel interface defines a generic tree interface for use by the gtk.TreeView widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer just has to implement this interface on their own data type for it to be viewable by a gtk.TreeView widget.

The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column is determined by using the Python or GObject type system (i.e. gobject.TYPE_INT, gtk.BUTTON, gobject.TYPE_STRING, etc.). The types are homogeneous per column across all nodes. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made.

In order to make life simpler for programmers who do not need to write their own specialized model, two generic models are provided: the gtk.TreeStore and the gtk.ListStore. To use these, the developer simply pushes data into these models as necessary. These models provide the data structure as well as all appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For the vast majority of trees and lists, these two models are sufficient.

Models are accessed on a node-column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. A particular node in a model is referenced using a path or a gtk.TreeIter object. Most of the interface consists of operations on a gtk.TreeIter.

A path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. A path can be converted into either an array of unsigned integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the offset at that level. Thus, the path "0" refers to the root node and the path "2:4" refers to the fifth child of the third node.

By contrast, a gtk.TreeIter is a reference to a specific node on a specific model. One can convert a path to a treeiter by calling get_iter(). These treeiters are the primary way of accessing a model and are similar to the textiters used by gtk.TextBuffer. The model interface defines a set of operations using them for navigating the model.

It is expected that models fill in the treeiter with private data. For example, the gtk.ListStore model, which is internally a simple linked list, stores a list node in one of the pointers. The gtk.TreeModelSort stores an array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled with a unique stamp per model. This stamp is for catching errors resulting from using invalid treeiters with a model.

The lifecycle of a treeiter can be a little confusing at first. treeiters are expected to always be valid for as long as the model is unchanged (and doesn't emit a signal). The model is considered to own all outstanding treeiters and nothing needs to be done to free them from the user's point of view. Additionally, some models guarantee that an treeiter is valid for as long as the node it refers to is valid (most notably the gtk.TreeStore and gtk.ListStore). Although generally uninteresting, as one always has to allow for the case where treeiters do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the gtk.TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.

A gtk.TreeModel object supports some of the Python Mapping protocol that allows you to retrieve a gtk.TreeModelRow object representing a row in the model. You can also set the values in a row using the same protocol. For example, you can retrieve the second row of a gtk.TreeModel using any of:

  treemodelrow = model[1]
  treemodelrow = model[(1,)]
  treemodelrow = model['1']
  treemodelrow = model["1"]

Also if the model has two columns both containing strings then the following will set the values of the third row.

  model[(2,)] = ('new string value', 'string 2')

You can also retrieve the number of top level items in the gtk.TreeModel by using the Python len() function:

  n_rows = len(model)

A gtk.TreeModelRowIter object can be retrieved for iterating over the top level rows of a gtk.TreeModel by calling the Python iter() function:

  treemodelrowiter = iter(model)

See the PyGTK tutorial for more information.

Methods

gtk.TreeModel.get_flags

    def get_flags()

Returns :

the flags supported by this interface.

The get_flags() method returns a set of flags supported by this interface. The flags are a bitwise combination of:

`gtk.TREE_MODEL_ITERS_PERSIST`	Treeiters survive all signals emitted by the tree.
`gtk.TREE_MODEL_LIST_ONLY`	The model is a list only, and never has children

The flags supported should not change during the lifecycle of the tree_model.

gtk.TreeModel.get_n_columns

    def get_n_columns()

Returns :

The number of columns.

The get_n_columns() method returns the number of columns supported by the treemodel.

gtk.TreeModel.get_column_type

    def get_column_type(index)

`index` :	the column index.
Returns :	the type of the column.

The get_column_type() method returns the type of the column.

gtk.TreeModel.get_iter

    def get_iter(path)

`path` :	a path
Returns :	a new `gtk.TreeIter` that points at `path`.

The get_iter() method returns a new gtk.TreeIter pointing to path. This method raises a ValueError exception if path is not a valid tree path.

gtk.TreeModel.get_iter_from_string

    def get_iter_from_string(path_string)

`path_string` :	a string representation of a path.
Returns :	a new `gtk.TreeIter` that points at the path represented by `path_string`

The get_iter_from_string() method returns a gtk.TreeIter pointing to the path represented by path_string, if it exists. This method raises a ValueError exception if path_string does not represent a valid tree path.

gtk.TreeModel.get_string_from_iter

    def get_string_from_iter(iter)

`iter` :	An `gtk.TreeIter`.
Returns :	A string representation of iter

Note

This method is available in PyGTK 2.2 and above.

The get_string_from_iter() method returns a string representation of the path pointed to by iter. This string is a ':' separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.

gtk.TreeModel.get_iter_root

    def get_iter_root()

Returns : a new gtk.TreeIter that points at the first path in the treemodel or None

The get_iter_root() method returns a gtk.TreeIter pointing to the path "0" or None if the tree is empty.

gtk.TreeModel.get_iter_first

    def get_iter_first()

Returns : a new gtk.TreeIter that points at the first path in the treemodel or None

The get_iter_first() method returns a gtk.TreeIter pointing to the path "0" or None if the tree is empty.

gtk.TreeModel.get_path

    def get_path(iter)

`iter` :	a `gtk.TreeIter`.
Returns :	the tree path referenced by `iter`.

The get_path() method returns the tree path referenced by iter.

gtk.TreeModel.get_value

    def get_value(iter, column)

`iter` :	a `gtk.TreeIter`.
`column` :	the column value to retrieve.
Returns :	a value.

The get_value() method returns the value at column at the path pointed to by iter.

gtk.TreeModel.iter_next

    def iter_next(iter)

`iter` :	a `gtk.TreeIter`.
Returns :	a `gtk.TreeIter` pointing at the next row or `None` if there is no next row.

The iter_next() method returns a gtk.TreeIter pointing at the row at the current level after the row referenced by iter. If there is no next row, None is returned. iter is unchanged.

gtk.TreeModel.iter_children

    def iter_children(parent)

`parent` :	the `gtk.TreeIter` pointing to the parent
Returns :	the new `gtk.TreeIter` to be set to the first child or `None`

The iter_children() method returns a new gtk.TreeIter pointing to the first child of parent. If parent has no children, None is returned. parent will remain a valid node after this method has been called.

gtk.TreeModel.iter_has_child

    def iter_has_child(iter)

`iter` :	a `gtk.TreeIter` to test for children.
Returns :	`TRUE` if `iter` has children.

The iter_has_child() method returns TRUE if iter has children, or FALSE otherwise.

gtk.TreeModel.iter_n_children

    def iter_n_children(iter)

`iter` :	a `gtk.TreeIter`, or `None`.
Returns :	the number of children of `iter`.

The iter_n_children() method returns the number of children that iter has. As a special case, if iter is None, then the number of top level nodes is returned.

gtk.TreeModel.iter_nth_child

    def iter_nth_child(parent, n)

`parent` :	a `gtk.TreeIter` to get the child from, or `None`.
`n` :	Then index of the desired child.
Returns :	the `gtk.TreeIter` that is set to the nth child or `None`

The iter_nth_child() method returns a new gtk.TreeIter pointing to the child of parent, with the index specified by n. The first index is 0. If n is too big, or parent has no children, this method returns None. parent will remain a valid node after this function has been called. As a special case, if parent is None, then the treeiter points to the nth root node.

gtk.TreeModel.iter_parent

    def iter_parent(child)

`child` :	The `gtk.TreeIter`.
Returns :	a new `gtk.TreeIter` set to the parent of `child` or `None`

The iter_parent() method returns a gtk.TreeIter pointing to the parent of child. If child is at the top level, and doesn't have a parent, then None is returned. child will remain a valid node after this method has been called.

gtk.TreeModel.ref_node

    def ref_node(iter)

iter : a gtk.TreeIter.

The ref_node() method lets the treemodel ref the node that iter points to. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let the caching model know when nodes are being displayed (and hence, whether or not to cache that node.) For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get a treeiter independent of it's reffed state.

gtk.TreeModel.unref_node

    def unref_node(iter)

iter : a gtk.TreeIter.

The unref_node() method lets the treemodel unref the node that iter points to. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see the ref_node() method. Please note that nodes that are deleted are not unreffed.

gtk.TreeModel.get

    def get(iter, column, ...)

`iter` :	a `gtk.TreeIter` pointing at the row to retrieve data value from
`column` :	a column number
`...` :	zero or more column numbers
Returns :	a tuple containing the column values

Note

This method is available in PyGTK 2.4 and above.

The get() method returns a tuple containing the values of one or more cells in the row referenced by the gtk.TreeIter specified by iter. column specifies the first column number to retrieve a value from. The additional arguments should contain integer column numbers for additional column values. For example, to get values from columns 0 and 3, you would write:

  value0, value3 = treemodel_get(iter, 0, 3)

gtk.TreeModel.foreach

    def foreach(func, user_data)

`func` :	a function to be called on each row
`user_data` :	the user data to passed to `func`.

The foreach() method calls func on each node in model in a depth-first fashion. user_data is passed to func each time it is called. If func returns TRUE, then the operation ceases, and foreach() returns.

The signature of func is:

  def func(model, path, iter, user_data)

where model is the treemodel, path is the current path, and iter is a treeiter pointing to path.

If func is an object method its signature will be:

  def func(self, model, path, iter, user_data)

gtk.TreeModel.row_changed

    def row_changed(path, iter)

`path` :	a path pointing to the changed row
`iter` :	a `gtk.TreeIter` pointing to the changed row

The row_changed() method emits the "row-changed" signal on the treemodel with the parameters path and iter that are the path and a treeiter pointing to the path of the changed row.

gtk.TreeModel.row_inserted

    def row_inserted(path, iter)

`path` :	a path pointing to the inserted row
`iter` :	a `gtk.TreeIter` pointing to the inserted row

The row_inserted() method emits the "row-inserted" signal on the treemodel with the parameters path and iter that are the path and a treeiter pointing to the path of the inserted row.

gtk.TreeModel.row_has_child_toggled

    def row_has_child_toggled(path, iter)

`path` :	a path pointing to the changed row
`iter` :	a `gtk.TreeIter` pointing to the changed row

The row_has_child_toggled() method emits the "row-has-child-toggled" signal on the treemodel with the parameters path and iter that are the path and a treeiter pointing to the path of the changed row. This should be called by models after the child state of a node changes.

gtk.TreeModel.row_deleted

    def row_deleted(path)

path : a path pointing to the previous location of the deleted row.

The row_deleted() method emits the "row-deleted" signal on the treemodel. This should be called by models after a row has been removed. The location pointed to by path should be the location that the deleted row was at. It may not be a valid location anymore.

gtk.TreeModel.rows_reordered

    def rows_reordered(path, iter, new_order)

`path` :	A tree path pointing to the tree node whose children have been reordered, or `None` or () or "" to indicate the top level node.
`iter` :	A valid `gtk.TreeIter` pointing to the node whose children have been reordered, or `None` to indicate the top level node.
`new_order` :	a sequence of integers containing the new indexes of the children, i.e. the former child `n` is now at the position specified by `new_order``[n]`.

The rows_reordered() method emits the "rows_reordered" signal on the tree model. This method should be called by a tree model when its rows have been reordered. If iter is None to indicate that the top level rows have been reordered, path should be None or () or "".

gtk.TreeModel.filter_new

    def filter_new(root=None)

`root` :	a tree path or `None`.
Returns :	A new `gtk.TreeModel`.

Note

This method is available in PyGTK 2.4 and above.

The filter_new() method creates a new gtk.TreeModel, with the tree model as the child_model and the virtual root specified by root.

Functions

gtk.tree_row_reference_inserted

    def gtk.tree_row_reference_inserted(proxy, path)

`proxy` :	a `GObject`
`path` :	a row position that was inserted

The gtk.tree_row_reference_inserted() function lets a set of row references know that the model emitted the "row_inserted" signal for the row specified by path.

gtk.tree_row_reference_deleted

    def gtk.tree_row_reference_deleted(proxy, path)

`proxy` :	a `GObject`
`path` :	a row position that was deleted

The gtk.tree_row_reference_deleted() function lets a set of row references know that the model emitted the "row_deleted" signal for the row specified by path.

Signals

The "row-changed" gtk.TreeModel Signal

    def callback(treemodel, path, iter, user_param1, ...)

`treemodel` :	the treemodel that received the signal
`path` :	a path
`iter` :	a `gtk.TreeIter` pointing at `path`
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "row-changed" signal is emitted when the row specified by path and pointed to by iter has changed in the treemodel. Usually, this means that one or more column values have changed.

The "row-deleted" gtk.TreeModel Signal

    def callback(treemodel, path, user_param1, ...)

`treemodel` :	the treemodel that received the signal
`path` :	a path
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "row-deleted" signal is emitted when the row that was specified by path is deleted from treemodel.

The "row-has-child-toggled" gtk.TreeModel Signal

    def callback(treemodel, path, iter, user_param1, ...)

`treemodel` :	the treemodel that received the signal
`path` :	a path
`iter` :	a `gtk.TreeIter` pointing at `path`
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "row-has-child-toggled" signal is emitted when the child state of the row specified by path and pointed to by iter has changed in treemodel.

The "row-inserted" gtk.TreeModel Signal

    def callback(treemodel, path, iter, user_param1, ...)

`treemodel` :	the treemodel that received the signal
`path` :	a path
`iter` :	a `gtk.TreeIter` pointing at `path`
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "row-inserted" signal is emitted when the row specified by path and pointed to by iter is inserted into treemodel. The row referenced by iter will be empty so using the get_value() method will always return None. Connect to the "row-changed" signal if you want to track value changes.

The "rows-reordered" gtk.TreeModel Signal

    def callback(treemodel, path, iter, new_order, user_param1, ...)

`treemodel` :	the treemodel that received the signal
`path` :	a path
`iter` :	a `gtk.TreeIter` pointing at `path`
`new_order` :	an array of reordered row numbers
`user_param1` :	the first user parameter (if any) specified with the `connect`() method
`...` :	additional user parameters (if any)

The "rows-reordered" signal is emitted when the treemodel child rows of the row specified by path and pointed to by iter are reordered. new_order is an array of node index numbers representing the new order of the rows. The value of new_order cannot be retrieved in PyGTK because it is passed as an opaque pointer (gobject.GPointer) value. iter may be None and path an empty tuple to indicate that the top level rows were reordered.