---

NSDraggingSource Protocol Reference

(informal protocol)

Overview

The NSDraggingSource informal protocol declares methods that are implemented by the source object in a dragging session. The dragging source is specified as an argument to the dragImage:at:offset:event:pasteboard:source:slideBack: message, sent to a window or view object to initiate the dragging session.

Of the methods declared below, only draggingSourceOperationMaskForLocal: must be implemented. The other methods are invoked only if the dragging source implements them. All methods are invoked automatically during a dragging session—you never send an NSDraggingSource message directly to an object.

Tasks

Specifying Dragging Options

• – draggingSourceOperationMaskForLocal:
• – ignoreModifierKeysWhileDragging

Responding to Messages During a Dragging Sessions

• – draggedImage:beganAt:
• – draggedImage:movedTo:
• – draggedImage:endedAt:deposited:
• – draggedImage:endedAt:operation:
• – namesOfPromisedFilesDroppedAtDestination:

Instance Methods

draggedImage:beganAt:

Gives the source object an opportunity to respond to the initiation of a dragging session.

- (void)draggedImage:(NSImage *)anImage beganAt:(NSPoint)aPoint

Parameters

anImage

The image of the dragged item.

aPoint

The origin of the image in screen coordinates.

Discussion

This method is invoked when anImage is displayed but before it starts following the mouse. For example, you might choose to have the source give a visual indication to the user that data is being dragged from the source.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – convertScreenToBase: (NSWindow)
• – convertBaseToScreen: (NSWindow)
• – convertPoint:fromView: (NSView)
• – convertPoint:toView: (NSView)

Declared In

NSDragging.h

draggedImage:endedAt:deposited:

Invoked after the dragging destination has been given a chance to operate on the data represented by the image, (Deprecated)

- (void)draggedImage:(NSImage *)anImage endedAt:(NSPoint)aPoint deposited:(BOOL)flag

Discussion

This method has been deprecated. Use draggedImage:endedAt:operation: instead.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

draggedImage:endedAt:operation:

Invoked after the dragging destination has been given a chance to operate on the data represented by the image,

- (void)draggedImage:(NSImage *)anImage endedAt:(NSPoint)aPoint operation:(NSDragOperation)operation

Parameters

anImage

The dragged image.

aPoint

The point locating the image’s origin in the screen coordinate system when it was released.

operation

An integer constant that indicates the operation performed by the destination.

Discussion

This method is invoked after the dragged image (anImage) has been released and the dragging destination has been given a chance to operate on the data it represents. This method provides the source object with an opportunity to respond to either a successful or a failed dragging session. For example, if you are moving data from one location to another, you could use this method to make the source data disappear from its previous location, if the dragging session is successful, or reset itself to its previous state, in the event of a failure.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

draggedImage:movedTo:

Informs the dragging source when a dragged image moves to a new screen coordinate.

- (void)draggedImage:(NSImage *)draggedImage movedTo:(NSPoint)screenPoint

Parameters

draggedImage

The dragged image.

screenPoint

The point specifying the new location of the image in screen coordinates.

Discussion

This message is similar to the dragging destination being sent draggingUpdated: messages.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

draggingSourceOperationMaskForLocal:

Returns an integer bit mask indicating the types of dragging operations the source object will allow to be performed on the dragged image's data.

- (NSDragOperation)draggingSourceOperationMaskForLocal:(BOOL)isLocal

Parameters

isLocal

YES indicates that the candidate destination object (the window or view over which the dragged image is currently poised) is in the same application as the source, while a NO value indicates that the destination object is in a different application.

Discussion

This method is the only NSDraggingSource method that must be implemented by the source object. It should return a mask, built by combining the allowed dragging operations listed in the “Constants” section of the NSDraggingInfo protocol reference, using the C bitwise OR operator. If the source does not permit any dragging operations, it should return NSDragOperationNone.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

ignoreModifierKeysWhileDragging

Sets whether the use of modifier keys should have an effect on the type of operation performed.

- (BOOL)ignoreModifierKeysWhileDragging

Discussion

If this method is not implemented or returns NO, the user can tailor the drag operation by holding down a modifier key during the drag. The dragging option that corresponds to the modifier key is combined with the source’s mask (as set with the draggingSourceOperationMaskForLocal: method) using the C bitwise AND operator. See the description for the draggingSourceOperationMask method in the NSDraggingInfo protocol specification for more information about dragging masks and modifier keys.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSDragging.h

namesOfPromisedFilesDroppedAtDestination:

Returns the names of the files that the receiver promises to create at a specified location.

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

Parameters

dropDestination

A URL object that identifies the location at which the promised files will be created.

Return Value

An array of the names of files (not full paths) that the receiver promises to create at dropDestination.

Discussion

This method is invoked when the drop has been accepted by the destination and the destination, in the case of another Cocoa application, invokes the NSDraggingInfo method namesOfPromisedFilesDroppedAtDestination:. For long operations, you can cache dropDestination and defer the creation of the files until the draggedImage:endedAt:operation: method to avoid blocking the destination application.

Availability

• Available in Mac OS X v10.2 and later.

Declared In

NSDragging.h

---