1/* gtktreednd.c
2 * Copyright (C) 2001 Red Hat, Inc.
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#include "config.h"
19#include <string.h>
20#include "gtktreednd.h"
21#include "gtkintl.h"
22
23#include "gtkprivate.h"
24
25/**
26 * SECTION:gtktreednd
27 * @Short_description: Interfaces for drag-and-drop support in GtkTreeView
28 * @Title: GtkTreeView drag-and-drop
29 *
30 * GTK supports Drag-and-Drop in tree views with a high-level and a low-level
31 * API.
32 *
33 * The low-level API consists of the GTK DND API, augmented by some treeview
34 * utility functions: gtk_tree_view_set_drag_dest_row(),
35 * gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(),
36 * gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and
37 * gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but
38 * nothing is done automatically, and implementing advanced features like
39 * hover-to-open-rows or autoscrolling on top of this API is a lot of work.
40 *
41 * On the other hand, if you write to the high-level API, then all the
42 * bookkeeping of rows is done for you, as well as things like hover-to-open
43 * and auto-scroll, but your models have to implement the
44 * `GtkTreeDragSource` and `GtkTreeDragDest` interfaces.
45 */
46
47/**
48 * GtkTreeDragDest:
49 *
50 * Interface for Drag-and-Drop destinations in `GtkTreeView`.
51 */
52
53/**
54 * GtkTreeDragSource:
55 *
56 * Interface for Drag-and-Drop destinations in `GtkTreeView`.
57 */
58
59GType
60gtk_tree_drag_source_get_type (void)
61{
62 static GType our_type = 0;
63
64 if (!our_type)
65 {
66 const GTypeInfo our_info =
67 {
68 sizeof (GtkTreeDragSourceIface), /* class_size */
69 NULL, /* base_init */
70 NULL, /* base_finalize */
71 NULL,
72 NULL, /* class_finalize */
73 NULL, /* class_data */
74 0,
75 0, /* n_preallocs */
76 NULL
77 };
78
79 our_type = g_type_register_static (G_TYPE_INTERFACE,
80 I_("GtkTreeDragSource"),
81 info: &our_info, flags: 0);
82 }
83
84 return our_type;
85}
86
87
88GType
89gtk_tree_drag_dest_get_type (void)
90{
91 static GType our_type = 0;
92
93 if (!our_type)
94 {
95 const GTypeInfo our_info =
96 {
97 sizeof (GtkTreeDragDestIface), /* class_size */
98 NULL, /* base_init */
99 NULL, /* base_finalize */
100 NULL,
101 NULL, /* class_finalize */
102 NULL, /* class_data */
103 0,
104 0, /* n_preallocs */
105 NULL
106 };
107
108 our_type = g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeDragDest"), info: &our_info, flags: 0);
109 }
110
111 return our_type;
112}
113
114/**
115 * gtk_tree_drag_source_row_draggable:
116 * @drag_source: a `GtkTreeDragSource`
117 * @path: row on which user is initiating a drag
118 *
119 * Asks the `GtkTreeDragSource` whether a particular row can be used as
120 * the source of a DND operation. If the source doesn’t implement
121 * this interface, the row is assumed draggable.
122 *
123 * Returns: %TRUE if the row can be dragged
124 **/
125gboolean
126gtk_tree_drag_source_row_draggable (GtkTreeDragSource *drag_source,
127 GtkTreePath *path)
128{
129 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
130
131 g_return_val_if_fail (path != NULL, FALSE);
132
133 if (iface->row_draggable)
134 return (* iface->row_draggable) (drag_source, path);
135 else
136 return TRUE;
137 /* Returning TRUE if row_draggable is not implemented is a fallback.
138 Interface implementations such as GtkTreeStore and GtkListStore really should
139 implement row_draggable. */
140}
141
142
143/**
144 * gtk_tree_drag_source_drag_data_delete:
145 * @drag_source: a `GtkTreeDragSource`
146 * @path: row that was being dragged
147 *
148 * Asks the `GtkTreeDragSource` to delete the row at @path, because
149 * it was moved somewhere else via drag-and-drop. Returns %FALSE
150 * if the deletion fails because @path no longer exists, or for
151 * some model-specific reason. Should robustly handle a @path no
152 * longer found in the model!
153 *
154 * Returns: %TRUE if the row was successfully deleted
155 **/
156gboolean
157gtk_tree_drag_source_drag_data_delete (GtkTreeDragSource *drag_source,
158 GtkTreePath *path)
159{
160 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
161
162 g_return_val_if_fail (iface->drag_data_delete != NULL, FALSE);
163 g_return_val_if_fail (path != NULL, FALSE);
164
165 return (* iface->drag_data_delete) (drag_source, path);
166}
167
168/**
169 * gtk_tree_drag_source_drag_data_get:
170 * @drag_source: a `GtkTreeDragSource`
171 * @path: row that was dragged
172 *
173 * Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing
174 * the row at @path. Should robustly handle a @path no
175 * longer found in the model!
176 *
177 * Returns: (nullable) (transfer full): a `GdkContentProvider` for the
178 * given @path
179 **/
180GdkContentProvider *
181gtk_tree_drag_source_drag_data_get (GtkTreeDragSource *drag_source,
182 GtkTreePath *path)
183{
184 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
185
186 g_return_val_if_fail (iface->drag_data_get != NULL, FALSE);
187 g_return_val_if_fail (path != NULL, FALSE);
188
189 return (* iface->drag_data_get) (drag_source, path);
190}
191
192/**
193 * gtk_tree_drag_dest_drag_data_received:
194 * @drag_dest: a `GtkTreeDragDest`
195 * @dest: row to drop in front of
196 * @value: data to drop
197 *
198 * Asks the `GtkTreeDragDest` to insert a row before the path @dest,
199 * deriving the contents of the row from @value. If @dest is
200 * outside the tree so that inserting before it is impossible, %FALSE
201 * will be returned. Also, %FALSE may be returned if the new row is
202 * not created for some model-specific reason. Should robustly handle
203 * a @dest no longer found in the model!
204 *
205 * Returns: whether a new row was created before position @dest
206 **/
207gboolean
208gtk_tree_drag_dest_drag_data_received (GtkTreeDragDest *drag_dest,
209 GtkTreePath *dest,
210 const GValue *value)
211{
212 GtkTreeDragDestIface *iface = GTK_TREE_DRAG_DEST_GET_IFACE (drag_dest);
213
214 g_return_val_if_fail (iface->drag_data_received != NULL, FALSE);
215 g_return_val_if_fail (dest != NULL, FALSE);
216 g_return_val_if_fail (value != NULL, FALSE);
217
218 return (* iface->drag_data_received) (drag_dest, dest, value);
219}
220
221
222/**
223 * gtk_tree_drag_dest_row_drop_possible:
224 * @drag_dest: a `GtkTreeDragDest`
225 * @dest_path: destination row
226 * @value: the data being dropped
227 *
228 * Determines whether a drop is possible before the given @dest_path,
229 * at the same depth as @dest_path. i.e., can we drop the data in
230 * @value at that location. @dest_path does not have to
231 * exist; the return value will almost certainly be %FALSE if the
232 * parent of @dest_path doesn’t exist, though.
233 *
234 * Returns: %TRUE if a drop is possible before @dest_path
235 **/
236gboolean
237gtk_tree_drag_dest_row_drop_possible (GtkTreeDragDest *drag_dest,
238 GtkTreePath *dest_path,
239 const GValue *value)
240{
241 GtkTreeDragDestIface *iface = GTK_TREE_DRAG_DEST_GET_IFACE (drag_dest);
242
243 g_return_val_if_fail (iface->row_drop_possible != NULL, FALSE);
244 g_return_val_if_fail (dest_path != NULL, FALSE);
245 g_return_val_if_fail (value != NULL, FALSE);
246
247 return (* iface->row_drop_possible) (drag_dest, dest_path, value);
248}
249
250typedef struct _GtkTreeRowData GtkTreeRowData;
251
252struct _GtkTreeRowData
253{
254 GtkTreeModel *model;
255 char path[4];
256};
257
258static GtkTreeRowData *
259gtk_tree_row_data_copy (GtkTreeRowData *src)
260{
261 return g_memdup2 (mem: src, byte_size: sizeof (GtkTreeRowData) + strlen (s: src->path) + 1 -
262 (sizeof (GtkTreeRowData) - G_STRUCT_OFFSET (GtkTreeRowData, path)));
263}
264
265G_DEFINE_BOXED_TYPE (GtkTreeRowData, gtk_tree_row_data,
266 gtk_tree_row_data_copy,
267 g_free)
268
269/**
270 * gtk_tree_create_row_drag_content:
271 * @tree_model: a `GtkTreeModel`
272 * @path: a row in @tree_model
273 *
274 * Creates a content provider for dragging @path from @tree_model.
275 *
276 * Returns: (transfer full): a new `GdkContentProvider`
277 */
278GdkContentProvider *
279gtk_tree_create_row_drag_content (GtkTreeModel *tree_model,
280 GtkTreePath *path)
281{
282 GdkContentProvider *content;
283 GtkTreeRowData *trd;
284 char *path_str;
285 int len;
286 int struct_size;
287
288 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
289 g_return_val_if_fail (path != NULL, FALSE);
290
291 path_str = gtk_tree_path_to_string (path);
292
293 len = strlen (s: path_str);
294
295 /* the old allocate-end-of-struct-to-hold-string trick */
296 struct_size = sizeof (GtkTreeRowData) + len + 1 -
297 (sizeof (GtkTreeRowData) - G_STRUCT_OFFSET (GtkTreeRowData, path));
298
299 trd = g_malloc (n_bytes: struct_size);
300
301 strcpy (dest: trd->path, src: path_str);
302
303 g_free (mem: path_str);
304
305 trd->model = tree_model;
306
307 content = gdk_content_provider_new_typed (GTK_TYPE_TREE_ROW_DATA, trd);
308
309 g_free (mem: trd);
310
311 return content;
312}
313
314/**
315 * gtk_tree_get_row_drag_data:
316 * @value: a `GValue`
317 * @tree_model: (nullable) (optional) (transfer none) (out): a `GtkTreeModel`
318 * @path: (nullable) (optional) (out): row in @tree_model
319 *
320 * Obtains a @tree_model and @path from value of target type
321 * %GTK_TYPE_TREE_ROW_DATA.
322 *
323 * The returned path must be freed with gtk_tree_path_free().
324 *
325 * Returns: %TRUE if @selection_data had target type %GTK_TYPE_TREE_ROW_DATA
326 * is otherwise valid
327 **/
328gboolean
329gtk_tree_get_row_drag_data (const GValue *value,
330 GtkTreeModel **tree_model,
331 GtkTreePath **path)
332{
333 GtkTreeRowData *trd;
334
335 g_return_val_if_fail (value != NULL, FALSE);
336
337 if (tree_model)
338 *tree_model = NULL;
339
340 if (path)
341 *path = NULL;
342
343 if (!G_VALUE_HOLDS (value, GTK_TYPE_TREE_ROW_DATA))
344 return FALSE;
345
346 trd = g_value_get_boxed (value);
347 if (trd == NULL)
348 return FALSE;
349
350 if (tree_model)
351 *tree_model = trd->model;
352
353 if (path)
354 *path = gtk_tree_path_new_from_string (path: trd->path);
355
356 return TRUE;
357}
358

source code of gtk/gtk/gtktreednd.c