GtkTreeSortable

GtkTreeSortable — The interface for sortable models used by GtkTreeView

Synopsis


#include <gtk/gtk.h>

                    GtkTreeSortable;
                    GtkTreeSortableIface;
gint                (*GtkTreeIterCompareFunc)           (GtkTreeModel *model,
                                                         GtkTreeIter *a,
                                                         GtkTreeIter *b,
                                                         gpointer user_data);
void                gtk_tree_sortable_sort_column_changed
                                                        (GtkTreeSortable *sortable);
gboolean            gtk_tree_sortable_get_sort_column_id
                                                        (GtkTreeSortable *sortable,
                                                         gint *sort_column_id,
                                                         GtkSortType *order);
void                gtk_tree_sortable_set_sort_column_id
                                                        (GtkTreeSortable *sortable,
                                                         gint sort_column_id,
                                                         GtkSortType order);
void                gtk_tree_sortable_set_sort_func     (GtkTreeSortable *sortable,
                                                         gint sort_column_id,
                                                         GtkTreeIterCompareFunc sort_func,
                                                         gpointer user_data,
                                                         GtkDestroyNotify destroy);
void                gtk_tree_sortable_set_default_sort_func
                                                        (GtkTreeSortable *sortable,
                                                         GtkTreeIterCompareFunc sort_func,
                                                         gpointer user_data,
                                                         GtkDestroyNotify destroy);
gboolean            gtk_tree_sortable_has_default_sort_func
                                                        (GtkTreeSortable *sortable);

Object Hierarchy

  GInterface
   +----GtkTreeSortable

Prerequisites

GtkTreeSortable requires GtkTreeModel and GObject.

Known Implementations

GtkTreeSortable is implemented by GtkTreeModelSort, GtkTreeStore and GtkListStore.

Signals

  "sort-column-changed"                            : Run Last

Description

GtkTreeSortable is an interface to be implemented by tree models which support sorting. The GtkTreeView uses the methods provided by this interface to sort the model.

Details

GtkTreeSortable

typedef struct _GtkTreeSortable GtkTreeSortable;


GtkTreeSortableIface

typedef struct {
  GTypeInterface g_iface;

  /* signals */
  void     (* sort_column_changed)   (GtkTreeSortable        *sortable);

  /* virtual table */
  gboolean (* get_sort_column_id)    (GtkTreeSortable        *sortable,
				      gint                   *sort_column_id,
				      GtkSortType            *order);
  void     (* set_sort_column_id)    (GtkTreeSortable        *sortable,
				      gint                    sort_column_id,
				      GtkSortType             order);
  void     (* set_sort_func)         (GtkTreeSortable        *sortable,
				      gint                    sort_column_id,
				      GtkTreeIterCompareFunc  func,
				      gpointer                data,
				      GtkDestroyNotify        destroy);
  void     (* set_default_sort_func) (GtkTreeSortable        *sortable,
				      GtkTreeIterCompareFunc  func,
				      gpointer                data,
				      GtkDestroyNotify        destroy);
  gboolean (* has_default_sort_func) (GtkTreeSortable        *sortable);
} GtkTreeSortableIface;


GtkTreeIterCompareFunc ()

gint                (*GtkTreeIterCompareFunc)           (GtkTreeModel *model,
                                                         GtkTreeIter *a,
                                                         GtkTreeIter *b,
                                                         gpointer user_data);

A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if a sorts before b, a sorts with b, or a sorts after b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the GtkTreeSortable behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive.

For example, if model is a product catalogue, then a compare function for the "price" column could be one which returns price_of(a) - price_of(b).

model : The GtkTreeModel the comparison is within
a : A GtkTreeIter in model
b : Another GtkTreeIter in model
user_data : Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func()
Returns :

gtk_tree_sortable_sort_column_changed ()

void                gtk_tree_sortable_sort_column_changed
                                                        (GtkTreeSortable *sortable);

Emits a GtkTreeSortable::sort_column_changed signal on

sortable : A GtkTreeSortable

gtk_tree_sortable_get_sort_column_id ()

gboolean            gtk_tree_sortable_get_sort_column_id
                                                        (GtkTreeSortable *sortable,
                                                         gint *sort_column_id,
                                                         GtkSortType *order);

Fills in sort_column_id and order with the current sort column and the order. It returns TRUE unless the sort_column_id is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.

sortable : A GtkTreeSortable
sort_column_id : The sort column id to be filled in
order : The GtkSortType to be filled in
Returns : TRUE if the sort column is not one of the special sort column ids.

gtk_tree_sortable_set_sort_column_id ()

void                gtk_tree_sortable_set_sort_column_id
                                                        (GtkTreeSortable *sortable,
                                                         gint sort_column_id,
                                                         GtkSortType order);

Sets the current sort column to be sort_column_id. The sortable will resort itself to reflect this change, after emitting a GtkTreeSortable::sort_column_changed signal. If sort_column_id is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the default sort function will be used, if it is set.

sortable : A GtkTreeSortable
sort_column_id : the sort column id to set
order : The sort order of the column

gtk_tree_sortable_set_sort_func ()

void                gtk_tree_sortable_set_sort_func     (GtkTreeSortable *sortable,
                                                         gint sort_column_id,
                                                         GtkTreeIterCompareFunc sort_func,
                                                         gpointer user_data,
                                                         GtkDestroyNotify destroy);

Sets the comparison function used when sorting to be sort_func. If the current sort column id of sortable is the same as sort_column_id, then the model will sort using this function.

sortable : A GtkTreeSortable
sort_column_id : the sort column id to set the function for
sort_func : The comparison function
user_data : User data to pass to sort_func, or NULL
destroy : Destroy notifier of user_data, or NULL

gtk_tree_sortable_set_default_sort_func ()

void                gtk_tree_sortable_set_default_sort_func
                                                        (GtkTreeSortable *sortable,
                                                         GtkTreeIterCompareFunc sort_func,
                                                         gpointer user_data,
                                                         GtkDestroyNotify destroy);

Sets the default comparison function used when sorting to be sort_func. If the current sort column id of sortable is GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function.

If sort_func is NULL, then there will be 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 GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.

sortable : A GtkTreeSortable
sort_func : The comparison function
user_data : User data to pass to sort_func, or NULL
destroy : Destroy notifier of user_data, or NULL

gtk_tree_sortable_has_default_sort_func ()

gboolean            gtk_tree_sortable_has_default_sort_func
                                                        (GtkTreeSortable *sortable);

Returns TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not.

sortable : A GtkTreeSortable
Returns : TRUE, if the model has a default sort function

Signal Details

The "sort-column-changed" signal

void                user_function                      (GtkTreeSortable *treesortable,
                                                        gpointer         user_data)         : Run Last

treesortable : the object which received the signal.
user_data : user data set when the signal handler was connected.

See Also

GtkTreeModel, GtkTreeView