Pileus Git - ~andy/gtk/blob - gtk/gtktreesortable.c

   1 /* gtktreesortable.c
   2  * Copyright (C) 2000  Red Hat, Inc.,  Jonathan Blandford <jrb@redhat.com>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18
  19 #include "config.h"
  20 #include "gtktreesortable.h"
  21 #include "gtkmarshalers.h"
  22 #include "gtkintl.h"
  23
  24
  25 /**
  26  * SECTION:gtktreesortable
  27  * @Short_description: The interface for sortable models used by GtkTreeView
  28  * @Title: GtkTreeSortable
  29  * @See_also:#GtkTreeModel, #GtkTreeView
  30  *
  31  * #GtkTreeSortable is an interface to be implemented by tree models which
  32  * support sorting. The #GtkTreeView uses the methods provided by this interface
  33  * to sort the model.
  34  */
  35
  36
  37 static void gtk_tree_sortable_base_init (gpointer g_class);
  38
  39 GType
  40 gtk_tree_sortable_get_type (void)
  41 {
  42   static GType tree_sortable_type = 0;
  43
  44   if (! tree_sortable_type)
  45     {
  46       const GTypeInfo tree_sortable_info =
  47       {
  48         sizeof (GtkTreeSortableIface), /* class_size */
  49         gtk_tree_sortable_base_init,   /* base_init */
  50         NULL,           /* base_finalize */
  51         NULL,
  52         NULL,           /* class_finalize */
  53         NULL,           /* class_data */
  54         0,
  55         0,
  56         NULL
  57       };
  58
  59       tree_sortable_type =
  60         g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeSortable"),
  61                                 &tree_sortable_info, 0);
  62
  63       g_type_interface_add_prerequisite (tree_sortable_type, GTK_TYPE_TREE_MODEL);
  64     }
  65
  66   return tree_sortable_type;
  67 }
  68
  69 static void
  70 gtk_tree_sortable_base_init (gpointer g_class)
  71 {
  72   static gboolean initialized = FALSE;
  73
  74   if (! initialized)
  75     {
  76       /**
  77        * GtkTreeSortable::sort-column-changed:
  78        * @sortable: the object on which the signal is emitted
  79        *
  80        * The ::sort-column-changed signal is emitted when the sort column
  81        * or sort order of @sortable is changed. The signal is emitted before
  82        * the contents of @sortable are resorted.
  83        */
  84       g_signal_new (I_("sort-column-changed"),
  85                     GTK_TYPE_TREE_SORTABLE,
  86                     G_SIGNAL_RUN_LAST,
  87                     G_STRUCT_OFFSET (GtkTreeSortableIface, sort_column_changed),
  88                     NULL, NULL,
  89                     _gtk_marshal_VOID__VOID,
  90                     G_TYPE_NONE, 0);
  91       initialized = TRUE;
  92     }
  93 }
  94
  95 /**
  96  * gtk_tree_sortable_sort_column_changed:
  97  * @sortable: A #GtkTreeSortable
  98  *
  99  * Emits a #GtkTreeSortable::sort-column-changed signal on @sortable.
 100  */
 101 void
 102 gtk_tree_sortable_sort_column_changed (GtkTreeSortable *sortable)
 103 {
 104   g_return_if_fail (GTK_IS_TREE_SORTABLE (sortable));
 105
 106   g_signal_emit_by_name (sortable, "sort-column-changed");
 107 }
 108
 109 /**
 110  * gtk_tree_sortable_get_sort_column_id:
 111  * @sortable: A #GtkTreeSortable
 112  * @sort_column_id: (out): The sort column id to be filled in
 113  * @order: (out): The #GtkSortType to be filled in
 114  *
 115  * Fills in @sort_column_id and @order with the current sort column and the
 116  * order. It returns %TRUE unless the @sort_column_id is
 117  * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or
 118  * %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID.
 119  *
 120  * Return value: %TRUE if the sort column is not one of the special sort
 121  *   column ids.
 122  **/
 123 gboolean
 124 gtk_tree_sortable_get_sort_column_id (GtkTreeSortable  *sortable,
 125                                       gint             *sort_column_id,
 126                                       GtkSortType      *order)
 127 {
 128   GtkTreeSortableIface *iface;
 129
 130   g_return_val_if_fail (GTK_IS_TREE_SORTABLE (sortable), FALSE);
 131
 132   iface = GTK_TREE_SORTABLE_GET_IFACE (sortable);
 133
 134   g_return_val_if_fail (iface != NULL, FALSE);
 135   g_return_val_if_fail (iface->get_sort_column_id != NULL, FALSE);
 136
 137   return (* iface->get_sort_column_id) (sortable, sort_column_id, order);
 138 }
 139
 140 /**
 141  * gtk_tree_sortable_set_sort_column_id:
 142  * @sortable: A #GtkTreeSortable
 143  * @sort_column_id: the sort column id to set
 144  * @order: The sort order of the column
 145  *
 146  * Sets the current sort column to be @sort_column_id. The @sortable will
 147  * resort itself to reflect this change, after emitting a
 148  * #GtkTreeSortable::sort-column-changed signal. @sort_column_id may either be
 149  * a regular column id, or one of the following special values:
 150  * <variablelist>
 151  * <varlistentry>
 152  *   <term>%GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID</term>
 153  *   <listitem>the default sort function will be used, if it is set</listitem>
 154  * </varlistentry>
 155  * <varlistentry>
 156  *   <term>%GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID</term>
 157  *   <listitem>no sorting will occur</listitem>
 158  * </varlistentry>
 159  * </variablelist>
 160  */
 161 void
 162 gtk_tree_sortable_set_sort_column_id (GtkTreeSortable  *sortable,
 163                                       gint              sort_column_id,
 164                                       GtkSortType       order)
 165 {
 166   GtkTreeSortableIface *iface;
 167
 168   g_return_if_fail (GTK_IS_TREE_SORTABLE (sortable));
 169
 170   iface = GTK_TREE_SORTABLE_GET_IFACE (sortable);
 171
 172   g_return_if_fail (iface != NULL);
 173   g_return_if_fail (iface->set_sort_column_id != NULL);
 174
 175   (* iface->set_sort_column_id) (sortable, sort_column_id, order);
 176 }
 177
 178 /**
 179  * gtk_tree_sortable_set_sort_func:
 180  * @sortable: A #GtkTreeSortable
 181  * @sort_column_id: the sort column id to set the function for
 182  * @sort_func: The comparison function
 183  * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
 184  * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
 185  *
 186  * Sets the comparison function used when sorting to be @sort_func. If the
 187  * current sort column id of @sortable is the same as @sort_column_id, then
 188  * the model will sort using this function.
 189  */
 190 void
 191 gtk_tree_sortable_set_sort_func (GtkTreeSortable        *sortable,
 192                                  gint                    sort_column_id,
 193                                  GtkTreeIterCompareFunc  sort_func,
 194                                  gpointer                user_data,
 195                                  GDestroyNotify          destroy)
 196 {
 197   GtkTreeSortableIface *iface;
 198
 199   g_return_if_fail (GTK_IS_TREE_SORTABLE (sortable));
 200   g_return_if_fail (sort_func != NULL);
 201
 202   iface = GTK_TREE_SORTABLE_GET_IFACE (sortable);
 203
 204   g_return_if_fail (iface != NULL);
 205   g_return_if_fail (iface->set_sort_func != NULL);
 206   g_return_if_fail (sort_column_id >= 0);
 207
 208   (* iface->set_sort_func) (sortable, sort_column_id, sort_func, user_data, destroy);
 209 }
 210
 211 /**
 212  * gtk_tree_sortable_set_default_sort_func:
 213  * @sortable: A #GtkTreeSortable
 214  * @sort_func: The comparison function
 215  * @user_data: (allow-none): User data to pass to @sort_func, or %NULL
 216  * @destroy: (allow-none): Destroy notifier of @user_data, or %NULL
 217  *
 218  * Sets the default comparison function used when sorting to be @sort_func.
 219  * If the current sort column id of @sortable is
 220  * %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using
 221  * this function.
 222  *
 223  * If @sort_func is %NULL, then there will be no default comparison function.
 224  * This means that once the model  has been sorted, it can't go back to the
 225  * default state. In this case, when the current sort column id of @sortable
 226  * is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted.
 227  */
 228 void
 229 gtk_tree_sortable_set_default_sort_func (GtkTreeSortable        *sortable,
 230                                          GtkTreeIterCompareFunc  sort_func,
 231                                          gpointer                user_data,
 232                                          GDestroyNotify          destroy)
 233 {
 234   GtkTreeSortableIface *iface;
 235
 236   g_return_if_fail (GTK_IS_TREE_SORTABLE (sortable));
 237
 238   iface = GTK_TREE_SORTABLE_GET_IFACE (sortable);
 239
 240   g_return_if_fail (iface != NULL);
 241   g_return_if_fail (iface->set_default_sort_func != NULL);
 242
 243   (* iface->set_default_sort_func) (sortable, sort_func, user_data, destroy);
 244 }
 245
 246 /**
 247  * gtk_tree_sortable_has_default_sort_func:
 248  * @sortable: A #GtkTreeSortable
 249  *
 250  * Returns %TRUE if the model has a default sort function. This is used
 251  * primarily by GtkTreeViewColumns in order to determine if a model can
 252  * go back to the default state, or not.
 253  *
 254  * Return value: %TRUE, if the model has a default sort function
 255  */
 256 gboolean
 257 gtk_tree_sortable_has_default_sort_func (GtkTreeSortable *sortable)
 258 {
 259   GtkTreeSortableIface *iface;
 260
 261   g_return_val_if_fail (GTK_IS_TREE_SORTABLE (sortable), FALSE);
 262
 263   iface = GTK_TREE_SORTABLE_GET_IFACE (sortable);
 264
 265   g_return_val_if_fail (iface != NULL, FALSE);
 266   g_return_val_if_fail (iface->has_default_sort_func != NULL, FALSE);
 267
 268   return (* iface->has_default_sort_func) (sortable);
 269 }