Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

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

For more information, see the Q&A at:

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

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

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

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

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