Next Page >

Hide TOC

NSDraggingInfo Protocol Reference

Framework	/System/Library/Frameworks/AppKit.framework
Availability	Available in Mac OS X v10.0 and later.
Companion guide	Drag and Drop Programming Topics for Cocoa
Declared in	NSDragging.h

Overview

The NSDraggingInfo protocol declares methods that supply information about a dragging session. NSDraggingInfo methods are designed to be invoked from within a class’s implementation of NSDraggingDestination informal 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

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.

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac 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 Mac 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 Mac 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 Mac 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 informal protocol.

Availability

Available in Mac 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 its draggingSourceOperationMaskForLocal: 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 NSDragOperation, 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 Mac OS X v10.0 and later.

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 Mac OS X v10.2 and later.

Declared In

NSDragging.h

slideDraggedImageTo:

Slides the image to a specified location. (Deprecated. Deprecated as of Mac OS X v10.5. There is no alternative method.)

- (void)slideDraggedImageTo:(NSPoint)aPoint

Parameters

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

Discussion

Calling this method has no effect on the image.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

Constants

NSDragOperation

Type representing drag operations.

typedef unsigned int NSDragOperation;

Discussion

See Dragging operations for values.

Availability

Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

Dragging operations

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   = UINT_MAX
};