---

NSDraggingDestination

(informal protocol)

Overview

The NSDraggingDestination interface declares methods that the destination object (or recipient) of a dragged image must implement. The destination automatically receives NSDraggingDestination messages for pasteboard data types it has registered for as an image enters, moves around inside, and then exits or is released within the destination’s boundaries.

Tasks

Before the Image Is Released

• draggingEntered
• draggingUpdated
• draggingEnded
• draggingExited
• wantsPeriodicDraggingUpdates

After the Image Is Released

• prepareForDragOperation
• performDragOperation
• concludeDragOperation

Instance Methods

concludeDragOperation

public abstract void concludeDragOperaton(NSDraggingInfo sender)

Discussion

Invoked when the dragging operation is complete and the previous performDragOperation returned true. The destination implements this method to perform any tidying up that it needs to do, such as updating its visual representation now that it has incorporated the dragged data. This message is the last message sent from sender to the destination during a dragging session.

draggingEnded

Implement this method to be notified when a drag operation ends in some other destination.

public abstract void draggingEnded(NSDraggingInfo sender)

Discussion

This method might be used by a destination doing autoexpansion in order to collapse any autoexpands. sender contains details about the dragging operation. This method has not yet been implemented.

draggingEntered

public abstract int draggingEntered(NSDraggingInfo sender)

Discussion

Invoked when a dragged image enters the destination but only if the destination has registered for the pasteboard data type involved in the drag operation. Specifically, this method is invoked when the mouse pointer enters the destination’s bounds rectangle (if it is a view object) or its frame rectangle (if it is a window object).

This method must return a value that indicates which dragging operation the destination will perform when the image is released. In deciding which dragging operation to return, the method should evaluate the overlap between both the dragging operations allowed by the source (obtained from sender with the draggingSourceOperationMask method) and the dragging operations and pasteboard data types the destination itself supports. The returned value should be exactly one of the dragging operation constants described in NSDraggingInfo’s "Constants" section.

If none of the operations is appropriate, this method should return NSDraggingInfo.DragOperationNone (this is the default response if the method is not implemented by the destination). A destination will still receive draggingUpdated and draggingExited even if NSDraggingInfo.DragOperationNone is returned by this method.

See Also

• draggingUpdated
• draggingExited
• prepareForDragOperation

draggingExited

Invoked when the dragged image exits the destination’s bounds rectangle (in the case of a view object) or its frame rectangle (in the case of a window object).

public abstract void draggingExited(NSDraggingInfo sender)

Discussion

sender contains details about the dragging operation.

draggingUpdated

public abstract int draggingUpdated(NSDraggingInfo sender)

Discussion

Invoked periodically as the image is held within the destination if the destination has registered for the pasteboard data type involved in the drag operation. The messages continue until the image is either released or dragged out of the window or view. The returned value should be exactly one of the dragging operation constants described in NSDraggingInfo’s constants section. The default return value (if this method is not implemented by the destination) is the value returned by the previous draggingEntered message.

This method provides the destination with an opportunity to modify the dragging operation depending on the position of the mouse pointer inside of the destination view or window object. For example, you may have several graphics or areas of text contained within the same view and wish to tailor the dragging operation, or to ignore the drag event completely, depending upon which object is underneath the mouse pointer at the time when the user releases the dragged image and the performDragOperation method is invoked. sender contains details about the dragging operation.

You typically examine the contents of the pasteboard in the draggingEntered method, where this examination is performed only once, rather than in the draggingUpdated method, which is invoked multiple times.

Only one destination at a time receives a sequence of draggingUpdated messages. If the mouse pointer is within the bounds of two overlapping views that are both valid destinations, the uppermost view receives these messages until the image is either released or dragged out.

See Also

• draggingExited
• prepareForDragOperation

performDragOperation

public abstract boolean performDragOperation(NSDraggingInfo sender)

Discussion

Invoked after the released image has been removed from the screen and the previous prepareForDragOperation message has returned true. The destination should implement this method to do the real work of importing the pasteboard data represented by the image. If the destination accepts the data, it returns true; otherwise it returns false. The default is to return false. Use sender to obtain details about the dragging operation.

See Also

• concludeDragOperation

prepareForDragOperation

public abstract boolean prepareForDragOperation(NSDraggingInfo sender)

Discussion

Invoked when the image is released, if the most recent draggingEntered or draggingUpdated message returned an acceptable drag-operation value. Returns true if the receiver agrees to perform the drag operation and false if not. Use sender to obtain details about the dragging operation.

See Also

• performDragOperation

wantsPeriodicDraggingUpdates

Requests the destination object whether it wants to receive periodic draggingUpdated messages.

public abstract boolean wantsPeriodicDraggingUpdates()

Discussion

If the destination returns NO, these messages are sent only when the mouse moves or a modifier flag changes. Otherwise the destination gets the default behavior, where it receives periodic dragging-updated messages even if nothing changes.

Availability

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

---