Mac Developer Library

Developer

AppKit Framework Reference NSDraggingSession Class Reference

Options
Deployment Target:

On This Page
Language:

NSDraggingSession

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.7 and later.

The NSDraggingSession class encompases a drag and drop action and allows modification of the drag while in progress.

You start a new dragging session by calling the NSView method beginDraggingSessionWithItems:event:source: method. This method immediately returns and you can further modify the properties of the dragging session. The actual drag begins at the next turn of the run loop.

  • Returns the pasteboard object that contains the data being dragged. (read-only)

    Declaration

    Swift

    var draggingPasteboard: NSPasteboard! { get }

    Objective-C

    @property(readonly) NSPasteboard *draggingPasteboard

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Controls whether the dragging image animates back to its starting point on a cancelled or failed drag.

    Declaration

    Swift

    var animatesToStartingPositionsOnCancelOrFail: Bool

    Objective-C

    @property BOOL animatesToStartingPositionsOnCancelOrFail

    Discussion

    This property should be set immediately after creating the dragging session.

    The default value is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Controls the dragging formation when the drag is not over the source or a valid destination.

    Declaration

    Swift

    var draggingFormation: NSDraggingFormation

    Objective-C

    @property NSDraggingFormation draggingFormation

    Discussion

    Setting this value causes the dragging formation to change immediately, provided a valid destination has not overriden the behavior. If the dragging session hasn't started yet, the dragging items will animate into formation immediately upon start. It is highly recommended to never change the formation when starting a drag.

    The default value is NSDraggingFormationNone.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns a number that uniquely identifies the dragging session. (read-only)

    Declaration

    Swift

    var draggingSequenceNumber: Int { get }

    Objective-C

    @property(readonly) NSInteger draggingSequenceNumber

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Enumerates through each dragging item.

    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)

  • The current cursor location of the drag in screen coordinates. (read-only)

    Declaration

    Swift

    var draggingLocation: NSPoint { get }

    Objective-C

    @property(readonly) NSPoint draggingLocation

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The following constants specify the enumeration options used in the enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: method.

    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

      Specifies that the Block enumeration should be concurrent.

      The order of invocation is nondeterministic and undefined; this flag is a hint and may be ignored by the implementation under some circumstances; the code of the Block must be safe against concurrent invocation.

      Available in OS X v10.7 and later.

    • ClearNonenumeratedImages

      NSDraggingItemEnumerationClearNonenumeratedImages

      When the following option is set, the Application Kit will automatically set the imageComponentProvider to nil for all dragging items that do not meet the classes/searchOptions criteria of the method. Effectively, this hides the drag image for invalid 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.