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