DropTarget#

class DropTarget(**properties: Any)#

Superclasses: EventController, Object

GtkDropTarget is an event controller to receive Drag-and-Drop operations.

The most basic way to use a GtkDropTarget to receive drops on a widget is to create it via new, passing in the GType of the data you want to receive and connect to the drop signal to receive the data:

static gboolean
on_drop (GtkDropTarget *target,
         const GValue  *value,
         double         x,
         double         y,
         gpointer       data)
{
  MyWidget *self = data;

  // Call the appropriate setter depending on the type of data
  // that we received
  if (G_VALUE_HOLDS (value, G_TYPE_FILE))
    my_widget_set_file (self, g_value_get_object (value));
  else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
    my_widget_set_pixbuf (self, g_value_get_object (value));
  else
    return FALSE;

  return TRUE;
}

static void
my_widget_init (MyWidget *self)
{
  GtkDropTarget *target =
    gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);

  // This widget accepts two types of drop types: GFile objects
  // and GdkPixbuf objects
  gtk_drop_target_set_gtypes (target, (GType [2]) {
    G_TYPE_FILE,
    GDK_TYPE_PIXBUF,
  }, 2);

  g_signal_connect (target, "drop", G_CALLBACK (on_drop), self);
  gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
}

GtkDropTarget supports more options, such as:

  • rejecting potential drops via the accept signal

    and the reject function to let other drop targets handle the drop

  • tracking an ongoing drag operation before the drop via the

    enter, motion and leave signals

  • configuring how to receive data by setting the

    preload property and listening for its availability via the value property

However, GtkDropTarget is ultimately modeled in a synchronous way and only supports data transferred via GType. If you want full control over an ongoing drop, the DropTargetAsync object gives you this ability.

While a pointer is dragged over the drop target’s widget and the drop has not been rejected, that widget will receive the DROP_ACTIVE state, which can be used to style the widget.

If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use DropControllerMotion.

Constructors#

class DropTarget
classmethod new(type: GType, actions: DragAction) → DropTarget#

Creates a new GtkDropTarget object.

If the drop target should support more than 1 type, pass Invalid for type and then call set_gtypes.

Parameters:

  • type – The supported type or Invalid

  • actions – the supported actions

Methods#

class DropTarget
get_actions() → DragAction#

Gets the actions that this drop target supports.

get_current_drop() → Drop | None#

Gets the currently handled drop operation.

If no drop operation is going on, None is returned.

Added in version 4.4.

get_drop() → Drop | None#

Gets the currently handled drop operation.

If no drop operation is going on, None is returned.

Deprecated since version 4.4: Use get_current_drop instead

get_formats() → ContentFormats | None#

Gets the data formats that this drop target accepts.

If the result is None, all formats are expected to be supported.

get_gtypes() → list[GType] | None#

Gets the list of supported GTypes that can be dropped on the target.

If no types have been set, NULL will be returned.

get_preload() → bool#

Gets whether data should be preloaded on hover.

get_value() → Value | None#

Gets the current drop data, as a GValue.

reject() → None#

Rejects the ongoing drop operation.

If no drop operation is ongoing, i.e when current_drop is None, this function does nothing.

This function should be used when delaying the decision on whether to accept a drag or not until after reading the data.

set_actions(actions: DragAction) → None#

Sets the actions that this drop target supports.

Parameters:

actions – the supported actions

set_gtypes(types: list[GType] | None = None) → None#

Sets the supported GTypes for this drop target.

Parameters:

types – all supported GTypes that can be dropped on the target

set_preload(preload: bool) → None#

Sets whether data should be preloaded on hover.

Parameters:

preload – True to preload drop data

Properties#

class DropTarget
props.actions: DragAction#

The type of the None singleton.

props.current_drop: Drop#

The type of the None singleton.

Added in version 4.4.

props.drop: Drop#

The type of the None singleton.

Deprecated since version 4.4: Use current_drop instead

props.formats: ContentFormats#

The type of the None singleton.

props.preload: bool#

The type of the None singleton.

props.value: Value#

The type of the None singleton.

Signals#

class DropTarget.signals
accept(drop: Drop) → bool#

The type of the None singleton.

Parameters:

drop – the GdkDrop

drop(value: Value, x: float, y: float) → bool#

The type of the None singleton.

Parameters:

  • value – the GValue being dropped

  • x – the x coordinate of the current pointer position

  • y – the y coordinate of the current pointer position

enter(x: float, y: float) → DragAction#

The type of the None singleton.

Parameters:

  • x – the x coordinate of the current pointer position

  • y – the y coordinate of the current pointer position

leave() → None#

The type of the None singleton.

motion(x: float, y: float) → DragAction#

The type of the None singleton.

Parameters:

  • x – the x coordinate of the current pointer position

  • y – the y coordinate of the current pointer position