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 | |
36 | static void gtk_tree_sortable_base_init (gpointer g_class); |
37 | |
38 | GType |
39 | gtk_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 | |
68 | static void |
69 | gtk_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 | */ |
100 | void |
101 | gtk_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 | **/ |
122 | gboolean |
123 | gtk_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 | */ |
155 | void |
156 | gtk_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 | */ |
184 | void |
185 | gtk_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 | */ |
222 | void |
223 | gtk_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 | */ |
250 | gboolean |
251 | gtk_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 | |