NSDraggingDestination

(informal protocol)

Category Of: NSObject

Declared In: AppKit/NSDragging.h

Protocol Description

The NSDraggingDestination protocol declares methods that the destination (or recipient) of a dragged image must implement. The destination automatically receives NSDraggingDestination messages as an image enters, moves around inside, and then exits or is released within the destination's boundaries.

Note: In the text here and in the other dragging protocol descriptions, the term dragging session is the entire process during which an image is selected, dragged, released, and is absorbed or rejected by the destination. A dragging operation is the action that the destination takes in absorbing the image when it's released. The dragging source is the object that owns the image that's being dragged. It's specified as an argument to the dragImage:... message, sent to a NSWindow or NSView, that instigated the dragging session.

The Dragged Image

The image that's dragged in an image-dragging session is an NSImage object that represents data that's put on the pasteboard. Although a dragging destination can access the NSImage (through a method described in the NSDraggingInfo protocol), its primary concern is with the pasteboard data that the NSImage representsthe dragging operation that a destination ultimately performs is on the pasteboard data, not on the image itself.

Valid Destinations

Dragging is a visual phenomenon. To be an image-dragging destination, an object must represent a portion of screen real estate; thus, only NSWindows and NSViews can be destinations. Furthermore, you must announce the destination-candidacy of an NSWindow or NSView by sending it a registerForDraggedTypes: message. This method, defined in both classes, registers the pasteboard types that the object will accept. During a dragging session, a candidate destination will only receive NSDraggingDestination messages if the pasteboard types for which it is registered matches a type that's represented by the image that's being dragged.

Although NSDraggingDestination is declared as a protocol, the NSView and NSWindow subclasses that you create to adopt the protocol need only implement those methods that are pertinent. (The NSView and NSWindow classes provide private implementations for all of the methods.) In addition, an NSWindow or its delegate may implement these methods; the delegate's implementation takes precedent.

The Sender of Destination Messages

Each of the NSDraggingDestination methods sports a single argument: sender, the object that invoked the method. Within its implementations of the NSDraggingDestination methods, the destination can send NSDraggingInfo messages to sender to get more information on the current dragging session.

The Order of Destination Messages

The six NSDraggingDestination methods are invoked in a distinct order:

. As the image is dragged into the destination's boundaries, the destination is sent a draggingEntered: message.

. While the image remains within the destination, a series of draggingUpdated: messages are sent.

. If the image is dragged out of the destination, draggingExited: is sent and the sequence of NSDraggingDestination messages stops. If it re-enters, the sequence begins again (with a new draggingEntered: message).

. When the image is released, it either slides back to its source (and breaks the sequence) or a prepareForDragOperation: message is sent to the destination, depending on the value that was returned by the most recent invocation of draggingEntered: or draggingUpdated:.

. If the prepareForDragOperation: message returned YES, a performDragOperation: message is sent.

. Finally, if performDragOperation: returned YES, concludeDragOperation: is sent.

Before the Image is Released

- (NSDragOperation)draggingEntered:(id <NSDraggingInfo>)sender

Invoked when the dragged image enters the destination.

- (NSDragOperation)draggingUpdated:(id <NSDraggingInfo>)sender

Invoked periodically while the image is over the destination.

- (void)draggingExited:(id <NSDraggingInfo>)sender

Invoked when the dragged image exits the destination.

After the Image is Released

- (BOOL)prepareForDragOperation:(id <NSDraggingInfo>)sender

Invoked when the image is released.

- (BOOL)performDragOperation:(id <NSDraggingInfo>)sender

Gives the destination an opportunity to perform the dragging operation.

- (void)concludeDragOperation:(id <NSDraggingInfo>)sender

Invoked when the dragging operation is complete.