gtk.TreeModel the tree interface used by gtk.TreeView gtk.TreeModel gobject.GInterface get_flags get_n_columns get_column_type index get_iter path get_iter_from_string path_string get_string_from_iter iter get_iter_root get_iter_first get_path iter get_value iter column iter_next iter iter_children parent iter_has_child iter iter_n_children iter iter_nth_child parent n iter_parent child ref_node iter unref_node iter get iter column ... foreach func user_data row_changed path iter row_inserted path iter row_has_child_toggled path iter row_deleted path rows_reordered path iter new_order filter_new rootNone Functions gtk.tree_row_reference_inserted proxy path gtk.tree_row_reference_deleted proxy path "row-changed" callback treemodel path iter user_param1 ... "row-deleted" callback treemodel path user_param1 ... "row-has-child-toggled" callback treemodel path iter user_param1 ... "row-inserted" callback treemodel path iter user_param1 ... "rows-reordered" callback treemodel path iter new_order user_param1 ... 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. 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. get_n_columns Returns : The number of columns. The get_n_columns() method returns the number of columns supported by the treemodel. 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. 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. 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. get_string_from_iter 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. 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. 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. 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. 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. 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. 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(). 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. 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. 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. 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. 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. 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. 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 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) 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) 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. 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. 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. 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. 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 "". filter_new rootNone root : 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. 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 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. 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. 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. 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. 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. 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.