1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 1995-1999 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser 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 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
19 * Modified by the GTK+ Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GTK+ Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
27 #include "gdkdndprivate.h"
28 #include "gdkdisplay.h"
29 #include "gdkwindow.h"
34 * @title: Drag And Drop
35 * @short_description: Functions for controlling drag and drop handling
37 * These functions provide a low level interface for drag and drop.
38 * The X backend of GDK supports both the Xdnd and Motif drag and drop
39 * protocols transparently, the Win32 backend supports the WM_DROPFILES
42 * GTK+ provides a higher level abstraction based on top of these functions,
43 * and so they are not normally needed in GTK+ applications.
44 * See the <link linkend="gtk-Drag-and-Drop">Drag and Drop</link> section of
45 * the GTK+ documentation for more information.
49 * gdk_drag_context_list_targets:
50 * @context: a #GdkDragContext
52 * Retrieves the list of targets of the context.
54 * Return value: (transfer none) (element-type GdkAtom): a #GList of targets
59 gdk_drag_context_list_targets (GdkDragContext *context)
61 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), NULL);
63 return context->targets;
67 * gdk_drag_context_get_actions:
68 * @context: a #GdkDragContext
70 * Determines the bitmask of actions proposed by the source if
71 * gdk_drag_context_get_suggested_action() returns GDK_ACTION_ASK.
73 * Return value: the #GdkDragAction flags
78 gdk_drag_context_get_actions (GdkDragContext *context)
80 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), GDK_ACTION_DEFAULT);
82 return context->actions;
86 * gdk_drag_context_get_suggested_action:
87 * @context: a #GdkDragContext
89 * Determines the suggested drag action of the context.
91 * Return value: a #GdkDragAction value
96 gdk_drag_context_get_suggested_action (GdkDragContext *context)
98 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), 0);
100 return context->suggested_action;
104 * gdk_drag_context_get_selected_action:
105 * @context: a #GdkDragContext
107 * Determines the action chosen by the drag destination.
109 * Return value: a #GdkDragAction value
114 gdk_drag_context_get_selected_action (GdkDragContext *context)
116 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), 0);
118 return context->action;
122 * gdk_drag_context_get_source_window:
123 * @context: a #GdkDragContext
125 * Returns the #GdkWindow where the DND operation started.
127 * Return value: (transfer none): a #GdkWindow
132 gdk_drag_context_get_source_window (GdkDragContext *context)
134 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), NULL);
136 return context->source_window;
140 * gdk_drag_context_get_dest_window:
141 * @context: a #GdkDragContext
143 * Returns the destination windw for the DND operation.
145 * Return value: (transfer none): a #GdkWindow
150 gdk_drag_context_get_dest_window (GdkDragContext *context)
152 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), NULL);
154 return context->dest_window;
158 * gdk_drag_context_get_protocol:
159 * @context: a #GdkDragContext
161 * Returns the drag protocol thats used by this context.
163 * Returns: the drag protocol
168 gdk_drag_context_get_protocol (GdkDragContext *context)
170 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), GDK_DRAG_PROTO_NONE);
172 return context->protocol;
176 * gdk_drag_context_set_device:
177 * @context: a #GdkDragContext
178 * @device: a #GdkDevice
180 * Associates a #GdkDevice to @context, so all Drag and Drop events
181 * for @context are emitted as if they came from this device.
184 gdk_drag_context_set_device (GdkDragContext *context,
187 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
188 g_return_if_fail (GDK_IS_DEVICE (device));
191 g_object_unref (context->device);
193 context->device = device;
196 g_object_ref (context->device);
200 * gdk_drag_context_get_device:
201 * @context: a #GdkDragContext
203 * Returns the #GdkDevice associated to the drag context.
205 * Returns: (transfer none): The #GdkDevice associated to @context.
208 gdk_drag_context_get_device (GdkDragContext *context)
210 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), NULL);
212 return context->device;
215 G_DEFINE_TYPE (GdkDragContext, gdk_drag_context, G_TYPE_OBJECT)
218 gdk_drag_context_init (GdkDragContext *context)
223 gdk_drag_context_finalize (GObject *object)
225 GdkDragContext *context = GDK_DRAG_CONTEXT (object);
227 g_list_free (context->targets);
229 if (context->source_window)
230 g_object_unref (context->source_window);
232 if (context->dest_window)
233 g_object_unref (context->dest_window);
235 G_OBJECT_CLASS (gdk_drag_context_parent_class)->finalize (object);
239 gdk_drag_context_class_init (GdkDragContextClass *klass)
241 GObjectClass *object_class = G_OBJECT_CLASS (klass);
243 object_class->finalize = gdk_drag_context_finalize;
247 * gdk_drag_find_window_for_screen:
248 * @context: a #GdkDragContext
249 * @drag_window: a window which may be at the pointer position, but
250 * should be ignored, since it is put up by the drag source as an icon
251 * @screen: the screen where the destination window is sought
252 * @x_root: the x position of the pointer in root coordinates
253 * @y_root: the y position of the pointer in root coordinates
254 * @dest_window: (out): location to store the destination window in
255 * @protocol: (out): location to store the DND protocol in
257 * Finds the destination window and DND protocol to use at the
258 * given pointer position.
260 * This function is called by the drag source to obtain the
261 * @dest_window and @protocol parameters for gdk_drag_motion().
266 gdk_drag_find_window_for_screen (GdkDragContext *context,
267 GdkWindow *drag_window,
271 GdkWindow **dest_window,
272 GdkDragProtocol *protocol)
274 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
276 *dest_window = GDK_DRAG_CONTEXT_GET_CLASS (context)
277 ->find_window (context, drag_window, screen, x_root, y_root, protocol);
282 * @context: a #GdkDragContext
283 * @action: the selected action which will be taken when a drop happens,
284 * or 0 to indicate that a drop will not be accepted
285 * @time_: the timestamp for this operation
287 * Selects one of the actions offered by the drag source.
289 * This function is called by the drag destination in response to
290 * gdk_drag_motion() called by the drag source.
293 gdk_drag_status (GdkDragContext *context,
294 GdkDragAction action,
297 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
299 GDK_DRAG_CONTEXT_GET_CLASS (context)->drag_status (context, action, time_);
304 * @context: a #GdkDragContext
305 * @dest_window: the new destination window, obtained by
306 * gdk_drag_find_window()
307 * @protocol: the DND protocol in use, obtained by gdk_drag_find_window()
308 * @x_root: the x position of the pointer in root coordinates
309 * @y_root: the y position of the pointer in root coordinates
310 * @suggested_action: the suggested action
311 * @possible_actions: the possible actions
312 * @time_: the timestamp for this operation
314 * Updates the drag context when the pointer moves or the
315 * set of actions changes.
317 * This function is called by the drag source.
320 gdk_drag_motion (GdkDragContext *context,
321 GdkWindow *dest_window,
322 GdkDragProtocol protocol,
325 GdkDragAction suggested_action,
326 GdkDragAction possible_actions,
329 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), FALSE);
331 return GDK_DRAG_CONTEXT_GET_CLASS (context)
332 ->drag_motion (context,
344 * @context: a #GdkDragContext
345 * @time_: the timestamp for this operation
347 * Aborts a drag without dropping.
349 * This function is called by the drag source.
352 gdk_drag_abort (GdkDragContext *context,
355 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
357 GDK_DRAG_CONTEXT_GET_CLASS (context)->drag_abort (context, time_);
362 * @context: a #GdkDragContext
363 * @time_: the timestamp for this operation
365 * Drops on the current destination.
367 * This function is called by the drag source.
370 gdk_drag_drop (GdkDragContext *context,
373 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
375 GDK_DRAG_CONTEXT_GET_CLASS (context)->drag_drop (context, time_);
380 * @context: a #GdkDragContext
381 * @accepted: %TRUE if the drop is accepted
382 * @time_: the timestamp for this operation
384 * Accepts or rejects a drop.
386 * This function is called by the drag destination in response
387 * to a drop initiated by the drag source.
390 gdk_drop_reply (GdkDragContext *context,
394 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
396 GDK_DRAG_CONTEXT_GET_CLASS (context)->drop_reply (context, accepted, time_);
401 * @context: a #GtkDragContext
402 * @success: %TRUE if the data was successfully received
403 * @time_: the timestamp for this operation
405 * Ends the drag operation after a drop.
407 * This function is called by the drag destination.
410 gdk_drop_finish (GdkDragContext *context,
414 g_return_if_fail (GDK_IS_DRAG_CONTEXT (context));
416 GDK_DRAG_CONTEXT_GET_CLASS (context)->drop_finish (context, success, time_);
420 * gdk_drag_drop_succeeded:
421 * @context: a #GdkDragContext
423 * Returns whether the dropped data has been successfully
424 * transferred. This function is intended to be used while
425 * handling a %GDK_DROP_FINISHED event, its return value is
426 * meaningless at other times.
428 * Return value: %TRUE if the drop was successful.
433 gdk_drag_drop_succeeded (GdkDragContext *context)
435 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), FALSE);
437 return GDK_DRAG_CONTEXT_GET_CLASS (context)->drop_status (context);
441 * gdk_drag_get_selection:
442 * @context: a #GdkDragContext.
444 * Returns the selection atom for the current source window.
446 * Return value: (transfer none): the selection atom, or %GDK_NONE
449 gdk_drag_get_selection (GdkDragContext *context)
451 g_return_val_if_fail (GDK_IS_DRAG_CONTEXT (context), GDK_NONE);
452 g_return_val_if_fail (context->source_window != NULL, GDK_NONE);
454 return GDK_DRAG_CONTEXT_GET_CLASS (context)->get_selection (context);