Mac Developer Library

Developer

AppKit Framework Reference NSDraggingDestination Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSDraggingDestination

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.7 and later.

The NSDraggingDestination protocol 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.

In OS X v10.7 and later NSDraggingDestination is a formal protocol with an updated interface. The OS X v10.6 behavior has been retained, but will be dropped in a future version of the operating system. The methods that are to be deprecated are marked as such.

  • Invoked when the dragged image enters destination bounds or frame; delegate returns dragging operation to perform.

    Declaration

    Swift

    optional func draggingEntered(_ sender: NSDraggingInfo) -> NSDragOperation

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Return Value

    One (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is the value returned by the previous draggingEntered: message.

    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.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Asks the destination object whether it wants to receive periodic draggingUpdated: messages.

    Declaration

    Swift

    optional func wantsPeriodicDraggingUpdates() -> Bool

    Objective-C

    - (BOOL)wantsPeriodicDraggingUpdates

    Return Value

    YEStrue if the destination wants to receive periodic draggingUpdated: messages, NOfalse otherwise.

    Discussion

    If the destination returns NOfalse, 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Invoked periodically as the image is held within the destination area, allowing modification of the dragging operation or mouse-pointer position.

    Declaration

    Swift

    optional func draggingUpdated(_ sender: NSDraggingInfo) -> NSDragOperation

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Return Value

    One (and only one) of the dragging operation constants described in NSDragOperation in the NSDraggingInfo reference. The default return value (if this method is not implemented by the destination) is the value returned by the previous draggingEntered: message.

    Discussion

    For this to be invoked, the destination must have 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.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

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

    Declaration

    Swift

    optional func draggingEnded(_ sender: NSDraggingInfo?)

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Discussion

    This method might be used by a destination doing auto-expansion in order to collapse any auto-expands.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • 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).

    Declaration

    Swift

    optional func draggingExited(_ sender: NSDraggingInfo?)

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Invoked when the image is released, allowing the receiver to agree to or refuse drag operation.

    Declaration

    Swift

    optional func prepareForDragOperation(_ sender: NSDraggingInfo) -> Bool

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Return Value

    YEStrue if the receiver agrees to perform the drag operation and NOfalse if not.

    Discussion

    This method is invoked only if the most recent draggingEntered: or draggingUpdated: message returned an acceptable drag-operation value.

    If you want the drag items to animate from their current location on screen to their final location in your view, set the sender object’s animatesToDestination property to YEStrue in your implementation of this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Invoked after the released image has been removed from the screen, signaling the receiver to import the pasteboard data.

    Declaration

    Swift

    optional func performDragOperation(_ sender: NSDraggingInfo) -> Bool

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Return Value

    If the destination accepts the data, it returns YEStrue; otherwise it returns NOfalse. The default is to return NOfalse.

    Discussion

    For this method to be invoked, the previous prepareForDragOperation: message must have returned YEStrue. The destination should implement this method to do the real work of importing the pasteboard data represented by the image.

    If the sender object’s animatesToDestination was set to YEStrue in prepareForDragOperation:, then setup any animation to arrange space for the drag items to animate to. Also at this time, enumerate through the dragging items to set their destination frames and destination images.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Invoked when the dragging operation is complete, signaling the receiver to perform any necessary clean-up.

    Declaration

    Swift

    optional func concludeDragOperation(_ sender: NSDraggingInfo?)

    Objective-C

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

    Parameters

    sender

    The object sending the message; use it to get details about the dragging operation.

    Discussion

    For this method to be invoked, the previous performDragOperation: must have returned YEStrue.

    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.

    If the sender object’s animatesToDestination property was set to YEStrue in prepareForDragOperation:, then the drag image is still visible. At this point you should draw the final visual representation in the view. When this method returns, the drag image is removed form the screen. If your final visual representation matches the visual representation in the drag, this is a seamless transition.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.7.

  • Invoked when the dragging images should be changed.

    Declaration

    Swift

    optional func updateDraggingItemsForDrag(_ sender: NSDraggingInfo?)

    Objective-C

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

    Parameters

    sender

    The object sending the message; use this object to get details about the dragging operation.

    Discussion

    While a destination may change the dragging images at any time, it is recommended to wait until this method is called before updating the dragging images.

    This allows the system to delay changing the dragging images until it is likely that the user will drop on this destination. Otherwise, the dragging images will change too often during the drag which would be distracting to the user.

    During enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: you may set non-acceptable drag items images to nil to hide them or use the enumeration option of NSDraggingItemEnumerationClearNonenumeratedImages If there are items that you hide, then after enumeration, you need to set the numberOfValidItemsForDrop to the number of non-hidden drag items. However, if the valid item count is 0, then it is better to return NSDragOperationNone from your implementation of draggingEntered: and, or draggingUpdated: instead of hiding all drag items during enumeration.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.