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