gtk.TreeSortable
Prev | The gtk Class Reference | Next

## gtk.TreeSortable

gtk.TreeSortable — an interface for sorting a `gtk.TreeModel`

## Synopsis

    class gtk.TreeSortable(gobject.GInterface):
        def sort_column_changed()
        def get_sort_column_id()
        def set_sort_column_id(sort_column_id, order)
        def set_sort_func(sort_column_id, sort_func, user_data=None)
        def set_default_sort_func(sort_func, user_data=None)
        def has_default_sort_func()

## gtk.TreeSortable Signal Prototypes

"sort-column-changed" | `def callback(`treesortable`, `user_param1`, `...`)`

## Description

The `gtk.TreeSortable` interface provide the common methods for a `gtk.TreeModel` to implement a sorted model for a `gtk.TreeView`. See the `gtk.TreeModelSort` for an example of a treemodel that implements the `gtk.TreeSortable` interface. The key element of the interface is a "sort column ID" which is an arbitrary integer value referring to a sort function and associated user data. A sort column ID must be greater than or equal to zero. A usable sort column ID is created by using the `set_sort_func`() method. The sort column ID can then be used for sorting a `gtk.ListStore` or `gtk.TreeStore` using the `set_sort_column_id`() method.

The `gtk.ListStore` and `gtk.TreeStore` objects automatically setup sort column IDs corresponding to the columns in the store. These sort column IDs are associated with an internal comparison function that handles the fundamental types:

- gboolean
- str
- int
- long
- float

### Note

Once a sort column ID has been set on a `gtk.TreeModel` implementing the `gtk.TreeSortable` interface it cannot be returned to the original unsorted state. You can change the sort function or use a default sort function but you cannot set the `gtk.TreeModel` to have no sort function.

## Methods

### gtk.TreeSortable.sort_column_changed

        def sort_column_changed()

The `sort_column_changed`() method emits the "sort_column_changed" signal on the treesortable object.

### gtk.TreeSortable.get_sort_column_id

        def get_sort_column_id()

Returns : | a tuple containing the sort column id and the sort type: `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`

The `get_sort_column_id`() method returns a tuple containing the current sort column ID and the sort type (either `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`), if applicable. If the sort column ID is not set, then the tuple `(-2, 0)` is returned. If the sort column ID is set to -1 indicating the default sort function is to be used this method returns (`None`, `None`)

### gtk.TreeSortable.set_sort_column_id

        def set_sort_column_id(sort_column_id, order)

`sort_column_id` : | the sort column id to set
`order` : | the sort order: `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`

The `set_sort_column_id`() method sets the current sort comparison function to that associated with the sort column ID specified by `sort_column_id` with the sort order type specified by `order`. The value of order must be either: `gtk.SORT_ASCENDING` or `gtk.SORT_DESCENDING`. The treesortable will resort itself to reflect this change, after emitting a "sort_column_changed" signal.

If `sort_column_id` is -1, then the default sort function will be used, if it is set. If a default sort function is not set then the sort column ID is not changed.

### gtk.TreeSortable.set_sort_func

        def set_sort_func(sort_column_id, sort_func, user_data=None)

`sort_column_id` : | the sort column id to set the function for
`sort_func` : | The sorting function
`user_data` : | the user data to pass to the sort func, or `None`

The `set_sort_func`() method sets the comparison function (or method) used when sorting on the sort column ID specified by `column_id` to the value specified by `sort_func`. If the current sort column id of the treesortable is the same as `sort_column_id`, the model will be resorted. The signature of the comparison function (or method) is:

        def comparefunction(treemodel, iter1, iter2, user_data)

        def comparemethod(self, treemodel, iter1, iter2, user_data)

where `treemodel` is the tree model implementing the `gtk.TreeSortable` interface, `iter1` and `iter2` point at the rows to compare and `user_data` is the user data specified in `set_sort_func`() or `None`. If `sort_func` is a method then `self` is the object associated with the method.

The comparison callback should return -1 if the `iter1` row should come before the `iter2` row, 0 if the rows are equal, or 1 if the `iter1` row should come after the `iter2` row.

### gtk.TreeSortable.set_default_sort_func

        def set_default_sort_func(sort_func, user_data=None)

`sort_func` : | the sorting function
`user_data` : | the user data to pass to `sort_func`, or `None`

The `set_default_sort_func`() method sets the default comparison function (or method) to the value of `sort_func`. If the current sort column id of the treesortable is -1 (the `get_sort_column_id`() method returns (None, None)), then the model will be resorted using the `sort_func`. See the `set_sort_func`() method for more details on the signature of the comparison function.

In Pygtk 2.10, `sort_func` can be `None` to have no default comparison function. This means that once the model has been sorted, it can't go back to the default state. In this case, when the current sort column id of sortable is -1, the model will be unsorted.

### gtk.TreeSortable.has_default_sort_func

        def has_default_sort_func()

Returns : | `True`, if the model has a default sort function

The `has_default_sort_func`() method returns `True` if the model has a default sort function. This is used primarily by `gtk.TreeViewColumn` to determine if a model can go back to the default state, or not.

## Signals

### The "sort-column-changed" gtk.TreeSortable Signal

        def callback(treesortable, user_param1, ...)

`treesortable` : | the treesortable that received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

The "sort-column-changed" signal is emitted when the `sort_column_changed`() method is called or the sort column is changed using the `set_sort_column_id`() method.

Prev | Up | Next
gtk.TreeSelection | Home | gtk.TreeStore