---

NSDraggingSource

(informal protocol)

Overview

The NSDraggingSource interface declares methods that are implemented by the source object in a dragging session. The dragging source is specified as an argument to the dragImage message, sent to a window or view object to initiate the dragging session.

Of the methods declared below, only draggingSourceOperationMaskForLocal must be implemented. The other methods are invoked only if the dragging source implements them. All methods are invoked automatically during a dragging session—you never send an NSDraggingSource message directly to an object.

Tasks

Specifying Dragging Options

• draggingSourceOperationMaskForLocal
• ignoreModifierKeysWhileDragging

Responding to Dragging Sessions

• startedDraggingImage
• finishedDraggingImage
• movedDraggingImage
• namesOfPromisedFilesDroppedAtDestination

Instance Methods

draggingSourceOperationMaskForLocal

public abstract int draggingSourceOperationMaskForLocal(boolean isLocal)

Discussion

This method is the only NSDraggingSource method that must be implemented by the source object. It should return a mask, built by combining the allowed dragging operations listed in NSDraggingInfo’s constants section, using the C bitwise OR operator. You should use this mask to indicate which types of dragging operations the source object will allow to be performed on the dragged image’s data. A true value for isLocal indicates that the candidate destination object (the window or view over which the dragged image is currently poised) is in the same application as the source, while a false value indicates that the destination object is in a different application.

If the source does not permit any dragging operations, it should return NSDraggingInfo.DragOperationNone.

finishedDraggingImage

public abstract void finishedDraggingImage(NSImage anImage, NSPoint aPoint, boolean flag)

Discussion

Invoked after anImage has been released and the dragging destination has been given a chance to operate on the data it represents. aPoint is the location of the image’s origin in the screen coordinate system when it was released. A true value for flag indicates that the destination accepted the dragged data, while a false value indicates that it was rejected.

This method provides the source object with an opportunity to respond to either a successful or a failed dragging session. For example, if you are moving data from one location to another, you could use this method to make the source data disappear from its previous location, if the dragging session is successful, or reset itself to its previous state, in the event of a failure.

Similar to the previous version of this method, but includes an indication of the operation performed by the destination in operation, rather than a boolean indicating acceptance.

public abstract void finishedDraggingImage(NSImage anImage, NSPoint aPoint, int operation)

See Also

• convertScreenToBase (NSWindow)
• convertBaseToScreen (NSWindow)
• convertPointFromView (NSView)
• convertPointToView (NSView)

ignoreModifierKeysWhileDragging

Sets whether the use of modifier keys should have an effect on the type of operation performed.

public abstract boolean ignoreModifierKeysWhileDragging()

Discussion

If this method is not implemented or returns false, the user can tailor the drag operation by holding down a modifier key during the drag. The dragging option that corresponds to the modifier key is combined with the source’s mask (as set with the draggingSourceOperationMaskForLocal method) using the C bitwise AND operator. See the description for the draggingSourceOperationMask method in the NSDraggingInfo interface specification for more information about dragging masks and modifier keys.

movedDraggingImage

Informs the dragging source about draggedImage moving to a new screen coordinate, screenPoint, similar to the dragging destination being sent draggingUpdated messages.

public abstract void movedDraggingImage(NSImage draggedImage, NSPoint screenPoint)

namesOfPromisedFilesDroppedAtDestination

Returns the names (not full paths) of the files that the receiver promises to create at dropDestination.

public abstract NSArray namesOfPromisedFilesDroppedAtDestination(java.net.URL dropDestination)

Discussion

This method is invoked when the drop has been accepted by the destination and the destination, in the case of another Cocoa application, invokes the NSDraggingInfo method namesOfPromisedFilesDroppedAtDestination. For long operations, you can cache dropDestination and defer the creation of the files until the finishedDraggingImage method to avoid blocking the destination application.

Availability

• Available in Mac OS X v10.2 and later.

startedDraggingImage

public abstract void startedDraggingImage(NSImage anImage, NSPoint aPoint)

Discussion

Invoked when anImage is displayed but before it starts following the mouse. aPoint is the origin of the image in screen coordinates. This method provides the source object with an opportunity to respond to the initiation of a dragging session. For example, you might choose to have the source give a visual indication to the user that data is being dragged from the source.

See Also

• convertScreenToBase (NSWindow)
• convertBaseToScreen (NSWindow)
• convertPointFromView (NSView)
• convertPointToView (NSView)

---