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)
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 or None. |
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.
If parent is None returns
the first node, equivalent to
gtk.TreeModel.get_iter_first().
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)
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)
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)
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 old
indexes of the children in the new order, i.e. the child nodes
have been rearranged so that the treemodel
node that was at position index
new_order[i] is now at
position index i. |
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)
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.
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. The child nodes have been
rearranged so that the treemodel node that was
at position index
new_order[i] is now at
position index i. The value of
new_order cannot be directly 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.
