diff options
author | Javier Jardón <jjardon@gnome.org> | 2010-10-22 22:10:03 +0200 |
---|---|---|
committer | Javier Jardón <jjardon@gnome.org> | 2010-10-23 00:31:37 +0200 |
commit | e51daa79fe2c17499bfa76e6fb25e40d04bba2d6 (patch) | |
tree | 21e9d8ffd9604d7d2b596713a14b206f3d446984 /gtk/gtktreesortable.h | |
parent | 16cf23959f17c240b5b1faf7802cffd1f51363ab (diff) | |
download | gtk+-e51daa79fe2c17499bfa76e6fb25e40d04bba2d6.tar.gz |
gtktreesortable: Move documentation to inline comments
Diffstat (limited to 'gtk/gtktreesortable.h')
-rw-r--r-- | gtk/gtktreesortable.h | 22 |
1 files changed, 22 insertions, 0 deletions
diff --git a/gtk/gtktreesortable.h b/gtk/gtktreesortable.h index 4931276d98..c9ce6e787a 100644 --- a/gtk/gtktreesortable.h +++ b/gtk/gtktreesortable.h @@ -46,6 +46,28 @@ enum { typedef struct _GtkTreeSortable GtkTreeSortable; /* Dummy typedef */ typedef struct _GtkTreeSortableIface GtkTreeSortableIface; +/** + * GtkTreeIterCompareFunc: + * @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() + * + * 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 + * <literal>price_of(@a) - price_of(@b)</literal>. + * + * Returns: a negative integer, zero or a positive integer depending on whether + * @a sorts before, with or after @b + */ typedef gint (* GtkTreeIterCompareFunc) (GtkTreeModel *model, GtkTreeIter *a, GtkTreeIter *b, |