drag-pane-object Function

Summary

Initiates a dragging operation.

Package

capi

Signature

drag-pane-object pane value &key string plist image-function operations => operation

Arguments

Values

Description

The function drag-pane-object initiates a dragging operation from within the pane pane. It can only be called from within the button :press or button :motion callbacks of the input-model of an output-pane.

value, string and plist are combined to provide an object to be dragged in various formats.

value can be any Lisp object (not necessarily a string) to make available for dropping into a pane within the local Lisp image.

string can be a string representation of value to make available, or nil. If string is nil and value is a string, then that will be made available as the string.

plist is a property list of additional format/value pairs to make available. The currently supported formats are as described for set-drop-object-supported-formats. You can make more than one format available simultaneously.

image-function provides a graphical image for use during the dragging operation on Cocoa. If image-function is supplied, then it should be a function of one argument. It might be called to provide an image for use during the dragging operation. The function image-function should return three values: a image object, an x offset and a y offset. The x and y offsets are the position within the image where the mouse should be located. If the image is nil or image-function is not supplied then a default image is generated. If the x or y offsets are nil or not returned then the image is positioned with the mouse at its center point. The image that is returned by image-function is freed automatically in the end of dragging operation. It must be a new image, and cannot be reused.

operations should be a list of operation keywords that the pane will allow the target application to perform. The operation keywords are :copy, :move and :link as described for the effect in drop-object-drop-effect. If certain platform-specific modifier keys are pressed, then some of the operations will be ignored.

The return value operation indicates which operation was performed by the application where the dragged object was dropped. The value will be :none if the object was not dropped anywhere or dragging was abandoned (for example, by the user hitting the Escape key). If operation is :move, then you should update the data structures in your application to remove the object that was dragged.

Notes

1. drag-pane-object is not supported on X11/Motif. See simple-pane for information about drop callbacks.
2. image-function is only called on Cocoa. There is no way to specify an image when dragging on Microsoft Windows.
3. If :image is supplied in plist, the dragging mechanism automatically frees the image object as if by free-image when it no longer needs it.

Examples

(example-edit-file "capi/output-panes/drag-and-drop")

See also

simple-pane
17 Drag and Drop