- Package:
- com.apple.yellow.application
The NSDraggingDestination informal 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.
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 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 window or view object, that instigated the dragging session.
The image that's dragged in an image-dragging session is simply an image that represents data that resides on the pasteboard. Although a dragging destination can access the image (through the draggedImage method described in the NSDraggingInfo protocol), its primary concern is with the pasteboard data that the image represents-the dragging operation that a destination ultimately performs is on the pasteboard data, not on the image itself.
Dragging is a visual phenomenon. To be an image-dragging destination, an object must represent a portion of screen real estate; thus, only window and view objects can be destinations. Furthermore, you must register the pasteboard types that the object will accept by sending the object a registerForDraggedTypes message, defined in both NSWindow and NSView. During a dragging session, a candidate destination only receives NSDraggingDestination messages if the destination is registered for a pasteboard type that matches the type of the pasteboard data being dragged. See the NSPasteboard class specification for more information about pasteboard types.
Although NSDraggingDestination is declared as an informal protocol, the NSWindow and NSView subclasses you create to adopt the protocol need only implement those methods that are pertinent. (The NSWindow and NSView classes provide private implementations for all of the methods.) Either a window object or its delegate may implement these methods; however, the delegate's implementation takes precedence if there are implementations in both places.
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 protocol messages to sender to get more information on the current dragging session.
The six NSDraggingDestination methods are invoked in a distinct order:
- Before the image is released
- draggingEntered
- draggingUpdated
- draggingExited
- After the image is released
- prepareForDragOperation
- performDragOperation
- concludeDragOperation
public abstract void concludeDragOperaton(NSDraggingInfo sender)
public abstract int draggingEntered(NSDraggingInfo sender)
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 (accessible through the draggingSourceOperationMask method) and the dragging operations and pasteboard data types the destination itself supports. The returned value should be exactly one of the following:
Option | Meaning |
DragOperationCopy | The data represented by the image will be copied. |
DragOperationLink | The data will be shared. |
DragOperationGeneric | The operation will be defined by the destination. |
DragOperationPrivate | The operation is negotiated privately between the source and the destination. |
DragOperationAll | Combines all the above. |
If none of the operations is appropriate, this method should
return DragOperationNone
(this is
the default response if the method isn't implemented by the destination).
See Also: draggingUpdated, draggingExited, prepareForDragOperation
public abstract void draggingExited(NSDraggingInfo sender)
public abstract int draggingUpdated(NSDraggingInfo sender)
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.
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
public abstract boolean performDragOperation(NSDraggingInfo sender)
See Also: concludeDragOperation
public abstract boolean prepareForDragOperation(NSDraggingInfo sender)
See Also: performDragOperation