## Drag And Drop Drag And Drop — Functions for controlling drag and drop handling |

## Functions

void | gdk_drag_drop_done ()
GdkDragContext * | gdk_drag_begin ()
GdkDisplay * | gdk_drag_context_get_display ()
GdkDragAction | gdk_drag_context_get_actions ()
GdkDragAction | gdk_drag_context_get_suggested_action ()
GdkDragAction | gdk_drag_context_get_selected_action ()
GdkContentFormats * | gdk_drag_context_get_formats ()
GdkDevice * | gdk_drag_context_get_device ()
GdkSurface * | gdk_drag_context_get_drag_surface ()
void | gdk_drag_context_set_hotspot ()
gboolean | gdk_drag_action_is_unique ()

## Properties

GdkContentProvider * | content | Read / Write / Construct Only
GdkDevice * | device | Read / Write / Construct Only
GdkDisplay * | display | Read
GdkContentFormats * | formats | Read / Write / Construct Only

## Signals

void | action-changed | Run Last
void | cancel | Run Last
void | dnd-finished | Run Last
void | drop-performed | Run Last

## Types and Values

| GdkDragContext
enum | GdkDragCancelReason
enum | GdkDragAction
#define | GDK_ACTION_ALL

## Object Hierarchy

        GObject
        ╰── GdkDragContext

## Includes

    #include <gdk/gdk.h>

## Description

These functions provide a low level interface for drag and drop. The X backend of GDK supports both the Xdnd and Motif drag and drop protocols transparently, the Win32 backend supports the WM_DROPFILES protocol.

GTK+ provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK+ applications. See the Drag and Drop section of the GTK+ documentation for more information.

## Functions

### gdk_drag_drop_done ()

    void
    gdk_drag_drop_done (GdkDragContext *context,
                        gboolean success);

Inform GDK if the drop ended successfully. Passing `FALSE` for `success` may trigger a drag cancellation animation.

This function is called by the drag source, and should be the last call before dropping the reference to the `context` .

The GdkDragContext will only take the first `gdk_drag_drop_done()` call as effective, if this function is called multiple times, all subsequent calls will be ignored.

#### Parameters

context | a GdkDragContext |
success | whether the drag was ultimatively successful |

### gdk_drag_begin ()

    GdkDragContext *
    gdk_drag_begin (GdkSurface *surface,
                    GdkDevice *device,
                    GdkContentProvider *content,
                    GdkDragAction actions,
                    gint dx,
                    gint dy);

Starts a drag and creates a new drag context for it.

This function is called by the drag source.

#### Parameters

surface | the source surface for this drag |
device | the device that controls this drag |
content | the offered content. | [transfer none]
actions | the actions supported by this drag |
dx | the x offset to `device` 's position where the drag nominally started |
dy | the y offset to `device` 's position where the drag nominally started |

#### Returns

a newly created GdkDragContext or `NULL` on error.

[transfer full][nullable]

### gdk_drag_context_get_display ()

    GdkDisplay *
    gdk_drag_context_get_display (GdkDragContext *context);

Gets the GdkDisplay that the drag context was created for.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkDisplay.

[transfer none]

### gdk_drag_context_get_actions ()

    GdkDragAction
    gdk_drag_context_get_actions (GdkDragContext *context);

Determines the bitmask of actions proposed by the source if `gdk_drag_context_get_suggested_action()` returns `GDK_ACTION_ASK`.

#### Parameters

context | a GdkDragContext |

#### Returns

the GdkDragAction flags

### gdk_drag_context_get_suggested_action ()

    GdkDragAction
    gdk_drag_context_get_suggested_action (GdkDragContext *context);

Determines the suggested drag action of the context.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkDragAction value

### gdk_drag_context_get_selected_action ()

    GdkDragAction
    gdk_drag_context_get_selected_action (GdkDragContext *context);

Determines the action chosen by the drag destination.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkDragAction value

### gdk_drag_context_get_formats ()

    GdkContentFormats *
    gdk_drag_context_get_formats (GdkDragContext *context);

Retrieves the formats supported by this context.

#### Parameters

context | a GdkDragContext |

#### Returns

a GdkContentFormats.

[transfer none]

### gdk_drag_context_get_device ()

    GdkDevice *
    gdk_drag_context_get_device (GdkDragContext *context);

Returns the GdkDevice associated to the drag context.

#### Parameters

context | a GdkDragContext |

#### Returns

The GdkDevice associated to `context` .

[transfer none]

### gdk_drag_context_get_drag_surface ()

    GdkSurface *
    gdk_drag_context_get_drag_surface (GdkDragContext *context);

Returns the surface on which the drag icon should be rendered during the drag operation. Note that the surface may not be available until the drag operation has begun. GDK will move the surface in accordance with the ongoing drag operation. The surface is owned by `context` and will be destroyed when the drag operation is over.

#### Parameters

context | a GdkDragContext |

#### Returns

the drag surface, or `NULL`.

[nullable][transfer none]

### gdk_drag_context_set_hotspot ()

    void
    gdk_drag_context_set_hotspot (GdkDragContext *context,
                                  gint hot_x,
                                  gint hot_y);

Sets the position of the drag surface that will be kept under the cursor hotspot. Initially, the hotspot is at the top left corner of the drag surface.

#### Parameters

context | a GdkDragContext |
hot_x | x coordinate of the drag surface hotspot |
hot_y | y coordinate of the drag surface hotspot |

### gdk_drag_action_is_unique ()

    gboolean
    gdk_drag_action_is_unique (GdkDragAction action);

Checks if `action` represents a single action or if it includes multiple flags that can be selected from.

When `action` is 0 - ie no action was given, `TRUE` is returned.

#### Parameters

action | a GdkDragAction |

#### Returns

`TRUE` if exactly one action was given

## Types and Values

### GdkDragContext

    typedef struct _GdkDragContext GdkDragContext;

The GdkDragContext struct contains only private fields and should not be accessed directly.

### enum GdkDragCancelReason

Used in GdkDragContext to the reason of a cancelled DND operation.

#### Members

GDK_DRAG_CANCEL_NO_TARGET | There is no suitable drop target. |
GDK_DRAG_CANCEL_USER_CANCELLED | Drag cancelled by the user |
GDK_DRAG_CANCEL_ERROR | Unspecified error. |

### enum GdkDragAction

Used in GdkDragContext to indicate what the destination should do with the dropped data.

#### Members

GDK_ACTION_COPY | Copy the data. |
GDK_ACTION_MOVE | Move the data, i.e. first copy it, then delete it from the source using the DELETE target of the X selection protocol. |
GDK_ACTION_LINK | Add a link to the data. Note that this is only useful if source and destination agree on what it means. |
GDK_ACTION_ASK | Ask the user what to do with the data. |

### GDK_ACTION_ALL

    #define GDK_ACTION_ALL (GDK_ACTION_COPY | GDK_ACTION_MOVE | GDK_ACTION_LINK)

Defines all possible DND actions. This can be used in `gdk_drop_status()` messages when any drop can be accepted or a more specific drop method is not yet known.

## Property Details

### The `“content”` property

      “content”                  GdkContentProvider *

The GdkContentProvider or `NULL` if the context is not a source-side context.

Flags: Read / Write / Construct Only

### The `“device”` property

      “device”                   GdkDevice *

The GdkDevice that is performing the drag.

Flags: Read / Write / Construct Only

### The `“display”` property

      “display”                  GdkDisplay *

The GdkDisplay that the drag context belongs to.

Flags: Read

### The `“formats”` property

      “formats”                  GdkContentFormats *

The possible formats that the context can provide its data in.

Flags: Read / Write / Construct Only

## Signal Details

### The `“action-changed”` signal

    void
    user_function (GdkDragContext *context,
                   GdkDragAction   action,
                   gpointer        user_data)

A new action is being chosen for the drag and drop operation.

#### Parameters

context | The object on which the signal is emitted |
action | The action currently chosen |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“cancel”` signal

    void
    user_function (GdkDragContext     *context,
                   GdkDragCancelReason reason,
                   gpointer            user_data)

The drag and drop operation was cancelled.

#### Parameters

context | The object on which the signal is emitted |
reason | The reason the context was cancelled |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“dnd-finished”` signal

    void
    user_function (GdkDragContext *context,
                   gpointer        user_data)

The drag and drop operation was finished, the drag destination finished reading all data. The drag source can now free all miscellaneous data.

#### Parameters

context | The object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“drop-performed”` signal

    void
    user_function (GdkDragContext *context,
                   gpointer        user_data)

The drag and drop operation was performed on an accepting client.

#### Parameters

context | The object on which the signal is emitted |
user_data | user data set when the signal handler was connected. |

Flags: Run Last