gtk:event-controller, gobject:object, common-lisp:standard-object, common-lisp:t

None

The gtk:drop-target-async object is an auxiliary object that can be used to receive Drag-and-Drop operations. It is the more complete but also more complex method of handling drop operations compared to GtkDropTarget and you should only use it if gtk:drop-target object does not provide all the features you need.

To use a gtk:drop-target-async object to receive drops on a widget, you create a gtk:drop-target-async object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with the gtk:widget-add-controller function.

During a drag operation, the first signal that a gtk:drop-target-async object emits is the "accept" signal, which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the "accept" signal accepts the drop if it finds a compatible data format and an action that is supported on both sides.

If it is, and the widget becomes a target, you will receive a "drag-enter" signal, followed by "drag-motion" signals as the pointer moves, optionally a "drop" signal when a drop happens, and finally a "drag-leave" signal when the pointer moves off the widget.

The "drag-enter" and "drag-motion" handler return a gdk:drag-action value to update the status of the ongoing operation. The "drop" signal handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling the gdk:drop-finish function.

Between the "drag-enter" and "drag-leave" signals the widget is a current drop target, and will receive the :drop-active state of the gtk:state-flags flags, which can be used by themes to style the widget as a drop target.

The "accept" signal

lambda (target drop)    :run-last      

target

The gtk:drop-target-async object.

drop

The gdk:drop object.

Returns

True if the drop is accepted.

The signal is emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, false will be returned and the drop target will ignore the drop. If true is returned, the drop is accepted for now but may be rejected later via a call to the gtk:drop-target-async-reject-drop function or ultimately by returning false from the "drop" signal handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the drop object. If the decision whether the drop will be accepted or rejected needs further processing, such as inspecting the data, this function should return true and proceed as this drop was accepted and if it decides to reject the drop later, it should call the gtk:drop-target-async-reject-drop function.

The "drag-enter" signal

lambda (target drop x y)    :run-last      

target

The gtk:drop-target-async object.

drop

The gdk:drop object.

x

A double float with the x coordinate of the current pointer position.

y

A double float with the y coordinate of the current pointer position.

Returns

A boolean with the preferred action for this drag operation.

The signal is emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting.

The "drag-leave" signal

lambda (target drop)    :run-last      

The signal is emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in the "drag-enter" signal handler.

target

The gtk:drop-target-async object.

drop

The gdk:drop object.

The "drag-motion" signal

lambda (target drop x y)    :run-last      

The signal is emitted while the pointer is moving over the drop target.

target

The gtk:drop-target-async object.

drop

The gdk:drop object.

x

A double float with the x coordinate of the current pointer position.

y

A double float with the y coordinate of the current pointer position.

Returns

A boolean with the preferred action for this drag operation.

The "drop" signal

lambda (target drop x y)    :run-last      

The signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns false and no further processing is necessary. Otherwise, the handler returns true. In this case, this handler will accept the drop. The handler must ensure that the gdk:drop-finish function is called to let the source know that the drop is done. The call to the gdk:drop-finish function must only be done when all data has been received. To receive the data, use one of the read functions provides by the gdk:drop object such as the gdk:drop-read-async or gdk:drop-read-value-async functions.

target

The gtk:drop-target-async object.

drop

The gdk:drop object.

x

A double float with the x coordinate of the current pointer position.

y

A double float with the y coordinate of the current pointer position.

Returns

Whether the drop is accepted at the given pointer position.