DragSourceProtocol

public protocol DragSourceProtocol : GestureSingleProtocol

GtkDragSource is 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 [classGdk.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 [methodGtk.Widget.add_controller].

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 [signalGtk.DragSource::prepare] and [signalGtk.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,
               GtkDrag       *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 GDK_ACTION_MOVE, you need to listen for the [signalGtk.DragSource::drag-end] signal and delete the data after it has been transferred.

The DragSourceProtocol protocol exposes the methods and properties of an underlying GtkDragSource instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DragSource. Alternatively, use DragSourceRef as a lighweight, unowned reference if you already have an instance you just want to use.

Show on GitHub

ptr
Untyped pointer to the underlying GtkDragSource instance.
Declaration
Swift

var ptr: UnsafeMutableRawPointer! { get }
Show on GitHub
drag_source_ptr Default implementation
Typed pointer to the underlying GtkDragSource instance.

Default Implementation

Return the stored, untyped pointer as a typed pointer to the GtkDragSource instance.
Declaration
Swift

var drag_source_ptr: UnsafeMutablePointer<GtkDragSource>! { get }
Show on GitHub
init(raw:)
Required Initialiser for types conforming to DragSourceProtocol
Declaration
Swift

init(raw: UnsafeMutableRawPointer)
Show on GitHub

DragSource Class


                    
                    
                    bind(property:to:_:flags:transformFrom:transformTo:)

Extension method

Bind a DragSourcePropertyName source property to a given target object.

Declaration

Swift

@discardableResult
@inlinable
func bind<Q, T>(property source_property: DragSourcePropertyName, to target: T, _ target_property: Q, flags f: BindingFlags = .default, transformFrom transform_from: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }, transformTo transform_to: @escaping GLibObject.ValueTransformer = { $0.transform(destValue: $1) }) -> BindingRef! where Q : PropertyNameProtocol, T : ObjectProtocol

Parameters

`source_property`	the source property to bind
`target`	the target object to bind to
`target_property`	the target property to bind to
`flags`	the flags to pass to the `Binding`
`transform_from`	`ValueTransformer` to use for forward transformation
`transform_to`	`ValueTransformer` to use for backwards transformation

Return Value

binding reference or nil in case of an error

Show on GitHub


                    
                    
                    get(property:)

Extension method

Get the value of a DragSource property

Declaration

Swift

@inlinable
func get(property: DragSourcePropertyName) -> GLibObject.Value

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub


                    
                    
                    set(property:value:)

Extension method

Set the value of a DragSource property. Note that this will only have an effect on properties that are writable and not construct-only!

Declaration

Swift

@inlinable
func set(property: DragSourcePropertyName, value v: GLibObject.Value)

Parameters


                                property

the property to get the value for

Return Value

the value of the named property

Show on GitHub

DragSource signals


                    
                    
                    connect(signal:flags:handler:)

Extension method

Connect a Swift signal handler to the given, typed DragSourceSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: DragSourceSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`handler`	The Swift signal handler (function or callback) to invoke on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    connect(signal:flags:data:destroyData:signalHandler:)

Extension method

Connect a C signal handler to the given, typed DragSourceSignalName signal

Declaration

Swift

@discardableResult
@inlinable
func connect(signal s: DragSourceSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

Parameters

`signal`	The signal to connect
`flags`	The connection flags to use
`data`	A pointer to user data to provide to the callback
`destroyData`	A `GClosureNotify` C function to destroy the data pointed to by `userData`
`signalHandler`	The C function to be called on the given signal

Return Value

The signal handler ID (always greater than 0 for successful connections)

Show on GitHub


                    
                    
                    prepareSignal

Extension method

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

Note

This represents the underlying prepare signal

Warning

a onPrepare wrapper for this signal could not be generated because it contains unimplemented features: { (8) nullable argument or return type is not allowed, (9) Record return type is not yet supported }

Note

Instead, you can connect prepareSignal using the connect(signal:) methods

Declaration

Swift

static var prepareSignal: DragSourceSignalName { get }

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`x`	the X coordinate of the drag starting point
`y`	the Y coordinate fo the drag starting point
`handler`	a `GdkContentProvider`

Show on GitHub


                    
                    
                    onDragBegin(flags:handler:)

Extension method

Emitted on the drag source when a drag is started.

It can be used to e.g. set a custom drag icon with [methodGtk.DragSource.set_icon].

Note

This represents the underlying drag-begin signal

Declaration

Swift

@discardableResult
@inlinable
func onDragBegin(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DragSourceRef, _ drag: Gdk.DragRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`drag`	the `GdkDrag` object
`handler`	The signal handler to call Run the given callback whenever the `dragBegin` signal is emitted

Show on GitHub

dragBeginSignal Extension method
Typed drag-begin signal for using the connect(signal:) methods
Declaration
Swift

static var dragBeginSignal: DragSourceSignalName { get }
Show on GitHub


                    
                    
                    onDragCancel(flags:handler:)

Extension method

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.

Note

This represents the underlying drag-cancel signal

Declaration

Swift

@discardableResult
@inlinable
func onDragCancel(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DragSourceRef, _ drag: Gdk.DragRef, _ reason: Gdk.DragCancelReason) -> Bool) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`drag`	the `GdkDrag` object
`reason`	information on why the drag failed
`handler`	`true` if the failed drag operation has been already handled Run the given callback whenever the `dragCancel` signal is emitted

Show on GitHub

dragCancelSignal Extension method
Typed drag-cancel signal for using the connect(signal:) methods
Declaration
Swift

static var dragCancelSignal: DragSourceSignalName { get }
Show on GitHub


                    
                    
                    onDragEnd(flags:handler:)

Extension method

Emitted on the drag source when a drag is finished.

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

Note

This represents the underlying drag-end signal

Declaration

Swift

@discardableResult
@inlinable
func onDragEnd(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DragSourceRef, _ drag: Gdk.DragRef, _ deleteData: Bool) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`drag`	the `GdkDrag` object
`deleteData`	`true` if the drag was performing `GDK_ACTION_MOVE`, and the data should be deleted
`handler`	The signal handler to call Run the given callback whenever the `dragEnd` signal is emitted

Show on GitHub

dragEndSignal Extension method
Typed drag-end signal for using the connect(signal:) methods
Declaration
Swift

static var dragEndSignal: DragSourceSignalName { get }
Show on GitHub


                    
                    
                    onNotifyActions(flags:handler:)

Extension method

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in notify being emitted, even if the new value is the same as the old. If they did pass G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::actions signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyActions(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DragSourceRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyActions` signal is emitted

Show on GitHub

notifyActionsSignal Extension method
Typed notify::actions signal for using the connect(signal:) methods
Declaration
Swift

static var notifyActionsSignal: DragSourceSignalName { get }
Show on GitHub


                    
                    
                    onNotifyContent(flags:handler:)

Extension method

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this:

(C Language Example):

g_signal_connect (text_view->buffer, "notify::paste-target-list",
                  G_CALLBACK (gtk_text_view_target_list_notify),
                  text_view)

It is important to note that you must use canonical parameter names as detail strings for the notify signal.

Note

This represents the underlying notify::content signal

Declaration

Swift

@discardableResult
@inlinable
func onNotifyContent(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: DragSourceRef, _ pspec: ParamSpecRef) -> Void) -> Int

Parameters

`flags`	Flags
`unownedSelf`	Reference to instance of self
`pspec`	the `GParamSpec` of the property which changed.
`handler`	The signal handler to call Run the given callback whenever the `notifyContent` signal is emitted

Show on GitHub

notifyContentSignal Extension method
Typed notify::content signal for using the connect(signal:) methods
Declaration
Swift

static var notifyContentSignal: DragSourceSignalName { get }
Show on GitHub

DragSource Class: DragSourceProtocol extension (methods and fields)

dragCancel() Extension method
Cancels a currently ongoing drag operation.
Declaration
Swift

@inlinable func dragCancel()
Show on GitHub
getActions() Extension method
Gets the actions that are currently set on the GtkDragSource.
Declaration
Swift

@inlinable func getActions() -> Gdk.DragAction
Show on GitHub
getContent() Extension method
Gets the current content provider of a GtkDragSource.
Declaration
Swift

@inlinable func getContent() -> Gdk.ContentProviderRef!
Show on GitHub
getDrag() Extension method
Returns the underlying GdkDrag object for an ongoing drag.
Declaration
Swift

@inlinable func getDrag() -> Gdk.DragRef!
Show on GitHub
set(actions:) Extension method
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 [signalGtk.DragSource::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 [signalGtk.DragSource::prepare] signal.
Declaration
Swift

@inlinable func set(actions: Gdk.DragAction)
Show on GitHub
set(content:) Extension method
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 [signalGtk.DragSource::prepare] signal.

You may consider setting the content provider back to nil in a [signalGtk.DragSource::drag-end] signal handler.
Declaration
Swift

@inlinable func set(content: Gdk.ContentProviderRef? = nil)
Show on GitHub
set(content:) Extension method
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 [signalGtk.DragSource::prepare] signal.

You may consider setting the content provider back to nil in a [signalGtk.DragSource::drag-end] signal handler.
Declaration
Swift

@inlinable func set<ContentProviderT>(content: ContentProviderT?) where ContentProviderT : ContentProviderProtocol
Show on GitHub
setIcon(paintable:hotX:hotY:) Extension method
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 nil, a default icon is used.

This function can be called before a drag is started, or in a [signalGtk.DragSource::prepare] or [signalGtk.DragSource::drag-begin] signal handler.
Declaration
Swift

@inlinable func setIcon(paintable: Gdk.PaintableRef? = nil, hotX: Int, hotY: Int)
Show on GitHub
setIcon(paintable:hotX:hotY:) Extension method
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 nil, a default icon is used.

This function can be called before a drag is started, or in a [signalGtk.DragSource::prepare] or [signalGtk.DragSource::drag-begin] signal handler.
Declaration
Swift

@inlinable func setIcon<PaintableT>(paintable: PaintableT?, hotX: Int, hotY: Int) where PaintableT : PaintableProtocol
Show on GitHub
actions Extension method
The actions that are supported by drag operations from the source.

Note that you must handle the [signalGtk.DragSource::drag-end] signal if the actions include GDK_ACTION_MOVE.
Declaration
Swift

@inlinable var actions: Gdk.DragAction { get nonmutating set }
Show on GitHub
content Extension method
The data that is offered by drag operations from this source.
Declaration
Swift

@inlinable var content: Gdk.ContentProviderRef! { get nonmutating set }
Show on GitHub
drag Extension method
Returns the underlying GdkDrag object for an ongoing drag.
Declaration
Swift

@inlinable var drag: Gdk.DragRef! { get }
Show on GitHub

DragSourceProtocol

Declaration

Default Implementation

Declaration

Declaration

DragSource Class

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

DragSource signals

Declaration

Parameters

Return Value

Declaration

Parameters

Return Value

Declaration

Parameters

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

Declaration

Parameters

Declaration

DragSource Class: DragSourceProtocol extension (methods and fields)

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration

Declaration