gtk.TreeModel — the tree interface used by gtk.TreeView
class gtk.TreeModel(gobject.GInterface): |
Functionsdef gtk.tree_row_reference_inserted(proxy,path)def gtk.tree_row_reference_deleted(proxy,path)
def callback( | |
def callback( | |
def callback( | |
def callback( | |
def callback( |
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.
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:
| Treeiters survive all signals emitted by the tree. |
| The model is a list only, and never has children |
The flags supported should not change during the lifecycle of the tree_model.
def get_n_columns()Returns : | The number of columns. |
The get_n_columns() method returns the
number of columns supported by the treemodel.
def get_column_type(index)
| the column index. |
Returns : | the type of the column. |
The get_column_type() method returns
the type of the column.
def get_iter(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.
def get_iter_from_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.
def get_string_from_iter(iter)
| An gtk.TreeIter. |
Returns : | A string representation of iter |
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.
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.
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.
def get_path(iter)
| a gtk.TreeIter. |
Returns : | the tree path referenced by
iter. |
The get_path() method returns the tree
path referenced by iter.
def get_value(iter, column)
| a gtk.TreeIter. |
| the column value to retrieve. |
Returns : | a value. |
The get_value() method returns the
value at column at the path pointed to by
iter.
def iter_next(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.
def iter_children(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().
def iter_has_child(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.
def iter_n_children(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.
def iter_nth_child(parent, n)
| a gtk.TreeIter to
get the child from, or None. |
| 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.
def iter_parent(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.
def ref_node(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.
def unref_node(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.
def get(iter, column, ...)
| a gtk.TreeIter
pointing at the row to retrieve data value
from |
| a column number |
| zero or more column numbers |
Returns : | a tuple containing the column values |
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)
def foreach(func, user_data)
| a function to be called on each row |
| 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)
def row_changed(path, iter)
| a path pointing to the changed row |
| 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.
def row_inserted(path, iter)
| a path pointing to the inserted row |
| 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.
def row_has_child_toggled(path, iter)
| a path pointing to the changed row |
| 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.
def row_deleted(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.
def rows_reordered(path, iter, new_order)
| A tree path pointing to the tree node whose
children have been reordered, or None or () or
"" to indicate the top level node. |
| A valid gtk.TreeIter
pointing to the node whose children have been reordered, or
None to indicate the top level
node. |
| 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 "".
def filter_new(root=None)
| a tree path or
None. |
Returns : | A new gtk.TreeModel. |
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.
def callback(treemodel, path, iter, user_param1, ...)
| the treemodel that received the signal |
| a path |
| a gtk.TreeIter
pointing at path |
| the first user parameter (if any) specified
with the connect() |
| 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.
def callback(treemodel, path, user_param1, ...)
| the treemodel that received the signal |
| a path |
| the first user parameter (if any) specified
with the connect() |
| additional user parameters (if any) |
The "row-deleted" signal is emitted when the row that was
specified by path is deleted from
treemodel.
def callback(treemodel, path, iter, user_param1, ...)
| the treemodel that received the signal |
| a path |
| a gtk.TreeIter
pointing at path |
| the first user parameter (if any) specified
with the connect() |
| 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.
def callback(treemodel, path, iter, user_param1, ...)
| the treemodel that received the signal |
| a path |
| a gtk.TreeIter
pointing at path |
| the first user parameter (if any) specified
with the connect() |
| 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.
def callback(treemodel, path, iter, new_order, user_param1, ...)
| the treemodel that received the signal |
| a path |
| a gtk.TreeIter
pointing at path |
| an array of reordered row numbers |
| the first user parameter (if any) specified
with the connect() |
| 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.GPointeriter may be None and
path an empty tuple to indicate that the top
level rows were reordered.