Mac Developer Library

Developer

AppKit Framework Reference NSDraggingInfo Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSDraggingInfo

The NSDraggingInfo protocol declares methods that supply information about a dragging session.

NSDraggingInfo protocol methods are designed to be invoked from within a class’s implementation of NSDraggingDestination protocol methods. The Application Kit automatically passes an object that conforms to the NSDraggingInfo protocol as the argument to each of the methods defined by NSDraggingDestination. NSDraggingInfo messages should be sent to this object; you never need to create a class that implements the NSDraggingInfo protocol.

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns the pasteboard object that holds the data being dragged.

    Declaration

    Swift

    func draggingPasteboard() -> NSPasteboard!

    Objective-C

    - (NSPasteboard *)draggingPasteboard

    Return Value

    The pasteboard object that holds the data being dragged.

    Discussion

    The dragging operation that is ultimately performed utilizes this pasteboard data and not the image returned by the draggedImage method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a number that uniquely identifies the dragging session.

    Declaration

    Swift

    func draggingSequenceNumber() -> Int

    Objective-C

    - (NSInteger)draggingSequenceNumber

    Return Value

    A number that uniquely identifies the dragging session.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the source, or owner, of the dragged data.

    Declaration

    Swift

    func draggingSource() -> AnyObject?

    Objective-C

    - (id)draggingSource

    Return Value

    The source, or owner, of the dragged data.

    Discussion

    This method returns nil if the source is not in the same application as the destination. The dragging source implements methods from the NSDraggingSource protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the dragging operation mask of the dragging source.

    Declaration

    Swift

    func draggingSourceOperationMask() -> NSDragOperation

    Objective-C

    - (NSDragOperation)draggingSourceOperationMask

    Return Value

    The dragging operation mask, which is declared by the dragging source through the NSDraggingSource draggingSession:sourceOperationMaskForDraggingContext: method (preferred) or the NSDraggingSourcedraggingSourceOperationMaskForLocal: method. If the source does not permit any dragging operations, this method should return NSDragOperationNone.

    Discussion

    If the source permits dragging operations, the elements in the mask are one or more of the constants described in “Obtaining Information About the Dragging Session”, combined using the C bitwise OR operator.

    If the user is holding down a modifier key during the dragging session and the source does not prohibit modifier keys from affecting the drag operation (through its ignoreModifierKeysWhileDragging method), then the operating system combines the dragging operation value that corresponds to the modifier key (see the descriptions below) with the source’s mask using the C bitwise AND operator.

    The modifier keys are associated with the dragging operation options shown below:

    Modifier Key

    Dragging Operation

    Control

    NSDragOperationLink

    Option

    NSDragOperationCopy

    Command

    NSDragOperationGeneric

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current location of the mouse pointer in the base coordinate system of the destination object’s window.

    Declaration

    Swift

    func draggingLocation() -> NSPoint

    Objective-C

    - (NSPoint)draggingLocation

    Return Value

    The current location of the mouse pointer in the base coordinate system of the destination object’s window.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the destination window for the dragging operation.

    Declaration

    Swift

    func draggingDestinationWindow() -> NSWindow!

    Objective-C

    - (NSWindow *)draggingDestinationWindow

    Return Value

    The destination window for the dragging operation.

    Discussion

    Either this window is the destination itself, or it contains the view object that is the destination.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the drop location for promised files and returns the names of the files that the receiver promises to create there.

    Declaration

    Swift

    func namesOfPromisedFilesDroppedAtDestination(_ dropDestination: NSURL) -> [AnyObject]!

    Objective-C

    - (NSArray *)namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination

    Parameters

    dropDestination

    A URL object specifying the drop location for promised files.

    Return Value

    An array of file names, which are not full paths.

    Discussion

    Drag destinations should invoke this method within their performDragOperation: method. The source may or may not have created the files by the time this method returns.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Specifies the number of valid items for a drop operation. (required)

    Declaration

    Swift

    var numberOfValidItemsForDrop: Int { get set }

    Objective-C

    @property NSInteger numberOfValidItemsForDrop

    Discussion

    During draggingEntered: or draggingUpdated:, you are responsible for returning the drag operation. In some cases, you may accept some, but not all items on the dragging pasteboard. (For example, your application may only accept image files.)

    If you only accept some of the items, set this property to the number of items accepted so the drag manager can update the drag count badge.

    When updateDraggingItemsForDrag: is called, you should set the image of non-valid dragging items to nil. If none of the drag items are valid then you should not updateItems:, simply return NSDragOperationNone from your implementation of draggingEntered: and, or draggingUpdated: and do not modify any drag item properties.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the image being dragged.

    Declaration

    Swift

    func draggedImage() -> NSImage?

    Objective-C

    - (NSImage *)draggedImage

    Return Value

    The image being dragged.

    Discussion

    This image object visually represents the data put on the pasteboard during the drag operation; however, it is the pasteboard data and not this image that is ultimately utilized in the dragging operation.

    This method returns non-nil for a local drag, but nil for a cross-process drag. With the new multi-image dragging capabilities, a cross-process destination may participate and change the drag image. But it still cannot get the current drag image.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current location of the dragged image’s origin.

    Declaration

    Swift

    func draggedImageLocation() -> NSPoint

    Objective-C

    - (NSPoint)draggedImageLocation

    Return Value

    The dragged image's origin, in the base coordinate system of the destination object’s window.

    Discussion

    The image moves along with the mouse pointer (the position of which is given by draggingLocation) but may be positioned at some offset.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Slides the image to a specified location.

    Declaration

    Swift

    func slideDraggedImageTo(_ aPoint: NSPoint)

    Objective-C

    - (void)slideDraggedImageTo:(NSPoint)aPoint

    Parameters

    aPoint

    A point that specifies a location in the screen coordinate system.

    Discussion

    This method can be used to adjust the location to which the dragged image will slide back if the drag is rejected.

    It should only be invoked from within the destination’s implementation of prepareForDragOperation:, and will only have effect if the destination rejects the drag.

    This method is invoked after the user has released the image but before it is removed from the screen.

    Special Considerations

    This method has been available since OS X v 10.0, however it was not implemented until OS X v 10.5. Previous to that version, it did nothing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns whether the dragging formation animates while the drag is over this destination. (required)

    Declaration

    Swift

    var animatesToDestination: Bool { get set }

    Objective-C

    @property BOOL animatesToDestination

    Discussion

    During the conclusion of an accepted drag, if this property is set to YEStrue, the drag manager will animate each dragging image to their NSDraggingFormationNone locations. Otherwise, the drag images are removed without any animation.

    This property is inspected between prepareForDragOperation: and performDragOperation:. You should enumerate through the dragging items during performDragOperation: to set the item’s draggingFrame to the correct destinations.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the dragging formation while the drag is over this destination. (required)

    Declaration

    Swift

    var draggingFormation: NSDraggingFormation { get set }

    Objective-C

    @property NSDraggingFormation draggingFormation

    Discussion

    Set this property to change the formation of the drag items. This is generally done during the updateDraggingItemsForDrag: method or whenever you enumerate the dragging items.

    The default value is the current drag formation.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Enumerates through each dragging item. (required)

    Declaration

    Swift

    func enumerateDraggingItemsWithOptions(_ enumOpts: NSDraggingItemEnumerationOptions, forView view: NSView, classes classArray: [AnyObject], searchOptions searchOptions: [NSObject : AnyObject], usingBlock block: (NSDraggingItem!, Int, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateDraggingItemsWithOptions:(NSDraggingItemEnumerationOptions)enumOpts forView:(NSView *)view classes:(NSArray *)classArray searchOptions:(NSDictionary *)searchOptions usingBlock:(void (^)(NSDraggingItem *draggingItem, NSInteger idx, BOOL *stop))block

    Parameters

    enumOpts

    The enumeration options. See NSDraggingItemEnumerationOptions for the supported values.

    view

    The view used as the base coordinate system for the NSDraggingItem instances.

    classArray

    An array of class objects.

    The classes should appear in the array in the order the preferred order of representation. Classes in the array must conform to the NSPasteboardReading Protocol Reference.

    searchOptions

    A dictionary that specifies options to refine the search for pasteboard items, for example to restrict the search to file URLs with particular content types. For valid dictionary keys, see Pasteboard_Reading_Options.

    block

    The block executed for the enumeration.

    The block takes three arguments:

    draggingItem

    A reference to the dragging item. The draggingFrame of the dragging item is in the coordinate space of the view specified in by view. A view value of nil means the screen coordinate space.

    idx

    The index of the element in the classes.

    stop

    A reference to a Boolean value that the block can use to stop the enumeration by setting *stop to YEStrue; it should not touch *stop otherwise.

    Discussion

    Classes in the provided array must implement the NSPasteboardReading protocol. Cocoa classes that implement this protocol include NSImage, NSString, NSURL, NSColor, NSAttributedString, and NSPasteboardItem. For every item on the pasteboard, each class in the provided array will be queried for the types it can read using readableTypesForPasteboard:. An instance is created of the first class found in the provided array whose readable types match a conforming type contained in that pasteboard item. Any instances that could be created from pasteboard item data is returned to the caller. Additional options, such as restricting the search to file URLs with particular content types, can be specified with the options dictionary. Only objects of the requested classes are returned. You can always ensure to receive one object per item on the pasteboard by including the NSPasteboardItem class in the array of classes.

    This method enumerates the items on the dragging pasteboard associated with this dragging info, as well as all the additional data the dragging info knows about. The pasteboard data and the additional data is represented as one logical unit, an NSDraggingItem instance.

    For every item on the pasteboard, each class in classArray will be queried for the types it can read using readableTypesForPasteboard:. An instance will be created of the first class found in the provided array whose readable types match a conforming type contained in that pasteboard item. If an instance is created from the pasteboard item data, it is placed into an NSDraggingItem along with the dragging properties of that item such as the dragging image. The NSDraggingItem instance is then passed as a parameter to the provided block.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    – readObjectsForClasses:options: (NSPasteboard Class)

  • These constants are used by draggingSourceOperationMask.

    Declaration

    Swift

    struct NSDragOperation : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var None: NSDragOperation { get } static var Copy: NSDragOperation { get } static var Link: NSDragOperation { get } static var Generic: NSDragOperation { get } static var Private: NSDragOperation { get } static var Move: NSDragOperation { get } static var Delete: NSDragOperation { get } static var Every: NSDragOperation { get } static var All_Obsolete: NSDragOperation { get } static var All: NSDragOperation { get } }

    Objective-C

    enum { NSDragOperationNone = 0, NSDragOperationCopy = 1, NSDragOperationLink = 2, NSDragOperationGeneric = 4, NSDragOperationPrivate = 8, NSDragOperationAll_Obsolete = 15, NSDragOperationMove = 16, NSDragOperationDelete = 32, NSDragOperationEvery = NSUIntegerMax }; typedef NSUInteger NSDragOperation;

    Constants

    • Copy

      NSDragOperationCopy

      The data represented by the image can be copied.

      Available in OS X v10.0 and later.

    • Link

      NSDragOperationLink

      The data can be shared.

      Available in OS X v10.0 and later.

    • Generic

      NSDragOperationGeneric

      The operation can be defined by the destination.

      Available in OS X v10.0 and later.

    • Private

      NSDragOperationPrivate

      The operation is negotiated privately between the source and the destination.

      Available in OS X v10.0 and later.

    • All_Obsolete

      NSDragOperationAll_Obsolete

      The NSDragOperationAll constant is deprecated. Use NSDragOperationEvery instead.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

    • Move

      NSDragOperationMove

      The data can be moved.

      Available in OS X v10.0 and later.

    • Delete

      NSDragOperationDelete

      The data can be deleted.

      Available in OS X v10.0 and later.

    • Every

      NSDragOperationEvery

      All of the above.

      Available in OS X v10.0 and later.

    • None

      NSDragOperationNone

      No drag operations are allowed.

      Available in OS X v10.0 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • These constants specify the enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: options for the options parameter.

    Declaration

    Swift

    struct NSDraggingItemEnumerationOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Concurrent: NSDraggingItemEnumerationOptions { get } static var ClearNonenumeratedImages: NSDraggingItemEnumerationOptions { get } }

    Objective-C

    enum { NSDraggingItemEnumerationConcurrent = NSEnumerationConcurrent, NSDraggingItemEnumerationClearNonenumeratedImages = (1UL << 16), }; typedef NSUInteger NSDraggingItemEnumerationOptions;

    Constants

    • Concurrent

      NSDraggingItemEnumerationConcurrent

      Dragging item enumeration occurs concurrently.

      Available in OS X v10.7 and later.

    • ClearNonenumeratedImages

      NSDraggingItemEnumerationClearNonenumeratedImages

      When the following option is set, the imageComponentsProvider is automatically set to nil for all dragging items that do not meet the classes and search options criteria. Effectively, this hides the drag image for non-valid items for this destination.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • These constants control the visual format of multiple items being dragged.

    Declaration

    Swift

    enum NSDraggingFormation : Int { case Default case None case Pile case List case Stack }

    Objective-C

    enum { NSDraggingFormationDefault = 0, NSDraggingFormationNone, NSDraggingFormationPile, NSDraggingFormationList, NSDraggingFormationStack }; typedef NSInteger NSDraggingFormation;

    Constants

    • Default

      NSDraggingFormationDefault

      The system determined formation.

      Available in OS X v10.7 and later.

    • None

      NSDraggingFormationNone

      Drag images maintain their set positions relative to each other/

      Available in OS X v10.7 and later.

    • Pile

      NSDraggingFormationPile

      Drag images are placed on top of each other with random rotations.

      Available in OS X v10.7 and later.

    • List

      NSDraggingFormationList

      Drag images are laid out vertically, non-overlapping with the left edges aligned.

      Available in OS X v10.7 and later.

    • Stack

      NSDraggingFormationStack

      Drag images are laid out overlapping diagonally.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • These parameters specify whether a drag terminates within or outside the application.

    Declaration

    Swift

    enum NSDraggingContext : Int { case OutsideApplication case WithinApplication }

    Objective-C

    enum { NSDraggingContextOutsideApplication = 0, NSDraggingContextWithinApplication }; typedef NSInteger NSDraggingContext;

    Constants

    • OutsideApplication

      NSDraggingContextOutsideApplication

      The dragging terminates outside the application.

      Available in OS X v10.7 and later.

    • WithinApplication

      NSDraggingContextWithinApplication

      The dragging terminates within the application.

      Available in OS X v10.7 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Specifies that all drag operations are supported.

    The NSDragOperationAll constant has been deprecated. Use NSDragOperationEvery instead.

    Declaration

    Objective-C

    #define NSDragOperationAll NSDragOperationAll_Obsolete

    Constants

    • NSDragOperationAll

      NSDragOperationAll

      Use NSDragOperationEvery instead.

      Available in OS X v10.0 through OS X v10.9.