Functions for controlling drag and drop handling

Description

GTK+ has a rich set of functions for doing inter-process communication via the drag-and-drop metaphor.

As well as the functions listed here, applications may need to use some facilities provided for [Selections][gtk3-Selections]. Also, the Drag and Drop API makes use of signals in the Gnome::Gtk3::Widget class.

Synopsis

Declaration

unit class Gnome::Gtk3::Drag;

Types

Methods

new

default, no options

Create a new Drag object.

multi method new ( )

This object does not wrap a native object into this Raku object because it does not need one. Therefore no option like :native-object is needed.

begin-with-coordinates

Initiates a drag on the source side. The function only needs to be used when the application is starting drags itself, and is not needed when source_set() is used.

The event is used to retrieve the timestamp that will be used internally to grab the pointer. If event is undefined, then GDK_CURRENT_TIME will be used. However, you should try to pass a real event in all cases, since that can be used to get information about the drag.

Generally there are three cases when you want to start a drag by hand by calling this function:

1. During a button-press-event from Gnome::Gtk3::Widget handler, if you want to start a drag immediately when the user presses the mouse button. Pass the event that you have in your button-press-event from Gnome::Gtk3::Widget handler.

2. During a motion-notify-event from Gnome::Gtk3::Widget handler, if you want to start a drag when the mouse moves past a certain threshold distance after a button-press. Pass the event that you have in your motion-notify-event from Gnome::Gtk3::Widget handler.

3. During a timeout handler, if you want to start a drag after the mouse button is held down for some time. Try to save the last event that you got from the mouse, using gdk_event_copy(), and pass it to this function (remember to free the event with gdk_event_free() when you are done). If you really cannot pass a real event, pass undefined instead.

Returns: the context for this drag

method begin-with-coordinates ( N-GObject() $widget, GtkTargetList $targets, GdkDragAction $actions, Int() $button, N-GdkEvent $event, Int() $x, Int() $y --> N-GObject )

• $widget; the source widget

• $targets; The targets (data formats) in which the source can provide the data

• $actions; A bitmask of the allowed drag actions for this drag

• $button; The button the user clicked to start the drag

• $event; The event that triggered the start of the drag, or undefined if none can be obtained.

• $x; The initial x coordinate to start dragging from, in the coordinate space of widget. If -1 is passed, the coordinates are retrieved from event or the current pointer position

• $y; The initial y coordinate to start dragging from, in the coordinate space of widget. If -1 is passed, the coordinates are retrieved from event or the current pointer position

cancel

Cancels an ongoing drag operation on the source side.

If you want to be able to cancel a drag operation in this way, you need to keep a pointer to the drag context, either from an explicit call to begin_with_coordinates(), or by connecting to drag-begin from Gnome::Gtk3::Widget.

If context does not refer to an ongoing drag operation, this function does nothing.

If a drag is cancelled in this way, the result argument of drag-failed from Gnome::Gtk3::Widget is set to GTK_DRAG_RESULT_ERROR.

method cancel ( N-GObject() $context )

• $context; a native Gnome::Gdk3::DragContext.

check-threshold

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.

Returns: True if the drag threshold has been passed.

method check-threshold ( N-GObject() $widget, Int() $start_x, Int() $start_y, Int() $current_x, Int() $current_y --> Bool )

• $widget; a Gnome::Gtk3::Widget

• $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

finish

Informs the drag source that the drop is finished, and that the data of the drag will no longer be required.

method finish ( N-GObject() $context, Bool $success, Bool $del, UInt $time )

• $context; the drag context

• $success; a flag indicating whether the drop was successful

• $del; a flag indicating whether the source should delete the original data. (This should be True for a move)

• $time; the timestamp from the drag-drop from Gnome::Gtk3::Widget signal

get-data

Gets the data associated with a drag. When the data is received or the retrieval fails, GTK+ will emit a drag-data-received from Gnome::Gtk3::Widget signal. Failure of the retrieval is indicated by the length field of the selection_data signal parameter being negative. However, when get_data() is called implicitely because the GTK_DEST_DEFAULT_DROP was set, then the widget will not receive notification of failed drops.

method get-data (
  N-GObject() $widget, N-GObject() $context,
  N-GObject() $target, UInt $time
)

• $widget; the widget that will receive the drag-data-received from Gnome::Gtk3::Widget signal

• $context; the drag context, a Gnome::Gdk3::DragContext.

• $target; the target (form of the data) to retrieve, A native Gnome::Gdk3::Atom.

• $time; a timestamp for retrieving the data. This will generally be the time received in a drag-motion from Gnome::Gtk3::Widget or drag-drop from Gnome::Gtk3::Widget signal

get-source-widget

Determines the source widget for a drag.

Returns: if the drag is occurring within a single application, a pointer to the source widget. Otherwise, undefined.

method get-source-widget ( N-GObject() $context --> N-GObject )

• $context; a (destination side) drag context

highlight

Highlights a widget as a currently hovered drop target. To end the highlight, call unhighlight(). GTK+ calls this automatically if GTK_DEST_DEFAULT_HIGHLIGHT is set.

method highlight ( N-GObject() $widget )

• $widget; a widget to highlight

set-icon-default

Sets the icon for a particular drag to the default icon.

method set-icon-default ( N-GObject() $context )

• $context; the context for a drag (This must be called with a context for the source side of a drag)

set-icon-gicon

Sets the icon for a given drag from the given icon. See the documentation for set_icon_name() for more details about using icons in drag and drop.

method set-icon-gicon ( N-GObject() $context, N-GObject() $icon, Int() $hot_x, Int() $hot_y )

• $context; the context for a drag (This must be called with a context for the source side of a drag)

• $icon; a Gnome::Gio::Icon

• $hot_x; the X offset of the hotspot within the icon

• $hot_y; the Y offset of the hotspot within the icon

set-icon-name

Sets the icon for a given drag from a named themed icon. See the docs for Gnome::Gtk3::IconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size Gnome::Gio::TK_ICON_SIZE_DND), thus hot_x and hot_y have to be used with care.

method set-icon-name (
  N-GObject() $context, Str $icon_name, Int() $hot_x, Int() $hot_y
)

• $context; the context for a drag (This must be called with a context for the source side of a drag)

• $icon_name; name of icon to use

• $hot_x; the X offset of the hotspot within the icon

• $hot_y; the Y offset of the hotspot within the icon

set-icon-pixbuf

Sets pixbuf as the icon for a given drag.

method set-icon-pixbuf (
  N-GObject() $context, N-GObject() $pixbuf,
  Int() $hot_x, Int() $hot_y
)

• $context; the context for a drag (This must be called with a context for the source side of a drag)

• $pixbuf; the Gnome::Gdk3::Pixbuf to use as the drag icon

• $hot_x; the X offset within widget of the hotspot

• $hot_y; the Y offset within widget of the hotspot

set-icon-surface

Sets surface as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed.

To position the surface relative to the mouse, use cairo_surface_set_device_offset() on surface. The mouse cursor will be positioned at the (0,0) coordinate of the surface.

method set-icon-surface ( N-GObject() $context, cairo_surface_t $surface )

• $context; the context for a drag (This must be called with a context for the source side of a drag)

• $surface; the surface to use as icon

set-icon-widget

Changes the icon for drag operation to a given widget. GTK+ will not destroy the widget, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself.

method set-icon-widget ( N-GObject() $context, N-GObject() $widget, Int() $hot_x, Int() $hot_y )

• $context; the context for a drag. (This must be called

• $widget; a widget to use as an icon

• $hot_x; the X offset within widget of the hotspot

• $hot_y; the Y offset within widget of the hotspot

unhighlight

Removes a highlight set by highlight() from a widget.

method unhighlight ( N-GObject() $widget )

• $widget; a widget to remove the highlight from