gtk.TreeModelFilter

gtk.TreeModelFilter
Prev	The gtk Class Reference	Next

gtk.TreeModelFilter — a gtk.TreeModel which hides parts of an underlying tree (new in PyGTK 2.4)

Synopsis

class gtk.TreeModelFilter(gobject.GObject, gtk.TreeModel, gtk.TreeDragSource):
    def set_visible_func(func, data=None)
    def set_modify_func(types, func, data=None)
    def set_visible_column(column)
    def get_model()
    def convert_child_iter_to_iter(child_iter)
    def convert_iter_to_child_iter(filter_iter)
    def convert_child_path_to_path(child_path)
    def convert_path_to_child_path(filter_path)
    def refilter()
    def clear_cache()

Ancestry

+-- gobject.GObject
  +-- gtk.TreeModelFilter (implements gtk.TreeModel, gtk.TreeDragSource)

gtk.TreeModelFilter Properties

"child-model"	Read-Write-Construct Only	The `gtk.TreeModel` for the filtermodel to filter. Available in GTK+ 2.4 and above.
"virtual-root"	Read-Write-Construct Only	The virtual root (relative to the child model) for this filtermodel. Available in GTK+ 2.4 and above.

gtk.TreeModelFilter Signal Prototypes

gobject.GObject Signal Prototypes

gtk.TreeModel Signal Prototypes

Description

Note

This object is available in PyGTK 2.4 and above.

A gtk.TreeModelFilter is a tree model which wraps another tree model, and can do the following things:

Filter specific rows, based on data from a "visible column", a column storing booleans indicating whether the row should be filtered or not, or based on the return value of a "visible function", which gets a model, iter and user_data and returns a boolean indicating whether the row should be filtered or not.
Modify the "appearance" of the model, using a modify function. This is extremely powerful and allows for just changing some values and also for creating a completely different synthetic model based on the child model. For example, you can create a model with columns synthesized from the data in the child model.
Set a different root node, also known as a "virtual root". You can pass in a tree path indicating the root node for the filter at construction time.

A gtk.TreeModelFilter is created using the gtk.TreeModel.filter_new() method. For example:

  liststore = gtk.ListStore(gobject.TYPE_INT, gobject.TYPE_STRING)
  modelfilter = liststore.filter_new()

The gtk.TreeModelFilter objects support the Python mapping and iterator protocols. See the gtk.TreeModel Description and the PyGTK tutorial for more information.

Methods

gtk.TreeModelFilter.set_visible_func

    def set_visible_func(func, data=None)

`func` :	a function called to determine the visibility of a row
`data` :	User data to pass to `func`

Note

This method is available in PyGTK 2.4 and above.

The set_visible_func() method sets the visible function used when filtering the rows of the treemodel filter to the value of func. data is the user data that is passed to func (see below). This method will fail if the set_visible_column() method has already been called. The visible function signature is:

  def visible_func(model, iter, user_data):

where model is the child gtk.TreeModel, iter is a gtk.TreeIter pointing at a row in model and user_data is the data parameter. The function should return TRUE if the row should be visible.

gtk.TreeModelFilter.set_modify_func

    def set_modify_func(types, func, data=None)

`types` :	a sequence containing the column types
`func` :	a function that is called to provide the data for a specific row and column
`data` :	user data to pass to the modify function, or `None`.

Note

This method is available in PyGTK 2.4 and above.

The set_modify_func() method uses the list of column types specified by types and the function specified by func to provide a synthetic model based on the child model of the gtk.TreeModelFilter. data is passed to func when it is called. func is called for each data access to return the data which should be displayed at the location specified using the parameters of the modify function.

The signature of func is:

  def func(model, iter, column, user_data)

where model is the gtk.TreeModelFilter, iter is a gtk.TreeIter pointing at a row in model, column is the column number to provide the value for and user_data is data. func should returns the generated value for the specified location in model.

Note

This method must be called before the gtk.TreeModelFilter is associated with a gtk.TreeView and before either of the gtk.TreeModel.get_n_columns() or gtk.TreeModel.get_column_type() methods are called. Also this method can only be called once - there is no way to change the modify function once it is set.

Since func is called for every access to a value in model, it will be slow for models with a large number of rows and/or columns.

gtk.TreeModelFilter.set_visible_column

    def set_visible_column(column)

column : the number of the column containing the visible information.

Note

This method is available in PyGTK 2.4 and above.

The set_visible_column() method sets the visible column setting to the value of column. The visible column setting contains the number of the "child-model" column that is used to determine the visibility of the model rows. The specified column should be a column of type gobject.TYPE_BOOLEAN, where True means that a row is visible, and False, not visible. This method will fail if the set_visible_func() method has already been called.

gtk.TreeModelFilter.get_model

    def get_model()

Returns : the child gtk.TreeModel

Note

This method is available in PyGTK 2.4 and above.

The get_model() method returns the child gtk.TreeModel of the treemodel filter

gtk.TreeModelFilter.convert_child_iter_to_iter

    def convert_child_iter_to_iter(child_iter)

`child_iter` :	A valid `gtk.TreeIter` pointing to a row on the child model.
Returns :	a `gtk.TreeIter` pointing to a row in the treemodel filter.

Note

This method is available in PyGTK 2.4 and above.

The convert_child_iter_to_iter() method returns a gtk.TreeIter pointing to the row in the treemodel filter that corresponds to the child treemodel row pointed to by the gtk.TreeIter specified by child_iter.

gtk.TreeModelFilter.convert_iter_to_child_iter

    def convert_iter_to_child_iter(filter_iter)

`filter_iter` :	A valid `gtk.TreeIter` pointing to a row in the treemodel filter.
Returns :	a `gtk.TreeIter` pointing to a row in the child treemodel.

Note

This method is available in PyGTK 2.4 and above.

The convert_iter_to_child_iter() method a gtk.TreeIter pointing to the row in the child treemodel that corresponds to the treemodel filter row pointed to by the gtk.TreeIter specified by filter_iter.

gtk.TreeModelFilter.convert_child_path_to_path

    def convert_child_path_to_path(child_path)

`child_path` :	a tree path in the child treemodel to convert.
Returns :	a treemodel filter tree path, or `None`.

Note

This method is available in PyGTK 2.4 and above.

The convert_child_path_to_path() method returns a treemodel filter tree path that corresponds to the child treemodel tree path specified by child_path. If child_path isn't a valid path on the child model, None is returned.

gtk.TreeModelFilter.convert_path_to_child_path

    def convert_path_to_child_path(filter_path)

`filter_path` :	a treemodel filter tree path to convert.
Returns :	a child treemodel tree path, or `None`.

Note

This method is available in PyGTK 2.4 and above.

The convert_path_to_child_path() method returns a child treemodel tree path that corresponds to the treemodel filter tree path specified by filter_path. If filter_path does not point to a row in the child model, None is returned.

gtk.TreeModelFilter.refilter

    def refilter()

Note

This method is available in PyGTK 2.4 and above.

The refilter() method emits the gtk.TreeModel "row-changed" signal for each row in the child model, thereby causing the filter to re-evaluate whether a row is visible or not.

gtk.TreeModelFilter.clear_cache

    def clear_cache()

Note

This method is available in PyGTK 2.4 and above.

The clear_cache() method clears the treemodel filter of any cached iterators that haven't been reffed with the gtk.TreeModel.ref_node(). This might be useful if the child model being filtered is static (and doesn't change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. This method should almost never be called by an application.