NSDraggingInfo Protocol Reference

Conforms to
NSObject
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Drag and Drop Programming Topics
Declared in
NSDragging.h
Related sample code

Overview

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.

Tasks

Obtaining Information About the Dragging Session

Getting Image Information

Sliding the Image

Enumerate Dragged Items

Properties

animatesToDestination

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

@property BOOL animatesToDestination
Discussion

During the conclusion of an accepted drag, if this property is set to YES, 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.

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

draggingFormation

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

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

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

numberOfValidItemsForDrop

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

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

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

Instance Methods

draggedImage

Returns the image being dragged.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDragging.h

draggedImageLocation

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSDragging.h

draggingDestinationWindow

Returns the destination window for the dragging operation.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

draggingLocation

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

- (NSPoint)draggingLocation
Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

draggingPasteboard

Returns the pasteboard object that holds the data being dragged.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

draggingSequenceNumber

Returns a number that uniquely identifies the dragging session.

- (NSInteger)draggingSequenceNumber
Return Value

A number that uniquely identifies the dragging session.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

draggingSource

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

draggingSourceOperationMask

Returns the dragging operation mask of the dragging source.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock:

Enumerates through each dragging item. (required)

- (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
Declared In
NSDragging.h

namesOfPromisedFilesDroppedAtDestination:

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

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

Availability
  • Available in OS X v10.2 and later.
Declared In
NSDragging.h

slideDraggedImageTo:

Slides the image to a specified location.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSDragging.h

Constants

NSDragOperation

These constants are used by draggingSourceOperationMask.

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

The data represented by the image can be copied.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationLink

The data can be shared.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationGeneric

The operation can be defined by the destination.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationPrivate

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

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationAll_Obsolete

The NSDragOperationAll constant is deprecated. Use NSDragOperationEvery instead.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationMove

The data can be moved.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationDelete

The data can be deleted.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationEvery

All of the above.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDragOperationNone

No drag operations are allowed.

Available in OS X v10.0 and later.

Declared in NSDragging.h.

NSDraggingItemEnumerationOptions

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

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

Dragging item enumeration occurs concurrently.

Available in OS X v10.7 and later.

Declared in NSDragging.h.

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.

Declared in NSDragging.h.

NSDraggingFormation

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

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

The system determined formation.

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingFormationNone

Drag images maintain their set positions relative to each other/

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingFormationPile

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

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingFormationList

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

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingFormationStack

Drag images are laid out overlapping diagonally.

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingContext

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

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

The dragging terminates outside the application.

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDraggingContextWithinApplication

The dragging terminates within the application.

Available in OS X v10.7 and later.

Declared in NSDragging.h.

NSDragOperationAll Deprecation

Specifies that all drag operations are supported. (Deprecated. The NSDragOperationAll constant has been deprecated. Use NSDragOperationEvery instead.)

#define NSDragOperationAll NSDragOperationAll_Obsolete
Constants
NSDragOperationAll

Use NSDragOperationEvery instead.

Available in OS X v10.0 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...