GtkTreeSortable: GTK+ 3 Reference Manual

## GtkTreeSortable GtkTreeSortable — The interface for sortable models used by GtkTreeView |

## Functions

gint | (*GtkTreeIterCompareFunc) ()
void | gtk_tree_sortable_sort_column_changed ()
gboolean | gtk_tree_sortable_get_sort_column_id ()
void | gtk_tree_sortable_set_sort_column_id ()
void | gtk_tree_sortable_set_sort_func ()
void | gtk_tree_sortable_set_default_sort_func ()
gboolean | gtk_tree_sortable_has_default_sort_func ()

## Signals

void | sort-column-changed | Run Last

## Types and Values

| GtkTreeSortable
struct | GtkTreeSortableIface
#define | GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID
#define | GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID

## Object Hierarchy

        GInterface
        ╰── GtkTreeSortable

## Prerequisites

GtkTreeSortable requires GtkTreeModel and GObject.

## Known Implementations

GtkTreeSortable is implemented by GtkListStore, GtkTreeModelSort and GtkTreeStore.

## Includes

    #include <gtk/gtk.h>

## 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.

## Functions

### 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)`.

#### Parameters

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

a negative integer, zero or a positive integer depending on whether `a` sorts before, with or after `b`

### gtk_tree_sortable_sort_column_changed ()

    void
    gtk_tree_sortable_sort_column_changed (GtkTreeSortable *sortable);

Emits a “sort-column-changed” signal on `sortable` .

#### Parameters

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`.

#### Parameters

sortable | A GtkTreeSortable |
sort_column_id | The sort column id to be filled in. | [out]
order | The GtkSortType to be filled in. | [out]

#### 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 “sort-column-changed” signal. `sort_column_id` may either be a regular column id, or one of the following special values:

- `GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID`: the default sort function will be used, if it is set

- `GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID`: no sorting will occur

#### Parameters

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,
                                     GDestroyNotify 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.

#### Parameters

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`. | [allow-none]
destroy | Destroy notifier of `user_data` , or `NULL`. | [allow-none]

### gtk_tree_sortable_set_default_sort_func ()

    void
    gtk_tree_sortable_set_default_sort_func
                                   (GtkTreeSortable *sortable,
                                    GtkTreeIterCompareFunc sort_func,
                                    gpointer user_data,
                                    GDestroyNotify 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.

#### Parameters

sortable | A GtkTreeSortable |
sort_func | The comparison function |
user_data | User data to pass to `sort_func` , or `NULL`. | [allow-none]
destroy | Destroy notifier of `user_data` , or `NULL`. | [allow-none]

### 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.

#### Parameters

sortable | A GtkTreeSortable |

#### Returns

`TRUE`, if the model has a default sort function

## Types and Values

### GtkTreeSortable

    typedef struct _GtkTreeSortable GtkTreeSortable;

### struct GtkTreeSortableIface

    struct GtkTreeSortableIface {
      /* 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  sort_func,
    				      gpointer                user_data,
    				      GDestroyNotify          destroy);
      void     (* set_default_sort_func) (GtkTreeSortable        *sortable,
    				      GtkTreeIterCompareFunc  sort_func,
    				      gpointer                user_data,
    				      GDestroyNotify          destroy);
      gboolean (* has_default_sort_func) (GtkTreeSortable        *sortable);
    };

#### Members

`sort_column_changed` () | Signal emitted when the sort column or sort order of sortable is changed. |
`get_sort_column_id` () | Fills in sort_column_id and order with the current sort column and the order. |
`set_sort_column_id` () | Sets the current sort column to be sort_column_id. |
`set_sort_func` () | Sets the comparison function used when sorting to be sort_func. |
`set_default_sort_func` () | Sets the default comparison function used when sorting to be sort_func. |
`has_default_sort_func` () | `TRUE` if the model has a default sort function. |

### GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID

    #define GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID (-1)

The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a GtkTreeSortable use the default sort function.

See also `gtk_tree_sortable_set_sort_column_id()`

### GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID

    #define GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID (-2)

The GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID can be used to make a GtkTreeSortable use no sorting.

See also `gtk_tree_sortable_set_sort_column_id()`

## Signal Details

### The `“sort-column-changed”` signal

    void
    user_function (GtkTreeSortable *sortable,
                   gpointer         user_data)

The ::sort-column-changed signal is emitted when the sort column or sort order of `sortable` is changed. The signal is emitted before the contents of `sortable` are resorted.

#### Parameters

sortable | the object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

GtkTreeModel, GtkTreeView