gtk.TreeModelFilter
Prev | The gtk Class Reference | Next

## gtk.TreeModelFilter

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.

Prev | Up | Next
gtk.TreeModel | Home | gtk.TreeModelSort