Drag and Drop
Drag and Drop — Functions for controlling drag and drop handling
Functions
Types and Values
enum | GtkDestDefaults |
enum | GtkTargetFlags |
enum | GtkDragResult |
Includes
#include <gtk/gtk.h>
Description
GTK+ has a rich set of functions for doing inter-process communication via the drag-and-drop metaphor.
As well as the functions listed here, applications may need to use some facilities provided for Selections. Also, the Drag and Drop API makes use of signals in the GtkWidget class.
Functions
gtk_drag_dest_set ()
void gtk_drag_dest_set (GtkWidget *widget
,GtkDestDefaults flags
,const GtkTargetEntry *targets
,gint n_targets
,GdkDragAction actions
);
[method]
Parameters
widget | ||
flags | which types of default drag behavior to use | |
targets | a pointer to an array of GtkTargetEntrys indicating the drop types that this | [allow-none][array length=n_targets] |
n_targets | the number of entries in | |
actions | a bitmask of possible actions for a drop onto this |
gtk_drag_dest_set_proxy ()
void gtk_drag_dest_set_proxy (GtkWidget *widget
,GdkWindow *proxy_window
,GdkDragProtocol protocol
,gboolean use_coordinates
);
[method]
Parameters
widget | ||
proxy_window | the window to which to forward drag events | |
protocol | the drag protocol which the | |
use_coordinates | If |
gtk_drag_dest_find_target ()
GdkAtom gtk_drag_dest_find_target (GtkWidget *widget
,GdkDragContext *context
,GtkTargetList *target_list
);
[method]
Parameters
widget | drag destination widget | |
context | drag context | |
target_list | list of droppable targets, or | [allow-none] |
Returns
.
[transfer none]
gtk_drag_dest_get_target_list ()
GtkTargetList *
gtk_drag_dest_get_target_list (GtkWidget *widget
);
[method]
Parameters
widget |
gtk_drag_dest_set_target_list ()
void gtk_drag_dest_set_target_list (GtkWidget *widget
,GtkTargetList *target_list
);
[method]
gtk_drag_dest_add_text_targets ()
void
gtk_drag_dest_add_text_targets (GtkWidget *widget
);
[method]
Parameters
widget | a GtkWidget that’s a drag destination |
Since: 2.6
gtk_drag_dest_add_image_targets ()
void
gtk_drag_dest_add_image_targets (GtkWidget *widget
);
[method]
Parameters
widget | a GtkWidget that’s a drag destination |
Since: 2.6
gtk_drag_dest_add_uri_targets ()
void
gtk_drag_dest_add_uri_targets (GtkWidget *widget
);
[method]
Parameters
widget | a GtkWidget that’s a drag destination |
Since: 2.6
gtk_drag_dest_set_track_motion ()
void gtk_drag_dest_set_track_motion (GtkWidget *widget
,gboolean track_motion
);
[method]
Parameters
widget | a GtkWidget that’s a drag destination | |
track_motion | whether to accept all targets |
Since: 2.10
gtk_drag_dest_get_track_motion ()
gboolean
gtk_drag_dest_get_track_motion (GtkWidget *widget
);
[method]
Parameters
widget | a GtkWidget that’s a drag destination |
Since: 2.10
gtk_drag_finish ()
void gtk_drag_finish (GdkDragContext *context
,gboolean success
,gboolean del
,guint32 time_
);
[method]
Parameters
context | the drag context. | |
success | a flag indicating whether the drop was successful | |
del | a flag indicating whether the source should delete the original data. (This should be | |
time_ | the timestamp from the “drag-drop” signal. |
gtk_drag_get_data ()
void gtk_drag_get_data (GtkWidget *widget
,GdkDragContext *context
,GdkAtom target
,guint32 time_
);
[method]
Parameters
widget | the widget that will receive the “drag-data-received” signal. | |
context | the drag context | |
target | the target (form of the data) to retrieve. | |
time_ | a timestamp for retrieving the data. This will generally be the time received in a “drag-motion”" or “drag-drop”" signal. |
gtk_drag_get_source_widget ()
GtkWidget *
gtk_drag_get_source_widget (GdkDragContext *context
);
[method]
Parameters
context | a (destination side) drag context |
Returns
.
[transfer none]
gtk_drag_highlight ()
void
gtk_drag_highlight (GtkWidget *widget
);
[method]
Parameters
widget | a widget to highlight |
gtk_drag_unhighlight ()
void
gtk_drag_unhighlight (GtkWidget *widget
);
[method]
Parameters
widget | a widget to remove the highlight from. |
gtk_drag_begin ()
GdkDragContext * gtk_drag_begin (GtkWidget *widget
,GtkTargetList *targets
,GdkDragAction actions
,gint button
,GdkEvent *event
);
gtk_drag_begin
has been deprecated since version 3.10 and should not be used in newly-written code.
Use gtk_drag_begin_with_coordinates()
instead
[method]
Parameters
widget | the source widget. | |
targets | The targets (data formats) in which the source can provide the data. | |
actions | A bitmask of the allowed drag actions for this drag. | |
button | The button the user clicked to start the drag. | |
event | The event that triggered the start of the drag. |
Returns
.
[transfer none]
gtk_drag_begin_with_coordinates ()
GdkDragContext * gtk_drag_begin_with_coordinates (GtkWidget *widget
,GtkTargetList *targets
,GdkDragAction actions
,gint button
,GdkEvent *event
,gint x
,gint y
);
[method]
Returns
.
[transfer none]
Since: 3.10
gtk_drag_cancel ()
void
gtk_drag_cancel (GdkDragContext *context
);
[method]
Parameters
context | a GdkDragContext, as e.g. returned by |
Since: 3.16
gtk_drag_set_icon_widget ()
void gtk_drag_set_icon_widget (GdkDragContext *context
,GtkWidget *widget
,gint hot_x
,gint hot_y
);
Changes the icon for a widget to a given widget. GTK+ will not destroy the icon, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) | |
widget | a toplevel window to use as an icon. | |
hot_x | the X offset within | |
hot_y | the Y offset within |
gtk_drag_set_icon_pixbuf ()
void gtk_drag_set_icon_pixbuf (GdkDragContext *context
,GdkPixbuf *pixbuf
,gint hot_x
,gint hot_y
);
Sets pixbuf
as the icon for a given drag.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) | |
pixbuf | the GdkPixbuf to use as the drag icon. | |
hot_x | the X offset within | |
hot_y | the Y offset within |
gtk_drag_set_icon_stock ()
void gtk_drag_set_icon_stock (GdkDragContext *context
,const gchar *stock_id
,gint hot_x
,gint hot_y
);
gtk_drag_set_icon_stock
has been deprecated since version 3.10 and should not be used in newly-written code.
Use gtk_drag_set_icon_name()
instead.
Sets the icon for a given drag from a stock ID.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) | |
stock_id | the ID of the stock icon to use for the drag. | |
hot_x | the X offset within the icon of the hotspot. | |
hot_y | the Y offset within the icon of the hotspot. |
gtk_drag_set_icon_surface ()
void gtk_drag_set_icon_surface (GdkDragContext *context
,cairo_surface_t *surface
);
Sets surface
as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed.
To position the surface relative to the mouse, use cairo_surface_set_device_offset()
on surface
. The mouse cursor will be positioned at the (0,0) coordinate of the surface.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) | |
surface | the surface to use as icon |
gtk_drag_set_icon_name ()
void gtk_drag_set_icon_name (GdkDragContext *context
,const gchar *icon_name
,gint hot_x
,gint hot_y
);
Sets the icon for a given drag from a named themed icon. See the docs for GtkIconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size GTK_ICON_SIZE_DND), thus hot_x
and hot_y
have to be used with care.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) | |
icon_name | name of icon to use | |
hot_x | the X offset of the hotspot within the icon | |
hot_y | the Y offset of the hotspot within the icon |
Since: 2.8
gtk_drag_set_icon_gicon ()
void gtk_drag_set_icon_gicon (GdkDragContext *context
,GIcon *icon
,gint hot_x
,gint hot_y
);
Sets the icon for a given drag from the given icon
. See the documentation for gtk_drag_set_icon_name()
for more details about using icons in drag and drop.
[method]
Parameters
context | the context for a drag (This must be called with a context for the source side of a drag) | |
icon | a GIcon | |
hot_x | the X offset of the hotspot within the icon | |
hot_y | the Y offset of the hotspot within the icon |
Since: 3.2
gtk_drag_set_icon_default ()
void
gtk_drag_set_icon_default (GdkDragContext *context
);
Sets the icon for a particular drag to the default icon.
[method]
Parameters
context | the context for a drag. (This must be called with a context for the source side of a drag) |
gtk_drag_check_threshold ()
gboolean gtk_drag_check_threshold (GtkWidget *widget
,gint start_x
,gint start_y
,gint current_x
,gint current_y
);
[method]
Parameters
widget | ||
start_x | X coordinate of start of drag | |
start_y | Y coordinate of start of drag | |
current_x | current X coordinate | |
current_y | current Y coordinate |
gtk_drag_source_set ()
void gtk_drag_source_set (GtkWidget *widget
,GdkModifierType start_button_mask
,const GtkTargetEntry *targets
,gint n_targets
,GdkDragAction actions
);
Sets up a widget so that GTK+ will start a drag operation when the user clicks and drags on the widget. The widget must have a window.
[method]
Parameters
gtk_drag_source_set_icon_pixbuf ()
void gtk_drag_source_set_icon_pixbuf (GtkWidget *widget
,GdkPixbuf *pixbuf
);
Sets the icon that will be used for drags from a particular widget from a GdkPixbuf. GTK+ retains a reference for pixbuf
and will release it when it is no longer needed.
[method]
gtk_drag_source_set_icon_stock ()
void gtk_drag_source_set_icon_stock (GtkWidget *widget
,const gchar *stock_id
);
gtk_drag_source_set_icon_stock
has been deprecated since version 3.10 and should not be used in newly-written code.
Use gtk_drag_source_set_icon_name()
instead.
Sets the icon that will be used for drags from a particular source to a stock icon.
[method]
Parameters
widget | ||
stock_id | the ID of the stock icon to use |
gtk_drag_source_set_icon_name ()
void gtk_drag_source_set_icon_name (GtkWidget *widget
,const gchar *icon_name
);
Sets the icon that will be used for drags from a particular source to a themed icon. See the docs for GtkIconTheme for more details.
[method]
Parameters
widget | ||
icon_name | name of icon to use |
Since: 2.8
gtk_drag_source_set_icon_gicon ()
void gtk_drag_source_set_icon_gicon (GtkWidget *widget
,GIcon *icon
);
Sets the icon that will be used for drags from a particular source to icon
. See the docs for GtkIconTheme for more details.
[method]
Since: 3.2
gtk_drag_source_unset ()
void
gtk_drag_source_unset (GtkWidget *widget
);
Undoes the effects of gtk_drag_source_set()
.
[method]
Parameters
widget |
gtk_drag_source_set_target_list ()
void gtk_drag_source_set_target_list (GtkWidget *widget
,GtkTargetList *target_list
);
Changes the target types that this widget offers for drag-and-drop. The widget must first be made into a drag source with gtk_drag_source_set()
.
[method]
Parameters
Since: 2.4
gtk_drag_source_get_target_list ()
GtkTargetList *
gtk_drag_source_get_target_list (GtkWidget *widget
);
Gets the list of targets this widget can provide for drag-and-drop.
[method]
Parameters
widget |
Since: 2.4
gtk_drag_source_add_text_targets ()
void
gtk_drag_source_add_text_targets (GtkWidget *widget
);
Add the text targets supported by GtkSelectionData to the target list of the drag source. The targets are added with info
= 0. If you need another value, use gtk_target_list_add_text_targets()
and gtk_drag_source_set_target_list()
.
[method]
Parameters
widget | a GtkWidget that’s is a drag source |
Since: 2.6
gtk_drag_source_add_image_targets ()
void
gtk_drag_source_add_image_targets (GtkWidget *widget
);
Add the writable image targets supported by GtkSelectionData to the target list of the drag source. The targets are added with info
= 0. If you need another value, use gtk_target_list_add_image_targets()
and gtk_drag_source_set_target_list()
.
[method]
Parameters
widget | a GtkWidget that’s is a drag source |
Since: 2.6
gtk_drag_source_add_uri_targets ()
void
gtk_drag_source_add_uri_targets (GtkWidget *widget
);
Add the URI targets supported by GtkSelectionData to the target list of the drag source. The targets are added with info
= 0. If you need another value, use gtk_target_list_add_uri_targets()
and gtk_drag_source_set_target_list()
.
[method]
Parameters
widget | a GtkWidget that’s is a drag source |
Since: 2.6
Types and Values
enum GtkDestDefaults
The GtkDestDefaults enumeration specifies the various types of action that will be taken on behalf of the user for a drag destination site.
Members
GTK_DEST_DEFAULT_MOTION | If set for a widget, GTK+, during a drag over this widget will check if the drag matches this widget’s list of possible targets and actions. GTK+ will then call | |
GTK_DEST_DEFAULT_HIGHLIGHT | If set for a widget, GTK+ will draw a highlight on this widget as long as a drag is over this widget and the widget drag format and action are acceptable. | |
GTK_DEST_DEFAULT_DROP | If set for a widget, when a drop occurs, GTK+ will will check if the drag matches this widget’s list of possible targets and actions. If so, GTK+ will call | |
GTK_DEST_DEFAULT_ALL | If set, specifies that all default actions should be taken. |
enum GtkTargetFlags
The GtkTargetFlags enumeration is used to specify constraints on a GtkTargetEntry.
Members
GTK_TARGET_SAME_APP | If this is set, the target will only be selected for drags within a single application. | |
GTK_TARGET_SAME_WIDGET | If this is set, the target will only be selected for drags within a single widget. | |
GTK_TARGET_OTHER_APP | If this is set, the target will not be selected for drags within a single application. | |
GTK_TARGET_OTHER_WIDGET | If this is set, the target will not be selected for drags withing a single widget. |
enum GtkDragResult
Gives an indication why a drag operation failed. The value can by obtained by connecting to the “drag-failed” signal.
Members
GTK_DRAG_RESULT_SUCCESS | The drag operation was successful. | |
GTK_DRAG_RESULT_NO_TARGET | No suitable drag target. | |
GTK_DRAG_RESULT_USER_CANCELLED | The user cancelled the drag operation. | |
GTK_DRAG_RESULT_TIMEOUT_EXPIRED | The drag operation timed out. | |
GTK_DRAG_RESULT_GRAB_BROKEN | The pointer or keyboard grab used for the drag operation was broken. | |
GTK_DRAG_RESULT_ERROR | The drag operation failed due to some unspecified error. |
© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk3/3.20/gtk3-Drag-and-Drop.html