2 * Copyright (C) 2001 Red Hat, Inc.
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.
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.
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/>.
20 #include "gtktreednd.h"
26 * @Short_description: Interfaces for drag-and-drop support in GtkTreeView
27 * @Title: GtkTreeView drag-and-drop
29 * GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level
32 * The low-level API consists of the GTK+ DND API, augmented by some treeview
33 * utility functions: gtk_tree_view_set_drag_dest_row(),
34 * gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(),
35 * gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and
36 * gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but
37 * nothing is done automatically, and implementing advanced features like
38 * hover-to-open-rows or autoscrolling on top of this API is a lot of work.
40 * On the other hand, if you write to the high-level API, then all the
41 * bookkeeping of rows is done for you, as well as things like hover-to-open
42 * and auto-scroll, but your models have to implement the
43 * #GtkTreeDragSource and #GtkTreeDragDest interfaces.
48 gtk_tree_drag_source_get_type (void)
50 static GType our_type = 0;
54 const GTypeInfo our_info =
56 sizeof (GtkTreeDragSourceIface), /* class_size */
58 NULL, /* base_finalize */
60 NULL, /* class_finalize */
61 NULL, /* class_data */
67 our_type = g_type_register_static (G_TYPE_INTERFACE,
68 I_("GtkTreeDragSource"),
77 gtk_tree_drag_dest_get_type (void)
79 static GType our_type = 0;
83 const GTypeInfo our_info =
85 sizeof (GtkTreeDragDestIface), /* class_size */
87 NULL, /* base_finalize */
89 NULL, /* class_finalize */
90 NULL, /* class_data */
96 our_type = g_type_register_static (G_TYPE_INTERFACE, I_("GtkTreeDragDest"), &our_info, 0);
103 * gtk_tree_drag_source_row_draggable:
104 * @drag_source: a #GtkTreeDragSource
105 * @path: row on which user is initiating a drag
107 * Asks the #GtkTreeDragSource whether a particular row can be used as
108 * the source of a DND operation. If the source doesn't implement
109 * this interface, the row is assumed draggable.
111 * Return value: %TRUE if the row can be dragged
114 gtk_tree_drag_source_row_draggable (GtkTreeDragSource *drag_source,
117 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
119 g_return_val_if_fail (path != NULL, FALSE);
121 if (iface->row_draggable)
122 return (* iface->row_draggable) (drag_source, path);
125 /* Returning TRUE if row_draggable is not implemented is a fallback.
126 Interface implementations such as GtkTreeStore and GtkListStore really should
127 implement row_draggable. */
132 * gtk_tree_drag_source_drag_data_delete:
133 * @drag_source: a #GtkTreeDragSource
134 * @path: row that was being dragged
136 * Asks the #GtkTreeDragSource to delete the row at @path, because
137 * it was moved somewhere else via drag-and-drop. Returns %FALSE
138 * if the deletion fails because @path no longer exists, or for
139 * some model-specific reason. Should robustly handle a @path no
140 * longer found in the model!
142 * Return value: %TRUE if the row was successfully deleted
145 gtk_tree_drag_source_drag_data_delete (GtkTreeDragSource *drag_source,
148 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
150 g_return_val_if_fail (iface->drag_data_delete != NULL, FALSE);
151 g_return_val_if_fail (path != NULL, FALSE);
153 return (* iface->drag_data_delete) (drag_source, path);
157 * gtk_tree_drag_source_drag_data_get:
158 * @drag_source: a #GtkTreeDragSource
159 * @path: row that was dragged
160 * @selection_data: (out): a #GtkSelectionData to fill with data
161 * from the dragged row
163 * Asks the #GtkTreeDragSource to fill in @selection_data with a
164 * representation of the row at @path. @selection_data->target gives
165 * the required type of the data. Should robustly handle a @path no
166 * longer found in the model!
168 * Return value: %TRUE if data of the required type was provided
171 gtk_tree_drag_source_drag_data_get (GtkTreeDragSource *drag_source,
173 GtkSelectionData *selection_data)
175 GtkTreeDragSourceIface *iface = GTK_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
177 g_return_val_if_fail (iface->drag_data_get != NULL, FALSE);
178 g_return_val_if_fail (path != NULL, FALSE);
179 g_return_val_if_fail (selection_data != NULL, FALSE);
181 return (* iface->drag_data_get) (drag_source, path, selection_data);
185 * gtk_tree_drag_dest_drag_data_received:
186 * @drag_dest: a #GtkTreeDragDest
187 * @dest: row to drop in front of
188 * @selection_data: data to drop
190 * Asks the #GtkTreeDragDest to insert a row before the path @dest,
191 * deriving the contents of the row from @selection_data. If @dest is
192 * outside the tree so that inserting before it is impossible, %FALSE
193 * will be returned. Also, %FALSE may be returned if the new row is
194 * not created for some model-specific reason. Should robustly handle
195 * a @dest no longer found in the model!
197 * Return value: whether a new row was created before position @dest
200 gtk_tree_drag_dest_drag_data_received (GtkTreeDragDest *drag_dest,
202 GtkSelectionData *selection_data)
204 GtkTreeDragDestIface *iface = GTK_TREE_DRAG_DEST_GET_IFACE (drag_dest);
206 g_return_val_if_fail (iface->drag_data_received != NULL, FALSE);
207 g_return_val_if_fail (dest != NULL, FALSE);
208 g_return_val_if_fail (selection_data != NULL, FALSE);
210 return (* iface->drag_data_received) (drag_dest, dest, selection_data);
215 * gtk_tree_drag_dest_row_drop_possible:
216 * @drag_dest: a #GtkTreeDragDest
217 * @dest_path: destination row
218 * @selection_data: the data being dragged
220 * Determines whether a drop is possible before the given @dest_path,
221 * at the same depth as @dest_path. i.e., can we drop the data in
222 * @selection_data at that location. @dest_path does not have to
223 * exist; the return value will almost certainly be %FALSE if the
224 * parent of @dest_path doesn't exist, though.
226 * Return value: %TRUE if a drop is possible before @dest_path
229 gtk_tree_drag_dest_row_drop_possible (GtkTreeDragDest *drag_dest,
230 GtkTreePath *dest_path,
231 GtkSelectionData *selection_data)
233 GtkTreeDragDestIface *iface = GTK_TREE_DRAG_DEST_GET_IFACE (drag_dest);
235 g_return_val_if_fail (iface->row_drop_possible != NULL, FALSE);
236 g_return_val_if_fail (selection_data != NULL, FALSE);
237 g_return_val_if_fail (dest_path != NULL, FALSE);
239 return (* iface->row_drop_possible) (drag_dest, dest_path, selection_data);
242 typedef struct _TreeRowData TreeRowData;
251 * gtk_tree_set_row_drag_data:
252 * @selection_data: some #GtkSelectionData
253 * @tree_model: a #GtkTreeModel
254 * @path: a row in @tree_model
256 * Sets selection data of target type %GTK_TREE_MODEL_ROW. Normally used
257 * in a drag_data_get handler.
259 * Return value: %TRUE if the #GtkSelectionData had the proper target type to allow us to set a tree row
262 gtk_tree_set_row_drag_data (GtkSelectionData *selection_data,
263 GtkTreeModel *tree_model,
271 g_return_val_if_fail (selection_data != NULL, FALSE);
272 g_return_val_if_fail (GTK_IS_TREE_MODEL (tree_model), FALSE);
273 g_return_val_if_fail (path != NULL, FALSE);
275 if (gtk_selection_data_get_target (selection_data) != gdk_atom_intern_static_string ("GTK_TREE_MODEL_ROW"))
278 path_str = gtk_tree_path_to_string (path);
280 len = strlen (path_str);
282 /* the old allocate-end-of-struct-to-hold-string trick */
283 struct_size = sizeof (TreeRowData) + len + 1 -
284 (sizeof (TreeRowData) - G_STRUCT_OFFSET (TreeRowData, path));
286 trd = g_malloc (struct_size);
288 strcpy (trd->path, path_str);
292 trd->model = tree_model;
294 gtk_selection_data_set (selection_data,
295 gdk_atom_intern_static_string ("GTK_TREE_MODEL_ROW"),
306 * gtk_tree_get_row_drag_data:
307 * @selection_data: a #GtkSelectionData
308 * @tree_model: (out): a #GtkTreeModel
309 * @path: (out): row in @tree_model
311 * Obtains a @tree_model and @path from selection data of target type
312 * %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler.
313 * This function can only be used if @selection_data originates from the same
314 * process that's calling this function, because a pointer to the tree model
315 * is being passed around. If you aren't in the same process, then you'll
316 * get memory corruption. In the #GtkTreeDragDest drag_data_received handler,
317 * you can assume that selection data of type %GTK_TREE_MODEL_ROW is
318 * in from the current process. The returned path must be freed with
319 * gtk_tree_path_free().
321 * Return value: %TRUE if @selection_data had target type %GTK_TREE_MODEL_ROW and
325 gtk_tree_get_row_drag_data (GtkSelectionData *selection_data,
326 GtkTreeModel **tree_model,
331 g_return_val_if_fail (selection_data != NULL, FALSE);
339 if (gtk_selection_data_get_target (selection_data) != gdk_atom_intern_static_string ("GTK_TREE_MODEL_ROW"))
342 if (gtk_selection_data_get_length (selection_data) < 0)
345 trd = (void*) gtk_selection_data_get_data (selection_data);
348 *tree_model = trd->model;
351 *path = gtk_tree_path_new_from_string (trd->path);