NSDraggingSession Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.7 and later.
Declared in
NSDragging.h
NSDraggingSession.h
Related sample code

Overview

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.

Tasks

Dragging Pasteboard

Dragging Visual Representation

Identifying the Dragging Session

Enumerating Dragging Items

Dragging Session Location

Dragging Item Location

Properties

animatesToStartingPositionsOnCancelOrFail

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

@property BOOL animatesToStartingPositionsOnCancelOrFail
Discussion

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

The default value is YES.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSDraggingSession.h

draggingFormation

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

@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.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSDraggingSession.h

draggingLeaderIndex

The index of the dragging item under the cursor.

@property NSInteger draggingLeaderIndex
Discussion

The index is to an element in the array passed as the first parameter to the NSView method beginDraggingSessionWithItems:event:source:.

The default is the NSDraggingItem closest to the location field in the event parameter that was passed to the beginDraggingSessionWithItems:event:source: method.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSDraggingSession.h

draggingLocation

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

@property(readonly) NSPoint draggingLocation
Availability
  • Available in OS X v10.7 and later.
Declared In
NSDraggingSession.h

draggingPasteboard

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

@property(readonly) NSPasteboard *draggingPasteboard
Availability
  • Available in OS X v10.7 and later.
Declared In
NSDraggingSession.h

draggingSequenceNumber

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

@property(readonly) NSInteger draggingSequenceNumber
Availability
  • Available in OS X v10.7 and later.
Declared In
NSDraggingSession.h

Instance Methods

enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock:

Enumerates through each dragging item.

- (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.

Note: The draggingItem object is only valid for this iteration of the enumeration block. Never store this draggingItem or try to change it outside of Block iteration. It is very easy to reference draggingItem inside an imageComponentsProvider block. This is bad for two reasons: by the time the imageComponentsProvider Block is called, the enumeration Block is out of scope and the draggingItem is no longer valid and it creates a retain cycle draggingItem retains imageComponentsProvider which retains draggingItem causing a memory leak. Instead, assign draggingItem.item to an object pointer outside of the imageComponentsProvider Block definition and use the object pointer inside the imageComponentsProvider block definition.

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 YES; 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.

Availability
  • Available in OS X v10.7 and later.
See Also
Related Sample Code
Declared In
NSDraggingSession.h

Constants

Dragging Enumeration Options

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

enum {
   NSDraggingItemEnumerationConcurrent            = NSEnumerationConcurrent,
   NSDraggingItemEnumerationClearNonenumeratedImages     = (1UL << 16),
};
typedef NSUInteger NSDraggingItemEnumerationOptions;
Constants
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.

Declared in NSDragging.h.

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.

Declared in NSDragging.h.



© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-06)

Did this document help you? Yes It's good, but... Not helpful...