Top | ![]() |
![]() |
![]() |
![]() |
GtkDropTarget * | gtk_drop_target_new () |
void | gtk_drop_target_set_formats () |
GdkContentFormats * | gtk_drop_target_get_formats () |
void | gtk_drop_target_set_actions () |
GdkDragAction | gtk_drop_target_get_actions () |
GdkDrop * | gtk_drop_target_get_drop () |
const char * | gtk_drop_target_find_mimetype () |
void | gtk_drop_target_read_selection () |
GtkSelectionData * | gtk_drop_target_read_selection_finish () |
gboolean | accept | Run Last |
gboolean | drag-drop | Run Last |
void | drag-enter | Run Last |
void | drag-leave | Run Last |
void | drag-motion | Run Last |
GtkDropTarget is an auxiliary object that is used to receive Drag-and-Drop operations.
To use a GtkDropTarget to receive drops on a widget, you create
a GtkDropTarget object, configure which data formats and actions
you support, connect to its signals, and then attach
it to the widget with gtk_widget_add_controller()
.
During a drag operation, the first signal that a GtkDropTarget emits is “accept”, which is meant to determine whether the target is a possible drop site for the ongoing drag. The default handler for the ::accept signal accepts the drag if it finds a compatible data format an an action that is supported on both sides.
If it is, and the widget becomes the current target, you will receive a “drag-enter” signal, followed by “drag-motion” signals as the pointer moves, and finally either a “drag-leave” signal when the pointer move off the widget, or a “drag-drop” signal when a drop happens.
The ::drag-enter and ::drag-motion handler can call gdk_drop_status()
to update the status of the ongoing operation. The ::drag-drop handler
should initiate the data transfer and finish the operation by calling
gdk_drop_finish()
.
Between the ::drag-enter and ::drag-leave signals the widget is the
current drop target, and will receive the GTK_STATE_FLAG_DROP_ACTIVE
state, which can be used to style the widget as a drop targett.
GtkDropTarget * gtk_drop_target_new (GdkContentFormats *formats
,GdkDragAction actions
);
Creates a new GtkDropTarget object.
void gtk_drop_target_set_formats (GtkDropTarget *dest
,GdkContentFormats *formats
);
Sets the data formats that this drop target will accept.
GdkContentFormats *
gtk_drop_target_get_formats (GtkDropTarget *dest
);
Gets the data formats that this drop target accepts.
void gtk_drop_target_set_actions (GtkDropTarget *dest
,GdkDragAction actions
);
Sets the actions that this drop target supports.
GdkDragAction
gtk_drop_target_get_actions (GtkDropTarget *dest
);
Gets the actions that this drop target supports.
GdkDrop *
gtk_drop_target_get_drop (GtkDropTarget *dest
);
Returns the underlying GtkDrop object for an ongoing drag.
const char *
gtk_drop_target_find_mimetype (GtkDropTarget *dest
);
Returns a mimetype that is supported both by dest
and the ongoing
drag. For more detailed control, you can use gdk_drop_get_formats()
to obtain the content formats that are supported by the source.
void gtk_drop_target_read_selection (GtkDropTarget *dest
,GdkAtom target
,GCancellable *cancellable
,GAsyncReadyCallback callback
,gpointer user_data
);
Asynchronously reads the dropped data from an ongoing drag on a GtkDropTarget, and returns the data in a GtkSelectionData object.
This function is meant for cases where a GtkSelectionData object is needed, such as when using the GtkTreeModel DND support. In most other cases, the GdkDrop async read APIs that return in input stream or GValue are more convenient and should be preferred.
GtkSelectionData * gtk_drop_target_read_selection_finish (GtkDropTarget *dest
,GAsyncResult *result
,GError **error
);
Finishes an async drop read operation, see gtk_drop_target_read_selection()
.
“actions”
property “actions” GdkDragAction
The GdkDragActions that this drop target supports
Owner: GtkDropTarget
Flags: Read / Write
“contains”
property “contains” gboolean
Whether the drop target is currently the targed of an ongoing drag operation, and highlighted.
Owner: GtkDropTarget
Flags: Read
Default value: FALSE
“accept”
signalgboolean user_function (GtkDropTarget *droptarget, GdkDrop *arg1, gpointer user_data)
Flags: Run Last
“drag-drop”
signalgboolean user_function (GtkDropTarget *dest, GdkDrop *drop, gint x, gint y, gpointer user_data)
The ::drag-drop signal is emitted on the drop site when the user drops
the data onto the widget. The signal handler must determine whether
the cursor position is in a drop zone or not. If it is not in a drop
zone, it returns FALSE
and no further processing is necessary.
Otherwise, the handler returns TRUE
. In this case, the handler must
ensure that gdk_drop_finish()
is called to let the source know that
the drop is done. The call to gtk_drag_finish()
can be done either
directly or after receiving the data.
To receive the data, use one of the read functions provides by GtkDrop
and GtkDragDest: gdk_drop_read_async()
, gdk_drop_read_value_async()
,
gdk_drop_read_text_async()
, gtk_drop_target_read_selection()
.
You can use gtk_drop_target_get_drop()
to obtain the GtkDrop object
for the ongoing operation in your signal handler. If you call one of the
read functions in your handler, GTK will ensure that the GtkDrop object
stays alive until the read is completed. If you delay obtaining the data
(e.g. to handle GDK_ACTION_ASK
by showing a GtkPopover), you need to
hold a reference on the GtkDrop.
dest |
the GtkDropTarget |
|
drop |
the GdkDrop |
|
x |
the x coordinate of the current cursor position |
|
y |
the y coordinate of the current cursor position |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“drag-enter”
signalvoid user_function (GtkDropTarget *dest, GdkDrop *drop, gpointer user_data)
The ::drag-enter signal is emitted on the drop site when the cursor enters the widget. It can be used to set up custom highlighting.
dest |
the GtkDropTarget |
|
drop |
the GdkDrop |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“drag-leave”
signalvoid user_function (GtkDropTarget *dest, GdkDrop *drop, gpointer user_data)
The ::drag-leave signal is emitted on the drop site when the cursor leaves the widget. Its main purpose it to undo things done in “drag-enter”.
dest |
the GtkDropTarget |
|
drop |
the GdkDrop |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last
“drag-motion”
signalvoid user_function (GtkDropTarget *dest, GdkDrop *drop, gint x, gint y, gpointer user_data)
The ::drag motion signal is emitted while the pointer is moving over the drop target.
dest |
the GtkDropTarget |
|
drop |
the GdkDrop |
|
x |
the x coordinate of the current cursor position |
|
y |
the y coordinate of the current cursor position |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run Last