Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
| NXDraggingDestination |
| Adopted By: | no NEXTSTEP classes | |
| Declared In: | appkit/drag.h |
| Protocol Description |
| The NXDraggingDestination protocol declares methods that the destination (or recipient) of a dragged image must implement. The destination automatically receives NXDraggingDestination 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 Window or View, that instigated the dragging session.
The Dragged Image The image that's dragged in an image-dragging session is an NXImage object that represents data that's put on the pasteboard. Although a dragging destination can access the NXImage (through a method described in the NXDraggingInfo protocol), its primary concern is with the pasteboard data that the NXImage represents--the 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 Windows and Views can be destinations. Furthermore, you must announce the destination-candidacy of a Window or View by sending it a registerForDraggedTypes:count: 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 NXDraggingDestination messages if the pasteboard types for which it is registered matches a type that's represented by the image that's being dragged. Although NXDraggingDestination is declared as a protocol, the Views and Window subclasses that you create to adopt the protocol need only implement those methods that are pertinent. (The View and Window classes provide private implementations for all of the methods.) In addition, a Window or its delegate may implement these methods; the delegate's implementation takes precedent.
The Sender of Destination Messages Each of the NXDraggingDestination methods sports a single argument, sender, the object that invoked the method. Within its implementations of the NXDraggingDestination methods, the destination can send NXDraggingInfo messages to sender to get more information on the current dragging session.
The Order of Destination Messages The six NXDraggingDestination 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 NXDraggingDestination 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. |
| Method Types |
| Before the image is released |  draggingEntered: |
| draggingUpdated: draggingExited: |
| After the image is released | prepareForDragOperation: |
| performDragOperation: concludeDragOperation: |
| Instance Methods |
| concludeDragOperation: |
| concludeDragOperation:(id <NXDraggingInfo>)sender |
| Invoked when the dragging operation is complete (but only if the previous performDragOperation: returned YES). The destination implements this method to perform any tidying up that it needs to do. This is the last message that's sent from sender to the destination during a dragging session. The return value is ignored. |
| draggingEntered: |
| (NXDragOperation)draggingEntered:(id <NXDraggingInfo>)sender |
| Invoked when the dragged image enters the destination. Specifically, the message is sent when the hot spot on the cursor that's dragging the image enters any portion of the destination's bounds rectangle (if it's a View) or its frame rectangle (if it's a Window).
The method must return a single NXDragOperation value that indicates which dragging operation the destination will perform when the image is released. It should be one of the operations specified in the value returned by sender's draggingSourceOperationMask method. If none of the operations are appropriate, this method should return NX_DragOperationNone (this is the default response if the method isn't implemented by the destination). The dragging operation constants are listed in the "Types and Constants" section of this chapter See also: |
| draggingExited: |
| draggingExited:(id <NXDraggingInfo>)sender |
| Invoked when the dragged image exits the destination (following, inversely, the geometric specification given in the description of draggingEntered:). The return value is ignored. |
| draggingUpdated: |
| (NXDragOperation)draggingUpdated:(id <NXDraggingInfo>)sender |
| Invoked periodically as the image is poised within the destination. The messages continue until the image is either released or exits. The return value follows the same rules as that for the draggingEntered: method. The default return value (if this method isn't implemented by the destination) is the value returned by the previous draggingEntered: message.
Only one destination at at time receives a sequence of draggingUpdated: messages. For example, if the cursor 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 exits. See also: |
| performDragOperation: |
| (BOOL)performDragOperation:(id <NXDraggingInfo>)sender |
| Invoked after the released image has been removed from the screen (but only if the previous prepareForDragOperation: message returned YES). The destination should implement this method to do the real work of importing the data represented by the image. If the destination accepts the data, it returns YES, otherwise it returns NO. The default (if the destination doesn't implement the method) is to return NO.
See also: |
| prepareForDragOperation: |
| (BOOL)prepareForDragOperation:(id <NXDraggingInfo>)sender |
| Invoked when the image is released (but only if the most recent draggingEntered: or draggingUpdated: message returned an acceptable drag-operation value). The method returns YES if it will perform the drag operation and NO if not.
See also: |