GtkDropTarget

GtkDropTarget — Event controller to receive DND drops

Functions

Properties

GdkDragAction actions Read / Write
gboolean contains Read
GdkContentFormats * formats Read / Write

Signals

gboolean accept Run Last
gboolean drag-drop Run Last
void drag-enter Run Last
void drag-leave Run Last
void drag-motion Run Last

Types and Values

  GtkDropTarget

Object Hierarchy

    GObject
    ╰── GtkEventController
        ╰── GtkDropTarget

Includes

#include <gtk/gtk.h>

Description

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.

Functions

gtk_drop_target_new ()

GtkDropTarget *
gtk_drop_target_new (GdkContentFormats *formats,
                     GdkDragAction actions);

Creates a new GtkDropTarget object.

Parameters

formats

the supported data formats.

[nullable]

actions

the supported actions

 

Returns

the new GtkDropTarget


gtk_drop_target_set_formats ()

void
gtk_drop_target_set_formats (GtkDropTarget *dest,
                             GdkContentFormats *formats);

Sets the data formats that this drop target will accept.

Parameters

dest

a GtkDropTarget

 

formats

the supported data formats.

[nullable]

gtk_drop_target_get_formats ()

GdkContentFormats *
gtk_drop_target_get_formats (GtkDropTarget *dest);

Gets the data formats that this drop target accepts.

Parameters

dest

a GtkDropTarget

 

Returns

the supported data formats


gtk_drop_target_set_actions ()

void
gtk_drop_target_set_actions (GtkDropTarget *dest,
                             GdkDragAction actions);

Sets the actions that this drop target supports.

Parameters

dest

a GtkDropTarget

 

actions

the supported actions

 

gtk_drop_target_get_actions ()

GdkDragAction
gtk_drop_target_get_actions (GtkDropTarget *dest);

Gets the actions that this drop target supports.

Parameters

dest

a GtkDropTarget

 

Returns

the actions that this drop target supports


gtk_drop_target_get_drop ()

GdkDrop *
gtk_drop_target_get_drop (GtkDropTarget *dest);

Returns the underlying GtkDrop object for an ongoing drag.

Parameters

dest

a GtkDropTarget

 

Returns

the GtkDrop of the current drag operation, or NULL.

[nullable][transfer none]


gtk_drop_target_find_mimetype ()

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.

Parameters

dest

a GtkDropTarget

 

Returns

a matching mimetype for the ongoing drag, or NULL.

[nullable]


gtk_drop_target_read_selection ()

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.

Parameters

dest

a GtkDropTarget

 

target

the data format to read

 

cancellable

a cancellable.

[nullable]

callback

callback to call on completion

 

user_data

data to pass to callback

 

gtk_drop_target_read_selection_finish ()

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().

Parameters

dest

a GtkDropTarget

 

result

a GAsyncResult

 

error

location to store error information on failure, or NULL.

[allow-none]

Returns

the GtkSelectionData, or NULL.

[nullable][transfer full]

Property Details

The “actions” property

  “actions”                  GdkDragAction

The GdkDragActions that this drop target supports

Owner: GtkDropTarget

Flags: Read / Write


The “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


The “formats” property

  “formats”                  GdkContentFormats *

The GdkContentFormats that determines the supported data formats

Owner: GtkDropTarget

Flags: Read / Write

Signal Details

The “accept” signal

gboolean
user_function (GtkDropTarget *droptarget,
               GdkDrop       *arg1,
               gpointer       user_data)

Flags: Run Last


The “drag-drop” signal

gboolean
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.

Parameters

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.

 

Returns

whether the cursor position is in a drop zone

Flags: Run Last


The “drag-enter” signal

void
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.

Parameters

dest

the GtkDropTarget

 

drop

the GdkDrop

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “drag-leave” signal

void
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”.

Parameters

dest

the GtkDropTarget

 

drop

the GdkDrop

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “drag-motion” signal

void
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.

Parameters

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