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

source code of gtk/gtk/gtktreesortable.c