## GtkDragSource GtkDragSource — Event controller to initiate DND operations |

## Functions

GtkDragSource * | gtk_drag_source_new ()
void | gtk_drag_source_set_content ()
GdkContentProvider * | gtk_drag_source_get_content ()
void | gtk_drag_source_set_actions ()
GdkDragAction | gtk_drag_source_get_actions ()
void | gtk_drag_source_set_icon ()
void | gtk_drag_source_drag_cancel ()
GdkDrag * | gtk_drag_source_get_drag ()
gboolean | gtk_drag_check_threshold ()

## Properties

GdkDragAction | actions | Read / Write
GdkContentProvider * | content | Read / Write

## Signals

void | drag-begin | Run Last
gboolean | drag-cancel | Run Last
void | drag-end | Run Last
GdkContentProvider* | prepare | Run Last

## Types and Values

| GtkDragSource

## Object Hierarchy

        GObject
        ╰── GtkEventController
            ╰── GtkGesture
                ╰── GtkGestureSingle
                    ╰── GtkDragSource

## Includes

    #include <gtk/gtk.h>

## Description

GtkDragSource is an auxiliary object that is used to initiate Drag-And-Drop operations. It can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a GdkContentProvider, the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using `gtk_widget_add_controller()`.

Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, GtkDragSource has “prepare” and “drag-begin” signals. The ::prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with. The ::drag-begin signal is emitted after the GdkDrag object has been created, and can be used to set up the drag icon.

During the DND operation, GtkDragSource emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case: when the supported actions include `GDK_ACTION_MOVE`, you need to listen for the “drag-end” signal and delete the data after it has been transferred.

## Functions

### gtk_drag_source_new ()

    GtkDragSource *
    gtk_drag_source_new (void);

Creates a new GtkDragSource object.

#### Returns

the new GtkDragSource

### gtk_drag_source_set_content ()

    void
    gtk_drag_source_set_content (GtkDragSource *source,
                                 GdkContentProvider *content);

Sets a content provider on a GtkDragSource.

When the data is requested in the cause of a DND operation, it will be obtained from the content provider.

This function can be called before a drag is started, or in a handler for the “prepare” signal.

You may consider setting the content provider back to `NULL` in a “drag-end” signal handler.

#### Parameters

source | a GtkDragSource |
content | a GdkContentProvider, or `NULL`. | [nullable]

### gtk_drag_source_get_content ()

    GdkContentProvider *
    gtk_drag_source_get_content (GtkDragSource *source);

Gets the current content provider of a GtkDragSource.

#### Parameters

source | a GtkDragSource |

#### Returns

the GdkContentProvider of `source` .

[transfer none]

### gtk_drag_source_set_actions ()

    void
    gtk_drag_source_set_actions (GtkDragSource *source,
                                 GdkDragAction actions);

Sets the actions on the GtkDragSource.

During a DND operation, the actions are offered to potential drop targets. If `actions` include `GDK_ACTION_MOVE`, you need to listen to the “drag-end” signal and handle `delete_data` being `TRUE`.

This function can be called before a drag is started, or in a handler for the “prepare” signal.

#### Parameters

source | a GtkDragSource |
actions | the actions to offer |

### gtk_drag_source_get_actions ()

    GdkDragAction
    gtk_drag_source_get_actions (GtkDragSource *source);

Gets the actions that are currently set on the GtkDragSource.

#### Parameters

source | a GtkDragSource |

#### Returns

the actions set on `source`

### gtk_drag_source_set_icon ()

    void
    gtk_drag_source_set_icon (GtkDragSource *source,
                              GdkPaintable *paintable,
                              int hot_x,
                              int hot_y);

Sets a paintable to use as icon during DND operations.

The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor.

If `paintable` is `NULL`, a default icon is used.

This function can be called before a drag is started, or in a “prepare” or “drag-begin” signal handler.

#### Parameters

source | a GtkDragSource |
paintable | the GdkPaintable to use as icon, or `NULL`. | [nullable]
hot_x | the hotspot X coordinate on the icon |
hot_y | the hotspot Y coordinate on the icon |

### gtk_drag_source_drag_cancel ()

    void
    gtk_drag_source_drag_cancel (GtkDragSource *source);

Cancels a currently ongoing drag operation.

#### Parameters

source | a GtkDragSource |

### gtk_drag_source_get_drag ()

    GdkDrag *
    gtk_drag_source_get_drag (GtkDragSource *source);

Returns the underlying GdkDrag object for an ongoing drag.

#### Parameters

source | a GtkDragSource |

#### Returns

the GdkDrag of the current drag operation, or `NULL`.

[nullable][transfer none]

### gtk_drag_check_threshold ()

    gboolean
    gtk_drag_check_threshold (GtkWidget *widget,
                              int start_x,
                              int start_y,
                              int current_x,
                              int current_y);

Checks to see if a mouse drag starting at (`start_x` , `start_y` ) and ending at (`current_x` , `current_y` ) has passed the GTK drag threshold, and thus should trigger the beginning of a drag-and-drop operation.

[method]

#### Parameters

widget | a GtkWidget |
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 |

#### Returns

`TRUE` if the drag threshold has been passed.

## Types and Values

### GtkDragSource

    typedef struct _GtkDragSource GtkDragSource;

## Property Details

### The `“actions”` property

      “actions”                  GdkDragAction

The actions that are supported by drag operations from the source.

Note that you must handle the “drag-end” signal if the actions include `GDK_ACTION_MOVE`.

Owner: GtkDragSource

Flags: Read / Write

Default value: GDK_ACTION_COPY

### The `“content”` property

      “content”                  GdkContentProvider *

The data that is offered by drag operations from this source, in the form of a GdkContentProvider.

Owner: GtkDragSource

Flags: Read / Write

## Signal Details

### The `“drag-begin”` signal

    void
    user_function (GtkDragSource *source,
                   GdkDrag       *drag,
                   gpointer       user_data)

The ::drag-begin signal is emitted on the drag source when a drag is started. It can be used to e.g. set a custom drag icon with `gtk_drag_source_set_icon()`.

#### Parameters

source | the GtkDragSource |
drag | the GdkDrag object |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“drag-cancel”` signal

    gboolean
    user_function (GtkDragSource      *source,
                   GdkDrag            *drag,
                   GdkDragCancelReason reason,
                   gpointer            user_data)

The ::drag-cancel signal is emitted on the drag source when a drag has failed. The signal handler may handle a failed drag operation based on the type of error. It should return `TRUE` if the failure has been handled and the default "drag operation failed" animation should not be shown.

#### Parameters

source | the GtkDragSource |
drag | the GdkDrag object |
reason | information on why the drag failed |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the failed drag operation has been already handled

Flags: Run Last

### The `“drag-end”` signal

    void
    user_function (GtkDragSource *source,
                   GdkDrag       *drag,
                   gboolean       delete_data,
                   gpointer       user_data)

The ::drag-end signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in “prepare” or “drag-begin”.

#### Parameters

source | the GtkDragSource |
drag | the GdkDrag object |
delete_data | `TRUE` if the drag was performing `GDK_ACTION_MOVE`, and the data should be deleted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“prepare”` signal

    GdkContentProvider*
    user_function (GtkDragSource *source,
                   gdouble        x,
                   gdouble        y,
                   gpointer       user_data)

The ::prepare signal is emitted when a drag is about to be initiated. It returns the * GdkContentProvider to use for the drag that is about to start. The default handler for this signal returns the value of the “content” property, so if you set up that property ahead of time, you don't need to connect to this signal.

#### Parameters

source | the GtkDragSource |
x | the X coordinate of the drag starting point |
y | the Y coordinate fo the drag starting point |
user_data | user data set when the signal handler was connected. |

#### Returns

a GdkContentProvider, or `NULL`.

[transfer full][nullable]

Flags: Run Last