[TOC] [Prev] [Next] [Bottom]

NSDraggingSource

(informal protocol)

Category Of:
NSObject

Declared In:
AppKit/NSDragging.h

Description

The NSDraggingSource informal protocol declares methods that are implemented by the source object in a dragging session (see the NSDraggingDestination protocol for definitions of dragging terms). 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 four methods are invoked automatically during a dragging session-you never send an NSDraggingSource message directly to an object.


Method Types

Specifying dragging options
- draggingSourceOperationMaskForLocal:
- ignoreModifierKeysWhileDragging
Responding to dragging sessions
- draggedImage:beganAt:
- draggedImage:endedAt:deposited:

Instance Methods

draggedImage:beganAt:

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

Invoked when anImage is displayed but before it starts following the mouse. aPoint is the origin of the image in screen coordinates. This method provides the source object with an opportunity to respond to the initiation of a dragging session. For example, you might choose to have the source give a visual indication to the user that data is being dragged from the source.

See also: - convertScreenToBase: (NSWindow), - convertBaseToScreen: (NSWindow), - convertPoint:fromView: (NSView), - convertPoint:toView: (NSView)


draggedImage:endedAt:deposited:

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

Invoked after anImage has been released and the dragging destination has been given a chance to operate on the data it represents. aPoint is the location of the image's origin in the screen coordinate system when it was released. A YES value for flag indicates that the destination accepted the dragged data, while a NO value indicates that it was rejected.

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.

See also: - convertScreenToBase: (NSWindow), - convertBaseToScreen: (NSWindow), - convertPoint:fromView: (NSView), - convertPoint:toView: (NSView)


draggingSourceOperationMaskForLocal:

- (unsigned int)draggingSourceOperationMaskForLocal:(BOOL)flag

This is the only NSDraggingSource method that must be implemented by the source object. It should return a mask, built by combining the applicable constants listed below using the C bitwise OR operator. You should use this mask to indicate which types of dragging operations the source object will allow to be performed on the dragged image's data. A YES value for flag 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.

Option Meaning
NSDragOperationCopy The data represented by the image can be copied.
NSDragOperationLink The data can be shared.
NSDragOperationGeneric The operation can be defined by the destination.
NSDragOperationPrivate The operation is negotiated privately between the source and the destination.
NSDragOperationAll Combines all the above.

If the source does not permit any dragging operations, then it should return NSDragOperationNone.


ignoreModifierKeysWhileDragging

- (BOOL)ignoreModifierKeysWhileDragging

Sets whether the use of the modifier keys should have no effect on the type of operation performed. If this method is not implemented or returns NO, then 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.



[TOC] [Prev] [Next] [Bottom]

Copyright © 1997, Apple Computer, Inc. All rights reserved.