Next Page >

Hide TOC

Drag Manager Reference

Framework	Carbon/Carbon.h
Declared in	Drag.h

Overview

The Drag Manager facilitates dragging objects within the Macintosh user interface. The Drag Manager provides functions that handle the user interface for dragging an object from, within, or to one of your application’s windows. The Drag Manager can be used whenever an object is dragged within your application.

Use the Drag Manager if you want your users to be able to drag items within your own application’s windows or between those of your application and other applications. You can also use the Drag Manager to allow the user of your application to drag selections of your documents to the Finder to create "clippings" from your documents and to allow selections from other applications to be dragged directly into your documents.

Functions by Task

Installing and Removing Drag Handlers

Creating and Disposing of Drag References

Adding Drag Item Flavors

Providing Drag Callback Functions

Setting the Drag Image

Altering the Behavior of a Drag

Performing a Drag

Getting Drag Item Information

Getting and Setting the Drop Location

Getting Drag Status Information

Accessing Drag Actions

Highlighting a Drag

Drag Manager Utilities

Creating, Calling, and Deleting Universal Procedure Pointers

Functions

ChangeDragBehaviors

Changes the behavior of a drag.

OSErr ChangeDragBehaviors (
   DragRef theDrag,
   DragBehaviors inBehaviorsToSet,
   DragBehaviors inBehaviorsToClear
);

Parameters

theDrag: A drag reference.
inBehaviorsToSet: A value indicating the new behavior of the drag. See “Drag Behaviors” for a description of the values you can use in this parameter.
inBehaviorsToClear: A value indicating which existing behavior, if any, should be cleared. See “Drag Behaviors” for a description of the values you can use in this parameter.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

DisposeDrag

Disposes of a drag reference and its associated data.

OSErr DisposeDrag (
   DragRef theDrag
);

Parameters

theDrag: The drag reference of the drag object to dispose of. If the drag reference contains any drag item flavors, the memory associated with the drag item flavors is disposed of as well.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

You should call the DisposeDrag function after a drag has been performed using the TrackDrag function or if a drag reference was created but is no longer needed.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

DisposeDragInputUPP

Disposes of the universal procedure pointer (UPP) to a drag input callback.

void DisposeDragInputUPP (
   DragInputUPP userUPP
);

Parameters

userUPP: The UPP to dispose of.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

GetDragAllowableActions

Returns the actions that the drag receiver may take on the data within a drag.

OSStatus GetDragAllowableActions (
   DragRef theDrag,
   DragActions *outActions
);

Parameters

theDrag: The drag reference.
outActions: A pointer to a field that specifies, on return, the allowable drag actions. See “Drag Actions” for a description of the values that may be returned here.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

The drag actions returned by the GetDragAllowableActions function are not actually requirements; they are highly recommended suggestions for operations that the drag receiver may perform. The drag sender sets the recommended actions for a drag using the SetDragAllowableActions function. The drag actions returned by GetDragAllowableActions are always local to the caller’s process.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragAttributes

Gets the current set of drag attribute flags.

OSErr GetDragAttributes (
   DragRef theDrag,
   DragAttributes *flags
);

Parameters

theDrag: A drag reference.
flags: On return, a pointer to the drag attribute flags for the specified drag reference. See “Drag Attributes” for a description of the values that may be returned here.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

If the GetDragAttributes function is called during a drag, the current set of drag attributes is returned. If the GetDragAttributes function is called after a drag, the set of drag attributes that were set at drop time is returned.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragDropAction

Returns the action performed by the receiver of the drag.

OSStatus GetDragDropAction (
   DragRef theDrag,
   DragActions *outAction
);

Parameters

theDrag: The drag reference from which to retrieve the drop action.
outAction: A pointer to a field that, on return, specifies the action performed by the drag receiver. More than one action may be performed. See “Drag Actions” for a description of the values that may be returned here.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragItemBounds

Gets the bounding rectangle of a drag item.

OSErr GetDragItemBounds (
   DragRef theDrag,
   DragItemRef theItemRef,
   Rect *itemBounds
);

Parameters

theDrag: A drag reference.
theItemRef: The reference number of the drag item whose bounds you wish to obtain.
itemBounds: On return, a pointer to the bounding rectangle (relative to the current pinned mouse position) of the specified item in global coordinates.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

You can use the GetDragItemBounds function in your tracking or receive handlers to determine the current or dropped location of each item in the drag.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragModifiers

Gets the current set of keyboard modifiers.

OSErr GetDragModifiers (
   DragRef theDrag,
   SInt16 *modifiers,
   SInt16 *mouseDownModifiers,
   SInt16 *mouseUpModifiers
);

Parameters

theDrag: A drag reference.
modifiers: A pointer to a variable that, on return, contains the current keyboard modifiers. You may pass NULL if you wish to disregard this value. The value will be 0 if the drag has not been started.
mouseDownModifiers: A pointer to a variable that, on return, contains the keyboard modifiers at the mouseDown parameter time. You may pass NULL if you wish to disregard this value. The value will be 0 if the drag has not been started.
mouseUpModifiers: A pointer to a variable that, on return, contains the keyboard modifiers at the mouseUp parameter time. You may pass NULL if you wish to disregard this value. The value will be 0 if the drag has not been completed.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragMouse

Gets the current mouse and pinned mouse locations.

OSErr GetDragMouse (
   DragRef theDrag,
   Point *mouse,
   Point *globalPinnedMouse
);

Parameters

theDrag: A drag reference.
mouse: A pointer to a variable containing, on return, the current mouse location in global screen coordinates. You may pass NULL if you wish to ignore this value. The value will be (0, 0) if the drag is not yet used. After a drag completes, the drop location is returned.
globalPinnedMouse: A pointer to a variable containing, on return, the current pinned mouse location in global screen coordinates. You may pass NULL if you wish to ignore this value. The value will be (0, 0) if the drag is not yet used. After a drag completes, the drop location is returned.The pinned mouse location is the mouse location that is used to draw the drag region on the screen. The pinned mouse location is different from the mouse location when the cursor is being constrained in either dimension by a tracking handler.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

GetDragOrigin

Gets the mouseDown parameter location that started the given drag.

OSErr GetDragOrigin (
   DragRef theDrag,
   Point *globalInitialMouse
);

Parameters

theDrag: A drag reference.
globalInitialMouse: A pointer to a variable that contains, on return, the mouseDown parameter location that started the drag, in global coordinates. The mouseDown location is returned whether or not the drag has completed.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

InvokeDragInputUPP

Calls your drag input callback.

OSErr InvokeDragInputUPP (
   Point *mouse,
   SInt16 *modifiers,
   void *dragInputRefCon,
   DragRef theDrag,
   DragInputUPP userUPP
);

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

You should not need to use the function InvokeDragInputUPP, as the system calls your drag input callback for you.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

NewDrag

Creates a new drag reference for your application to use with the Drag Manager.

OSErr NewDrag (
   DragRef *theDrag
);

Parameters

theDrag: On return, a pointer to the newly created drag reference. This drag reference is required when adding drag item flavors and calling the TrackDrag function. Your installed drag handler functions receive this drag reference so they can call other Drag Manager functions.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

NewDragInputUPP

Creates a new universal procedure pointer (UPP) to a drag input callback.

DragInputUPP NewDragInputUPP (
   DragInputProcPtr userRoutine
);

Parameters

userRoutine: A pointer to your drag input callback.

Return Value

On return, a UPP to the drag input callback. See the description of the DragInputUPP data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

SetDragAllowableActions

Sets the actions that the drag receiver may take on the data within a drag.

OSStatus SetDragAllowableActions (
   DragRef theDrag,
   DragActions inActions,
   Boolean isLocal
);

Parameters

theDrag: The drag reference.
inActions: A field specifying the allowable actions for the drag. See “Drag Actions” for a description of the values you may use here.
isLocal: A Boolean value allowing the drag sender to specify whether the actions passed in the inActions parameter are allowable for a local receiver or for a remote receiver. Pass true in this parameter if the drag actions are for local receivers.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

The actions set by the drag sender using the SetDragAllowableActions function are not requirements; they are highly recommended suggestions for operations the drag receiver may perform. The caller may select whether these drag actions apply to a remote or local process with the inLocal parameter.

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

Drag.h

SetDragDropAction

Sets the action performed by the receiver of the drag.

OSStatus SetDragDropAction (
   DragRef theDrag,
   DragActions inAction
);

Parameters

theDrag: The drag reference for which to set the drop action.
inAction: The drop action performed. More than one action may be performed. See “Drag Actions” for a description of the values you may use here.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.1 and later.
Not available to 64-bit applications.

Declared In

Drag.h

SetDragImageWithCGImage

Associates a Core Graphics image with a drag reference.

OSStatus SetDragImageWithCGImage (
   DragRef inDrag,
   CGImageRef inCGImage,
   const HIPoint *inImageOffsetPt,
   DragImageFlags inImageFlags
);

Parameters

inDrag: The drag reference for which to display the image.
inCGImage: A reference to the image to display during the drag. The Drag Manager retains this image for the duration of the drag, so you may release the image immediately after calling SetDragImageWithCGImage.
inImageOffsetPt: A pointer to the offset from the mouse location to the upper left corner of the image, normally expressed in negative values. For example, an offset of (-30, -30) centers a 60 by 60 pixel image on the mouse. Note that this differs from the usage of the offset passed to the SetDragImage function.
inImageFlags: Flags controlling the appearance of the drag image. See “Drag Image Flags” for a description of the values you can use in this parameter.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

This function is called by the sender of a drag to set the image displayed to provide user feedback during the drag. You can call the SetDragImageWithCGImage function at any point during the drag to update the image.

Availability

Available in Mac OS X v10.2 and later.
Not available to 64-bit applications.

Declared In

Drag.h

SetDragInputProc

Sets the drag input function for the Drag Manager to use with a particular drag.

OSErr SetDragInputProc (
   DragRef theDrag,
   DragInputUPP inputProc,
   void *dragInputRefCon
);

Parameters

theDrag: The drag reference for which the drag input function will be set.
inputProc: The drag input function to be called by the Drag Manager whenever the Drag Manager requires the location of the mouse, the state of the mouse button, and the status of the modifier keys on the keyboard. The Drag Manager typically calls this function once per cycle through the Drag Manager’s main drag tracking loop.Your drag input function may either modify the current state of the mouse and keyboard to slightly alter dragging behavior or entirely replace the input data to drive the drag completely by itself. Details for how to write a drag input function are covered in the “Drag Manager Callbacks” section.
dragInputRefCon: A pointer to a reference constant that will be forwarded to your drag input function when it is called by the Drag Manager. Use this constant to pass any data you wish to forward to your drag input function.

Return Value

A result code. See “Drag Manager Result Codes.”

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

SetDragItemBounds

Sets the bounding rectangle of a drag item.

OSErr SetDragItemBounds (
   DragRef theDrag,
   DragItemRef theItemRef,
   const Rect *itemBounds
);

Parameters

theDrag: A drag reference.
theItemRef: The reference number of the drag item whose bounds you wish to set.
itemBounds: A pointer to the bounding rectangle to set for the specified drag item. This rectangle is specified in global coordinates relative to the mouse down position.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

Your application would normally call the SetDragItemBounds function on each drag item before starting a drag with the TrackDrag function.

If you do not set the bounds of an item, the rectangle returned by the GetDragItemBounds function is an empty rectangle centered under the pinned mouse location.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

SetDragMouse

Sets the current pinned mouse location.

OSErr SetDragMouse (
   DragRef theDrag,
   Point globalPinnedMouse
);

Parameters

theDrag: A drag reference.
globalPinnedMouse: The coordinates to which to set the pinned mouse location, in global screen coordinates. The pinned mouse location is used to draw the drag region on the screen.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

To constrain the mouse within one of your application’s windows, call the SetDragMouse function from within your tracking handler when you receive the kDragTrackingInWindow messages. The Drag Manager updates the position of the drag region on the screen after each time your tracking handlers are called.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

TrackDrag

Drags an item or collection of items from your application.

OSErr TrackDrag (
   DragRef theDrag,
   const EventRecord *theEvent,
   RgnHandle theRegion
);

Parameters

theDrag: A drag reference for performing the drag operation.
theEvent: A pointer to the mouseDown event record that your application received that resulted in starting a drag.
theRegion: A region that represents the item or items being dragged. Note that under normal circumstances, the drag region should only include the pixels that represent the outline of the items being dragged. The Drag Manager draws the region on the screen by calling the PaintRgn function (not the FrameRgn function).

Return Value

A result code. See “Drag Manager Result Codes.” Under some circumstances, TrackDrag may fail with a procNotFound error. See "Special Considerations" below for a description of the events that may cause this problem.

Discussion

The Drag Manager follows the cursor on the screen with the “dotted outline” drag feedback and sends tracking messages to applications that have registered drag tracking handlers. The drag item flavor information cached for the drag is available to each application that becomes active during a drag.

When the user releases the mouse button, the Drag Manager calls any drag receive handlers that have been registered on the destination window. An application’s drag receive handler(s) are responsible for accepting the drag and transferring the dragged data into their application.

The TrackDrag function returns noErr in situations where the user selected a destination for the drag and the destination received data from the Drag Manager. If the user drops over a non-aware application or the receiver does not accept any data from the Drag Manager, the Drag Manager automatically provides a "zoom back" animation and returns the userCanceledErr flag.

Special Considerations

During the call to the TrackDrag function, your application’s context is temporarily switched out when the Drag Manager calls a different application’s tracking and receive handlers. Do not depend on your application’s context to be active for the entire duration of a drag.

The following actions may cause TrackDrag to fail with a procNotFound error:

Using a high-level debugger with the Drag Manager. Although there is no workaround for this problem, your code should work fine when run without the debugger.
Passing TrackDrag an event record in which the where field is expressed in local coordinates. In such cases, the where field often points outside of the window in which the drag originated. This problem can cause a crash as well as a procNotFound error.
Using the Drag Manager with Text Services Manager windows when the gestaltDragMgrFloatingWind bit isn't defined.

For more information, see the Q&A at:

http://developer.apple.com/dev/techsupport/develop/issue29/macqa.html.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

WaitMouseMoved

Returns true if a mouse movement is the beginning of a drag.

Boolean WaitMouseMoved (
   Point initialGlobalMouse
);

Parameters

initialMouse: The point where a mouseDown event occurred in global screen coordinates.

Return Value

True if the mouse moves away from the initialMouse location before the mouse button is released, otherwise false.

Discussion

You can use this function to determine whether you should begin to drag the object when your application receives a mouseDown event on a draggable object.

Availability

Available in Mac OS X v10.0 and later.
Not available to 64-bit applications.

Declared In

Drag.h

Callbacks by Task

Tracking and Receiving Drags

Overriding Drag Manager Behavior

Callbacks

DragDrawingProcPtr

Defines a pointer to a drag drawing function that draws the drag region.

Not recommended

typedef OSErr (*DragDrawingProcPtr) (
   DragRegionMessage message,
   RgnHandle showRegion,
   Point showOrigin,
   RgnHandle hideRegion,
   Point hideOrigin,
   void * dragDrawingRefCon,
   DragRef theDrag);

If you name your function MyDragDrawingFunction, you would declare it like this:

OSErr MyDragDrawingFunction (
   DragRegionMessage message,
   RgnHandle showRegion,
   Point showOrigin,
   RgnHandle hideRegion,
   Point hideOrigin,
   void * dragDrawingRefCon,
   DragRef theDrag);

Parameters

message: A drag region drawing message from the Drag Manager. Use this message to determine what action your drag drawing callback function should take. These messages are described further in “Drag Drawing Messages.”
showRegion: A region containing the drag region as it should be drawn or is currently visible on the screen, in global screen coordinates. The showRegion parameter has slightly different meanings depending on the message passed to your drag drawing callback.
showOrigin: The point corresponding to the original mouseDown location in the drag region within the given showRegion, in global screen coordinates.
hideRegion: A region containing the drag region as it should be erased from the screen, in global screen coordinates. The hideRegion parameter has slightly different meanings depending on the message passed to your drag drawing callback.
hideOrigin: The point corresponding to the original mouseDown location in the drag region within the given hideRegion, in global screen coordinates.
dragDrawingRefCon: A pointer to the reference constant that was provided when the SetDragDrawingProc function was called to install this function.
theDrag: The drag reference of the drag.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

If your application set a custom drawing function for a drag using the SetDragDrawingProc function, the Drag Manager calls this drawing function to perform all drag region drawing operations.

The Drag Manager tracks the drag region as it appears on the screen and as it should follow the mouse. All drag region operations are performed on the region specified to the TrackDrag function. Drag region drawing is managed by sending your drag drawing callback function messages to show and hide pieces of the drag region.

The Drag Manager has its own drag region port that is used to do all drag region drawing during a drag. This port is set to the current port before calling your drag drawing function. The drag region port is for your drag drawing function’s exclusive use during a drag. You may modify its fields and depend on its contents between calls to your drag drawing callback function.

Special Considerations

For Classic applications, your application’s context is not available when your drag drawing callback function is called by the Drag Manager. If you need access to your application’s global variables, you will need to setup and restore your application’s A5 world yourself.

You cannot call the WaitNextEvent function or any other Event Manager functions in your drag drawing callback function. This restriction includes calling any functions that may call the Event Manager, such as the ModalDialog or Alert functions.

Carbon Porting Notes

Drag drawing functions are not supported in Mac OS X, although they continue to work in CarbonLib when running Mac OS 8 and Mac OS 9.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragInputProcPtr

Defines a pointer to a drag input function that modifies keyboard and mouse input to the Drag Manager.

typedef OSErr (*DragInputProcPtr) (
   
   Point * mouse,
   SInt16 * modifiers,
   void * dragInputRefCon,
   DragRef theDrag);

If you name your function MyDragInputFunction, you would declare it like this:

OSErr MyDragInputFunction (
   Point * mouse,
   SInt16 * modifiers,
   void * dragInputRefCon,
   DragRef theDrag);

Parameters

mouse: On entry, a pointer to the location. On return, your drag input function should provide the desired current mouse location. The mouse location is specified in global coordinates.
modifiers: On entry, a pointer to a value indicating the current state of the keyboard modifiers and mouse button. On return, your drag input function should provide a pointer to the desired state of the keyboard modifiers and mouse button. The modifiers are specified using the same format and constants as the Event Manager’s EventRecord.modifiers field.
dragInputRefCon: A pointer to the reference constant that was provided when the SetDragInputProc function was called to install this function.
theDrag: The drag reference of the drag.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

Each time the Drag Manager samples the mouse and keyboard, it calls your drag input callback (if one has been set by calling the SetDragInputProc function) to provide a way for your application to modify or completely change the mouse and keyboard input to the Drag Manager.

When your drag input callback function is called, the mouse and modifiers parameters contain the actual values from the physical input devices. Your drag input callback function may modify these values in any way. For example, your drag input callback function may simply inhibit the control key modifier bit from being set or it may completely replace the mouse coordinates with those generated some other way to drive the drag itself.

Note that the Drag Manager uses the buttonState flag in the modifiers parameter to determine when the mouse button has been released to finish a drag.

Special Considerations

For Classic applications, your application’s context is not available when your drag input callback function is called by the Drag Manager. If you need access to your application’s global variables, you will need to setup and restore your application’s A5 world yourself.

You cannot call the WaitNextEvent function or any other Event Manager functions from your drag input callback function. This restriction includes calling any functions that may call the Event Manager, such as the ModalDialog or Alert functions.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragReceiveHandlerProcPtr

Defines a pointer to a drag receive handler.

typedef OSErr (*DragReceiveHandlerProcPtr)
(
   WindowRef theWindow,
   void * handlerRefCon,
   DragRef theDrag);

If you name your function MyDragReceiveHandler, you would declare it like this:

OSErr MyDragReceiveHandler (
   WindowRef theWindow,
   void * handlerRefCon,
   DragRef theDrag);

Parameters

theWindow: A reference to the window that the drop occurred in.
handlerRefCon: A pointer to the reference constant that was provided to the InstallReceiveHandler function when this handler was installed.
theDrag: The drag reference of the drag.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

When the user releases a drag in a window, the Drag Manager calls any drag receive handler functions that have been installed on that window. You can get the information about the data that is being dragged, to determine if your window will accept the drop, by using the drag information functions provided by the Drag Manager. After your drag receive handler decides that it can accept the drop, use the GetFlavorData function to get the data from the sender of the drag.

When the Drag Manager calls your drag receive handler, the port is set to the window that the drop occurred in. If you want to provide an optional Apple Event descriptor of the drop location for the sender, use the SetDropLocation function to set the drop location descriptor before calling the sender with the GetFlavorData or GetFlavorDataSize functions.

If you return any result code other than noErr from your drag receive handler, the Drag Manager will "zoomback" the drag region to the source location and return the userCanceledErr result code from the TrackDrag function. If the drag is dropped into a location that cannot accept the drag (such as the window title bar or window scroll bars) or no acceptable data types were available, your drag receive handler should return the dragNotAcceptedErr result code, which will cause the Drag Manager to provide the "zoomback" animation described above.

Special Considerations

For Classic applications, the Drag Manager guarantees that your application’s A5 world and low-memory environment is properly set up for your application’s use. Therefore, you can allocate memory, and use your application’s global variables. You can also rely on low-memory globals being valid.

Although it is possible to call WaitNextEvent or other functions that run the event loop from within your drag receive handler, it is not recommended as it can cause the drag to timeout and may result in a crash or in corrupt data.

Note that the Process Manager's process switching mechanism is disabled during calls to your handler. If your application is not frontmost when calling these functions, your application will not be able to switch forward. This could result in a situation where a modal dialog appears behind the front process but will not be able to come forward in order to interact with the user.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragSendDataProcPtr

Defines a pointer to a drag send data function, called by the Drag Manager to supply flavor data to the drag receiver.

typedef OSErr (*DragSendDataProcPtr)
(
   FlavorType theType,
   void * dragSendRefCon,
   DragItemRef theItemRef,
   DragRef theDrag);

If you name your function MyDragSendDataFunction, you would declare it like this:

OSErr MyDragSendDataFunction (
   FlavorType theType,
   void * dragSendRefCon,
   DragItemRef theItemRef,
   DragRef theDrag);

Parameters

theType: The flavor type being requested by a drop receiver.
dragSendRefCon: A pointer to the reference constant that was provided when the SetDragSendProc function was called to install this function.
theItemRef: The item reference of the item from which the flavor data is being requested.
theDrag: The drag reference of the drag.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

The Drag Manager calls your drag send data function when drag item flavor data is requested by a drop receiver if the drag item flavor data is not already cached by the Drag Manager. Use the function SetDragItemFlavorData to provide the requested data to the Drag Manager.

The Drag Manager caches all drag item flavor data that was specified in the data pointer when the flavor was added using the AddDragItemFlavor function. If the data pointer was NULL when the flavor was added, the Drag Manager calls the drag send data function to get the data when a receiver requests the data using the GetFlavorData or GetFlavorDataSize functions.

A second scenario where the drag send data function is called is when a drop receiver requests a flavor that is translated by the Translation Manager and the source data (which would be a different type than actually requested by the receiver) is not already cached by the Drag Manager.

You can use the GetDropLocation function to get the Apple event descriptor of the drop location from within your drag send data function. It is optional for the receiver to provide a drop location descriptor. If the receiver does not provide the drop location descriptor, the typeNull value will be returned by the GetDropLocation function.You do not need to provide a drag send data function if you never pass NULL as the data pointer when calling the AddDragItemFlavor function.

Special Considerations

Although it is possible to call WaitNextEvent or other functions that run the event loop from within your drag send data callback, it is not recommended as it can cause the drag to timeout and may result in a crash or in corrupt data.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragTrackingHandlerProcPtr

Defines a pointer to a drag tracking handler.

typedef OSErr (*DragTrackingHandlerProcPtr)
(
   DragTrackingMessage message,
   WindowRef theWindow,
   void * handlerRefCon,
   DragRef theDrag);

If you name your function MyDragTrackingHandler, you would declare it like this:

OSErr MyDragTrackingHandler (
   DragTrackingMessage message,
   WindowRef theWindow,
   void * handlerRefCon,
   DragRef theDrag);

Parameters

message: A tracking message from the Drag Manager indicating the action your tracking handler should take. These messages are described further in “Drag Tracking Messages.”
theWindow: A reference to the window that the mouse is currently over.
handlerRefCon: A pointer to the reference constant that was provided to the InstallTrackingHandler function when this handler was installed.
theDrag: The drag reference of the drag.

Return Value

A result code. See “Drag Manager Result Codes.”

Discussion

When the user drags an item or collection of items through a window, the Drag Manager calls any tracking handlers that have been installed on that window. Your tracking handler can determine the contents of the drag by calling the drag item information functions, such as CountDragItems, CountDragItemFlavors, GetFlavorType and GetFlavorFlags, and highlighting or modifying the objects in your window accordingly.

When the Drag Manager calls your tracking handler, the port will always be set to the window that the mouse is over.

Special Considerations

Although it is possible to call WaitNextEvent or other functions that run the event loop from within your drag tracking handler, it is not recommended as it can cause the drag to timeout and may result in a crash or in corrupt data.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

Data Types

DragRef

Defines a reference to a drag object.

typedef struct OpaqueDragRef * DragRef;

Discussion

Before calling any other Drag Manager function, you must first create a new drag reference by calling the NewDrag function. The drag reference that is returned by the NewDrag function is used in all subsequent calls to the Drag Manager. Use the DisposeDrag function to dispose of a drag reference after you are finished using it.

The meaning of the bits in a drag reference is internal to the Drag Manager. You should not attempt to interpret the value of the drag reference.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragItemRef

Defines a reference to a drag item.

typedef UInt32 DragItemRef;

Discussion

The drag item reference is a reference number used to refer to a single item in a drag. Drag item reference numbers are created by the sender application when adding drag item flavor information to a drag. Drag item reference numbers are created by and should only be interpreted by the sender application.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

FlavorType

Defines a flavor type.

typedef OSType FlavorType;

Discussion

The flavor type is a four character type that describes the format of drag item flavor data. The flavor type has the same function as a scrap type; it designates the format of the associated data. Any scrap type or resource type may be used.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

HFSFlavor

Defines a flavor for dragging file system objects.

struct HFSFlavor {
   OSType fileType;
   OSType fileCreator;
   UInt16 fdFlags;
   FSSpec fileSpec;
};
typedef struct HFSFlavor HFSFlavor;

Fields

fileType: The file type of the object.
fileCreator: The file creator of the object.
fdFlags: The Finder flags of the object.
fileSpec: The FSSpec structure for the object.

Discussion

The Drag Manager defines a special flavor for dragging file system objects. The HFS drag item flavor is used when dragging document and folder icons in the Finder. The HFS drag item flavor data structure is defined by the HFSFlavor data type.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

PromiseHFSFlavor

Defines a data flavor for promising file system objects.

struct PromiseHFSFlavor {
   OSType fileType;
   OSType fileCreator;
   UInt16 fdFlags;
   FlavorType promisedFlavor;
};
typedef struct PromiseHFSFlavor PromiseHFSFlavor;

Fields

fileType: The file type of the object.
fileCreator: The file creator of the object.
fdFlags: The Finder flags of the object.
promisedFlavor: The flavor type of a separate promise flavor to contain the FSSpec structure for the new file. Apple recommends that you use the kDragPromisedFlavor type in this field.

Discussion

The promise HFS flavor type is used when you wish to create a new file when dragging to the Finder. The flavor consists of an array of PromiseHFSFlavor structures, with the first entry being the preferred file type you would like to create and subsequent array entries being file types in descending preference. This structure allows you to create the file in your DragSendDataProcPtr callback and provide the FSSpec for the new file at that time.

After providing an FSSpec, the Finder will move the new file to the drop location. If you wish to create the file before the drag and provide the FSSpec data up front, create the new file in the Temporary Items folder so it does not prematurely appear in an open Finder window.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragDrawingUPP

Defines a universal procedure pointer (UPP) to a drag drawing callback.

typedef DragDrawingProcPtr DragDrawingUPP;

Discussion

For more information, see the description of the DragDrawingProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragInputUPP

Defines a universal procedure pointer (UPP) to a drag input callback.

typedef DragInputProcPtr DragInputUPP;

Discussion

For more information, see the description of the DragInputProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragReceiveHandlerUPP

Defines a universal procedure pointer (UPP) to a drag receive handler.

typedef DragReceiveHandlerProcPtr DragReceiveHandlerUPP;

Discussion

For more information, see the description of the DragReceiveHandlerProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragSendDataUPP

Defines a universal procedure pointer (UPP) to a drag send data callback.

typedef DragSendDataProcPtr DragSendDataUPP;

Discussion

For more information, see the description of the DragSendDataProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

DragTrackingHandlerUPP

Defines a universal procedure pointer (UPP) to a drag tracking handler.

typedef DragTrackingHandlerProcPtr DragTrackingHandlerUPP;

Discussion

For more information, see the description of the DragTrackingHandlerProcPtr callback function.

Availability

Available in Mac OS X v10.0 and later.

Declared In

Drag.h

Constants

Drag Attributes

Provide additional information about a drag that is in progress.

typedef UInt32 DragAttributes;
enum {
   kDragHasLeftSenderWindow = (1L << 0),
   kDragInsideSenderApplication = (1L << 1),
   kDragInsideSenderWindow = (1L << 2) };

Constants

kDragHasLeftSenderWindow

Set if the drag has left the source window since the beginning of the drag. This flag is useful for providing window highlighting after the user has moved the mouse outside of the source window.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragInsideSenderApplication

Set if the drag is currently in any window that belongs to the application that started the drag.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragInsideSenderWindow

Set if the drag is currently in the same window that the drag started from.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Discussion

The attribute flags defined by the DragAttributes type provide information about the window and application that the drag is currently occurring in. During a drag, the current drag attributes can be obtained by calling the function GetDragAttributes.

Drag Behaviors

Specify the current zoomback behavior of a drag.

typedef UInt32 DragBehaviors;
enum {
   kDragBehaviorNone = 0,
   kDragBehaviorZoomBackAnimation = (1L << 0) };

Constants

kDragBehaviorNone

The Drag Manager performs no animation for a failed drag.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragBehaviorZoomBackAnimation

The Drag Manager performs zoomback animation for a failed drag. This behavior is normally enabled.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Discussion

To change the behavior associated with a drag reference, use the ChangeDragBehaviors function.

Drag Drawing Messages

Define messages that may be sent to your drag drawing callback.

typedef SInt16 DragRegionMessage;
enum {
   kDragRegionBegin = 1,
   kDragRegionDraw = 2,
   kDragRegionHide = 3,
   kDragRegionIdle = 4,
   kDragRegionEnd = 5
};

Constants

kDragRegionBegin

Your drag drawing callback function receives this message when a drag is being started and it is time to initialize your drawing function. You should not draw anything to the screen when you receive this message.The showRegion and showOrigin parameters to your drag drawing callback function contain the drag region and the mouseDown location, respectively, that were specified to the TrackDrag function. The mouseDown location is the origin of the drag region.The hideRegion parameter is NULL when your drag drawing callback function receives this message.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragRegionDraw

Your drag drawing callback receives this message when you should move your drag region from the area of the screen defined by the hideRegion parameter to the area of the screen defined by the showRegion parameter.The showRegion parameter contains the drag region that was passed to the TrackDrag function, offset to the current pinned mouse location. This region represents the area of the screen that must be drawn into.The hideRegion parameter contains the drag region as it is currently visible on the screen from the last call with a dragRegionDraw message. This region represents the area of the screen that must be restored. Any part of the drag region that was previously obscured by a call with the dragRegionHide message is not included in this hideRegion parameter.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragRegionHide

Your drag drawing callback receives this message when you should remove part of the drag region from the screen. You receive this message when the drag has ended or when part of the region must be obscured for drawing operations to occur underneath the drag region.The showRegion parameter is NULL when your drag drawing callback function receives this message.The hideRegion parameter contains the part of the currently visible drag region that must be removed from the screen.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragRegionIdle

Your drag drawing callback receives this message when the drag region has not moved on the screen and no drawing is necessary. You can use this message if animation of the drag region is necessary.The showRegion parameter contains the drag region as it is currently visible on the screen.The hideRegion parameter is NULL when your drag drawing callback receives this message.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragRegionEnd

Your drag drawing callback receives this message when the drag has completed and it is time to deallocate any allocations made from within your drag drawing callback. Your drag drawing callback will have already received a dragRegionHide message to hide the entire drag region before receiving this message. After you receive this message, your drag drawing callback will not be called again for the duration of the drag.Both the showRegion and hideRegion parameters are NULL when your drag drawing callback function receives this message.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Discussion

See DragDrawingProcPtr for more information on drag drawing callback functions.

Drag Tracking Messages

Define messages that may be sent to your drag tracking handler.

typedef SInt16 DragTrackingMessage;
enum {
   kDragTrackingEnterHandler = 1,
   kDragTrackingEnterWindow = 2,
   kDragTrackingInWindow = 3,
   kDragTrackingLeaveWindow = 4,
   kDragTrackingLeaveHandler = 5
};

Constants

kDragTrackingEnterHandler

Your tracking handler receives this message when the focus of a drag enters a window that is handled by your tracking handler. If the user moves the drag directly to another window that is handled by the same tracking handler, a second kDragTrackingEnterHandler message is not received. Your tracking handler only receives this message when the drag enters the domain of your function after leaving another.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragTrackingEnterWindow

Your tracking handler receives this message when a drag enters any window that is handled by your tracking handler. This message is sent to your tracking handler for each window that the drag may enter. Your tracking handler will always receive this message within a pair of kDragTrackingEnterHandler and kDragTrackingLeaveHandler messages.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragTrackingInWindow

Your tracking handler receives this message as the user is dragging within a window handled by your tracking handler. You can use this message to track the dragging process through your window. Your tracking handler will always receive this message within a pair of kDragTrackingEnterWindow and kDragTrackingLeaveWindow messages.Your tracking handler would typically draw the majority of your window highlighting and track objects in your window when you receive this message from the Drag Manager.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragTrackingLeaveWindow

Your tracking handler receives this message when a drag leaves any window that is handled by your tracking handler. You are guaranteed to receive this message after receiving a corresponding kDragTrackingEnterWindow message. Your tracking handler will always receive this message within a pair of kDragTrackingEnterHandler and kDragTrackingLeaveHandler messages.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragTrackingLeaveHandler

Your tracking handler receives this message when the focus of a drag enters a window that is not handled by your tracking handler. Your tracking handler is guaranteed to receive this message after receiving a corresponding kDragTrackingEnterHandler message.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Discussion

See DragTrackingHandlerProcPtr for more information on drag tracking handlers.

Flavor Flags

Provide additional information about drag item flavors.

typedef UInt32 FlavorFlags;
enum {
   flavorSenderOnly = (1 << 0),
   flavorSenderTranslated = (1 << 1),
   flavorNotSaved = (1 << 2),
   flavorSystemTranslated = (1 << 8),
   flavorDataPromised = (1 << 9) };

Constants

flavorSenderOnly

Set by the sender if the flavor should only be available to the sender of a drag. If this flag is set when adding the flavor to a drag, no Drag Manager clients other than the sender can receive this flavor.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorSenderTranslated

Set by the sender if the flavor data is translated by the sender. This flag is useful to a receiver if the receiver needs to determine if the sender is performing its own translation to generate this data type. Typically, receivers that store dragged data without interpreting each data type do not store translated types. Flavor types marked with this flag are not stored by the Finder in clipping files.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorNotSaved

Set by the sender if the flavor data should not be stored by the receiver. This flag is useful for marking flavor data that will become stale after the drag has completed. Receivers that store dragged data should not store flavors that are marked with this flag. Flavor types marked with this flag are not stored by the Finder in clipping files.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorSystemTranslated

Set if the flavor data is provided by the Translation Manager. If this flavor is requested, the Drag Manager will obtain any required data types from the sender and then it will use the Translation Manager to provide the data that the receiver requested. Typically, receivers that store dragged data without interpreting each data type do not store translated types. Flavor types marked with this flag are not stored by the Finder in clipping files.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorDataPromised

Set by the sender if the flavor data is promised at a later time.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

Discussion

These constants are used when calling the AddDragItemFlavor function and can be obtained by calling the GetFlavorFlags function.

flavorTypeDirectory

Represents a special flavor type for AOCE directory specifications.

enum {
   flavorTypeDirectory = 'diry'
};

Constants

flavorTypeDirectory

The flavor type for a AOCE directory specification. Refer to the AOCE documentation for a definition of the DSSpec data structure.

Available in Mac OS X v10.0 through Mac OS X v10.4.

Declared in Drag.h.

Drag Actions

Specify the actions that should be or have been performed on the data in a drag.

enum {
   kDragActionNothing = 0,
   kDragActionCopy = 1L,
   kDragActionAlias = (1L << 1),
   kDragActionGeneric = (1L << 2),
   kDragActionPrivate = (1L << 3),
   kDragActionMove = (1L << 4),
   kDragActionDelete = (1L << 5),
   kDragActionAll = 0xFFFFFFFF };
typedef UInt32 DragActions;

Constants

kDragActionNothing

Nothing should be or has been done with the data in the drag. When set as an allowable action for remote drags, the drag is not sent to applications other than the drag sender.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionCopy

The data contained in the drag can be or has been copied.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionAlias

The data contained in the drag can be or has been shared.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionGeneric

When set by the drag sender, suggests that the drag receiver can determine the drag action. When returned by the drag receiver, indicates that the receiver did not define a drag action.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionPrivate

Suggests that the drag action should be negotiated privately between the drag source and destination.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionMove

The data contained in the drag can be or has been moved.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionDelete

The data contained in the drag can be or has been deleted.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

kDragActionAll

Indicates that all of the above drag actions are allowed.

Available in Mac OS X v10.1 and later.

Declared in Drag.h.

Discussion

The drag sender can use these constants to indicate what actions are allowable on the data contained within a drag. The drag receiver can use these constants to indicate what, if any, action was performed on the drag.

Some of the drag actions defined here enforce a mode of operation, while others are suggestions. The DragActions constants are used in conjunction with the GetDragAllowableActions, SetDragAllowableActions, GetDragDropAction, and SetDragDropAction functions. Using drag actions increases compatibility with the Cocoa drag operation model.

HFS Flavor Types

Identify flavor types for file system objects.

enum {
   kDragFlavorTypeHFS = 'hfs ',
   kDragFlavorTypePromiseHFS = 'phfs',
   flavorTypeHFS = kDragFlavorTypeHFS,
   flavorTypePromiseHFS = kDragFlavorTypePromiseHFS
};

Constants

kDragFlavorTypeHFS

The flavor type for an HFS file system object. The Finder uses HFS flavors when dragging existing file system objects. The HFS flavor data is defined by the data type HFSFlavor.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragFlavorTypePromiseHFS

The flavor type for promising an HFS file system object to the receiver of the drag. This flavor type can be used when a file could be created if the destination of the drag can accept file system objects. The data type PromiseHFSFlavor is used to access the information in this flavor type.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorTypeHFS

Use kDragFlavorTypeHFS instead.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

flavorTypePromiseHFS

Use kDragFlavorTypePromiseHFS instead.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Promised Flavor Types

Identify flavor types for the PromiseHFSFlavor structure.

enum {
   kDragPromisedFlavorFindFile = 'rWm1',
   kDragPromisedFlavor = 'fssP'
};

Constants

kDragPromisedFlavorFindFile

The value of the promisedFlavor field of the PromiseHFSFlavor structure for Find File.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragPromisedFlavor

The value of the promisedFlavor field of the PromiseHFSFlavor structure for all other file system objects.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Type and Creator Constants for Volumes and Directories

Define a creator code and file types for flavor data referring to a volume or directory.

enum {
   kDragPseudoCreatorVolumeOrDirectory = 'MACS',
   kDragPseudoFileTypeVolume = 'disk',
   kDragPseudoFileTypeDirectory = 'fold'
};

Constants

kDragPseudoCreatorVolumeOrDirectory

The "creator type" for volumes and directories. If the data in a drag containing kDragFlavorTypeHFS data refers to a folder or volume, the fileCreator field of the HFSFlavor structure should be set to this value.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragPseudoFileTypeVolume

The value of the fileType field of the HFSFlavor structure for a volume.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragPseudoFileTypeDirectory

The value of the fileType field of the HFSFlavor structure for a directory.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Standard Drop Locations

Define common drop locations.

enum {
   kDragStandardDropLocationTrash = 'trsh',
   kDragStandardDropLocationUnknown = 'unkn'
};
typedef OSType StandardDropLocation;

Constants

kDragStandardDropLocationTrash

Set when a drag is dropped on the trash icon. Setting this standard drop location automatically sets the traditional drop location to an alias to the trash folder.

Available in Mac OS X v10.2 and later.

Declared in Drag.h.

kDragStandardDropLocationUnknown

The receiver did not specify a drop location. This is the default.

Available in Mac OS X v10.2 and later.

Declared in Drag.h.

Discussion

These values are used in conjunction with the GetStandardDropLocation and SetStandardDropLocation functions.

Drag Image Flags

Specify the appearance of a translucent drag.

typedef UInt32 DragImageFlags;
enum {
   kDragRegionAndImage = (1L << 4)
   kDragStandardTranslucency = 0,
   kDragDarkTranslucency = 1,
   kDragDarkerTranslucency = 2,
   kDragOpaqueTranslucency = 3
};

Constants

kDragRegionAndImage

Add this constant to the transparency levels represented by the following constants to specify that the outline region passed to TrackDrag should be drawn on screen, in addition to the translucent drag image.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragStandardTranslucency

Use the standard translucency level for the drag image. Currently, this is 65%.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragDarkTranslucency

Use 50% translucency for the drag image.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragDarkerTranslucency

Use 25% transparency for the drag image.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kDragOpaqueTranslucency

Use an opaque drag image (0% translucency).

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Discussion

These constants are used in conjunction with the SetDragImageWithCGImageand SetDragImage functions to specify the appearance of the drag image.

Finder Flavor Types

Identify flavor types for the Finder.

enum {
   kFlavorTypeClippingName = 'clnm',
   kFlavorTypeClippingFilename = 'clfn',
   kFlavorTypeUnicodeClippingName = 'ucln',
   kFlavorTypeUnicodeClippingFilename = 'uclf',
   kFlavorTypeDragToTrashOnly = 'fdtt',
   kFlavorTypeFinderNoTrackingBehavior = 'fntb'
};

Constants

kFlavorTypeClippingName

The flavor of a name hint for a clipping file. This flavor type is preferred over the kFlavorTypeClippingFilename type.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kFlavorTypeClippingFilename

The flavor of the name of a clipping file.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kFlavorTypeUnicodeClippingName

The flavor of a hint for the unicode name of a clipping file. This flavor type is preferred over the kFlavorTypeUnicodeClippingFilename type.

Available in Mac OS X v10.2 and later.

Declared in Drag.h.

kFlavorTypeUnicodeClippingFilename

The flavor of the unicode name of a clipping file.

Available in Mac OS X v10.2 and later.

Declared in Drag.h.

kFlavorTypeDragToTrashOnly

Specify this flavor to allow dragging private data to the trash.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kFlavorTypeFinderNoTrackingBehavior

A flavor type indicating that the Finder should ignore the drag.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

Zoom Acceleration Constants

Specify acceleration constants for the ZoomRects and ZoomRegion functions.

typedef SInt16 ZoomAcceleration;
enum {
   kZoomNoAcceleration = 0,
   kZoomAccelerate = 1,
   kZoomDecelerate = 2
};

Constants

kZoomNoAcceleration

Use linear interpolation for each frame of animation between the source and destination.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kZoomAccelerate

Increment the step size for each frame of animation between the source and destination. This option produces the visual appearance of the animation speeding up as it approaches the destination.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

kZoomDecelerate

Decrement the step size for each frame of animation between the source and destination. This option produces the visual appearance of the animation slowing down as it approaches the destination.

Available in Mac OS X v10.0 and later.

Declared in Drag.h.

zoomNoAcceleration

Obsolete. Use "Zoom Acceleration Constants" instead.

enum {
   zoomNoAcceleration = kZoomNoAcceleration,
   zoomAccelerate = kZoomAccelerate,
   zoomDecelerate = kZoomDecelerate
};

kDragStandardImage

Obsolete. Use "Drag Image Flags" instead.

enum {
   kDragStandardImage = kDragStandardTranslucency,
   kDragDarkImage = kDragDarkTranslucency,
   kDragDarkerImage = kDragDarkerTranslucency,
   kDragOpaqueImage = kDragOpaqueTranslucency
};

dragTrackingEnterHandler

Obsolete. Use "Drag Tracking Messages" instead.

enum {
   dragTrackingEnterHandler = kDragTrackingEnterHandler,
   dragTrackingEnterWindow = kDragTrackingEnterWindow,
   dragTrackingInWindow = kDragTrackingInWindow,
   dragTrackingLeaveWindow = kDragTrackingLeaveWindow,
   dragTrackingLeaveHandler = kDragTrackingLeaveHandler
};

dragRegionBegin

Obsolete. Use "Drag Drawing Messages" instead.

enum {
   dragRegionBegin = kDragRegionBegin,
   dragRegionDraw = kDragRegionDraw,
   dragRegionHide = kDragRegionHide,
   dragRegionIdle = kDragRegionIdle,
   dragRegionEnd = kDragRegionEnd
};

dragHasLeftSenderWindow

Obsolete. Use "Drag Attributes" instead.

enum {
   dragHasLeftSenderWindow = kDragHasLeftSenderWindow,
   dragInsideSenderApplication = kDragInsideSenderApplication,
   dragInsideSenderWindow = kDragInsideSenderWindow
};

Result Codes

The table below lists the most common result codes returned by the Drag Manager.

Result Code	Value	Description
`badDragRefErr`	-1850	Unknown drag reference Available in Mac OS X v10.0 and later.
`badDragItemErr`	-1851	Unknown drag item reference Available in Mac OS X v10.0 and later.
`badDragFlavorErr`	-1852	Unknown flavor type Available in Mac OS X v10.0 and later.
`duplicateFlavorErr`	-1853	Flavor type already exists Available in Mac OS X v10.0 and later.
`cantGetFlavorErr`	-1854	Error while trying to get flavor data Available in Mac OS X v10.0 and later.
`duplicateHandlerErr`	-1855	Handler already exists Available in Mac OS X v10.0 and later.
`handlerNotFoundErr`	-1856	Handler not found Available in Mac OS X v10.0 and later.
`dragNotAcceptedErr`	-1857	Drag was not accepted by receiver Available in Mac OS X v10.0 and later.
`unsupportedForPlatformErr`	-1858	Call is for PowerPC only Available in Mac OS X v10.0 and later.
`noSuitableDisplaysErr`	-1859	No displays support translucency Available in Mac OS X v10.0 and later.
`badImageRgnErr`	-1860	Bad translucent image region Available in Mac OS X v10.0 and later.
`badImageErr`	-1861	Bad translucent image PixMap Available in Mac OS X v10.0 and later.
`nonDragOriginatorErr`	-1862	Illegal attempt to access originator only data Available in Mac OS X v10.0 and later.

Gestalt Constants

You can check for version and feature availability information by using the Drag Manager selectors defined in the Gestalt Manager. For more information see Inside Mac OS X: Gestalt Manager Reference

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.