Class DragSource

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gtk.EventController
org.gnome.gtk.Gesture
org.gnome.gtk.GestureSingle
org.gnome.gtk.DragSource
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class DragSource extends GestureSingle

An event controller to initiate Drag-And-Drop operations.

GtkDragSource 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 ContentProvider, 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 Widget.addController(EventController).

static void
my_widget_init (MyWidget *self)
{
  GtkDragSource *drag_source = gtk_drag_source_new ();

  g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self);
  g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self);

  gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source));
}

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 Gtk.DragSource::prepare and Gtk.DragSource::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.

static GdkContentProvider *
on_drag_prepare (GtkDragSource *source,
                 double         x,
                 double         y,
                 MyWidget      *self)
{
  // This widget supports two types of content: GFile objects
  // and GdkPixbuf objects; GTK will handle the serialization
  // of these types automatically
  GFile *file = my_widget_get_file (self);
  GdkPixbuf *pixbuf = my_widget_get_pixbuf (self);

  return gdk_content_provider_new_union ((GdkContentProvider *[2]) {
      gdk_content_provider_new_typed (G_TYPE_FILE, file),
      gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf),
    }, 2);
}

The ::drag-begin signal is emitted after the GdkDrag object has been created, and can be used to set up the drag icon.

static void
on_drag_begin (GtkDragSource *source,
               GdkDrag       *drag,
               MyWidget      *self)
{
  // Set the widget as the drag icon
  GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self));
  gtk_drag_source_set_icon (source, paintable, 0, 0);
  g_object_unref (paintable);
}

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 DragAction.MOVE, you need to listen for the Gtk.DragSource::drag-end signal and delete the data after it has been transferred.

  • Constructor Details

    • DragSource

      public DragSource(MemorySegment address)
      Create a DragSource instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • DragSource

      public DragSource()
      Create a new DragSource.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the DragSource class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected DragSource asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class GestureSingle
      Returns:
      the instance as if it were its parent type

    • dragCancel

      public void dragCancel()
      Cancels a currently ongoing drag operation.

    • getActions

      public Set<DragAction> getActions()
      Gets the actions that are currently set on the GtkDragSource.
      Returns:
      the actions set on this DragSource

    • getContent

      public @Nullable ContentProvider getContent()
      Gets the current content provider of a GtkDragSource.
      Returns:
      the GdkContentProvider of this DragSource

    • getDrag

      public @Nullable Drag getDrag()
      Returns the underlying GdkDrag object for an ongoing drag.
      Returns:
      the GdkDrag of the current drag operation

    • setActions

      public void setActions(Set<DragAction> actions)

      Sets the actions on the GtkDragSource.

      During a DND operation, the actions are offered to potential drop targets. If actions include DragAction.MOVE, you need to listen to the Gtk.DragSource::drag-end signal and handle deleteData being true.

      This function can be called before a drag is started, or in a handler for the Gtk.DragSource::prepare signal.

      Parameters:
      actions - the actions to offer

    • setActions

      public void setActions(DragAction... actions)

      Sets the actions on the GtkDragSource.

      During a DND operation, the actions are offered to potential drop targets. If actions include DragAction.MOVE, you need to listen to the Gtk.DragSource::drag-end signal and handle deleteData being true.

      This function can be called before a drag is started, or in a handler for the Gtk.DragSource::prepare signal.

      Parameters:
      actions - the actions to offer

    • setContent

      public void setContent(@Nullable ContentProvider 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 Gtk.DragSource::prepare signal.

      You may consider setting the content provider back to null in a Gtk.DragSource::drag-end signal handler.

      Parameters:
      content - a GdkContentProvider

    • setIcon

      public void setIcon(@Nullable Paintable paintable, int hotX, int hotY)

      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 Gtk.DragSource::prepare or Gtk.DragSource::drag-begin signal handler.

      Parameters:
      paintable - the GdkPaintable to use as icon
      hotX - the hotspot X coordinate on the icon
      hotY - the hotspot Y coordinate on the icon

    • onDragBegin

      public SignalConnection<DragSource.DragBeginCallback> onDragBegin(DragSource.DragBeginCallback handler)

      Emitted on the drag source when a drag is started.

      It can be used to e.g. set a custom drag icon with setIcon(Paintable, int, int).

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDragBegin

      public void emitDragBegin(@Nullable Drag drag)
      Emits the "drag-begin" signal. See onDragBegin(DragSource.DragBeginCallback).

    • onDragCancel

      public SignalConnection<DragSource.DragCancelCallback> onDragCancel(DragSource.DragCancelCallback handler)

      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:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDragCancel

      public boolean emitDragCancel(@Nullable Drag drag, DragCancelReason reason)
      Emits the "drag-cancel" signal. See onDragCancel(DragSource.DragCancelCallback).

    • onDragEnd

      public SignalConnection<DragSource.DragEndCallback> onDragEnd(DragSource.DragEndCallback handler)

      Emitted on the drag source when a drag is finished.

      A typical reason to connect to this signal is to undo things done in Gtk.DragSource::prepare or Gtk.DragSource::drag-begin handlers.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDragEnd

      public void emitDragEnd(@Nullable Drag drag, boolean deleteData)
      Emits the "drag-end" signal. See onDragEnd(DragSource.DragEndCallback).

    • onPrepare

      public SignalConnection<DragSource.PrepareCallback> onPrepare(DragSource.PrepareCallback handler)

      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 Gtk.DragSource:content property, so if you set up that property ahead of time, you don't need to connect to this signal.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitPrepare

      public ContentProvider emitPrepare(double x, double y)
      Emits the "prepare" signal. See onPrepare(DragSource.PrepareCallback).

    • builder

      public static DragSource.Builder<? extends DragSource.Builder> builder()
      A DragSource.Builder object constructs a DragSource with the specified properties. Use the various set...() methods to set properties, and finish construction with DragSource.Builder.build().
      Returns:
      the builder object