| Mac OS X header: | Carbon/Carbon.h |
| Mac OS 9 header: | Drag.h |
| Miscellaneous Callbacks | |
| DragTrackingHandlerProcPtr | Defines a pointer to a drag tracking handler callback function. |
| DragReceiveHandlerProcPtr | Defines a pointer to a drag receive handler callback function. |
| DragSendDataProcPtr | Defines a pointer to a drag send data function. |
| DragInputProcPtr | Defines a pointer to a drag input callback function. |
| DragDrawingProcPtr | Defines a pointer to a drag drawing callback function. |
DragTrackingHandlerProcPtr |
Defines a pointer to a drag tracking handler callback function.
typedef OSErr(* DragTrackingHandlerProcPtr) (
DragTrackingMessage message,
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag
);
If you name your function MyDragTrackingHandlerCallback, you would declare it like this:
OSErr MyDragTrackingHandlerCallback (
DragTrackingMessage message,
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag
);
A tracking message from the Drag Manager to determine what action your tracking handler function should take. These messages are defined by the enumeration
A pointer to the window that the mouse is currently over.
A pointer to the reference constant that was provided to the InstallTrackingHandler function when this handler was installed.
The drag reference of the drag.
A result code.
When the user drags an item or collection of items through a window, the Drag Manager calls any tracking handler functions 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
When the Drag Manager calls your tracking handler, the port will always be set to the window that the mouse is over.
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.You cannot call the WaitNextEvent function or any other Event Manager functions from within your tracking handler. This includes calling any functions that may call the Event Manager, such as the ModalDialog or Alert functions. 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.
DragReceiveHandlerProcPtr |
Defines a pointer to a drag receive handler callback function.
typedef OSErr(* DragReceiveHandlerProcPtr) (
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag
);
If you name your function MyDragReceiveHandlerCallback, you would declare it like this:
OSErr MyDragReceiveHandlerCallback (
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag
);
A pointer to the window that the drop occurred in.
A pointer to the reference constant that was provided to the InstallReceiveHandler function when this handler was installed.
The drag reference of the drag.
A result code.
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 needed data from the sender of the drag.
When the Drag Manager calls your drag receive handler, the port will be set to the window that the drop occurred in. If you want to provide an optional AppleEvent 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 the noErr result code from your drag receive handler, the Drag Manager will “zoomback” the drag region to the source location and return result code 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.
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.
You cannot call the WaitNextEvent function or any other Event Manager functions from within your drag receive handler. This includes calling any functions that may call the Event Manager, such as the ModalDialog or Alert functions. 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.
DragSendDataProcPtr |
Defines a pointer to a drag send data function.
typedef OSErr(* DragSendDataProcPtr) (
FlavorType theType,
void *dragSendRefCon,
DragItemRef theItemRef,
DragRef theDrag
);
If you name your function MyDragSendDataCallback, you would declare it like this:
OSErr MyDragSendDataCallback (
FlavorType theType,
void *dragSendRefCon,
DragItemRef theItemRef,
DragRef theDrag
);
The flavor type being requested by a drop receiver.
A pointer to the reference constant that was provided when the SetDragSendProc function was called to install this function.
The item reference of the item from which the flavor data is being requested.
The drag reference of the drag.
A result code.
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
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.
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.
You cannot call the WaitNextEvent function or any other Event Manager functions from within your drag send data function. This includes calling any functions that may call the Event Manager, such as the ModalDialog or Alert functions. 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.
DragInputProcPtr |
Defines a pointer to a drag input callback function.
typedef OSErr(* DragInputProcPtr) (
Point *mouse,
SInt16 *modifiers,
void *dragInputRefCon,
DragRef theDrag
);
If you name your function MyDragInputCallback, you would declare it like this:
OSErr MyDragInputCallback (
Point *mouse,
SInt16 *modifiers,
void *dragInputRefCon,
DragRef theDrag
);
On entry, a pointer to the location of the mouse in global screen coordinates. On return, a pointer to the desired current mouse location in global screen coordinates.
On entry, a pointer to the keyboard modifiers and mouse button. On return, 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.
A pointer to the reference constant that was provided when the SetDragInputProc function was called to install this function.
The drag reference of the drag.
A result code.
Each time the Drag Manager samples the mouse and keyboard, it calls your drag input callback function (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.
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.
DragDrawingProcPtr |
Defines a pointer to a drag drawing callback function.
typedef OSErr(* DragDrawingProcPtr) (
DragRegionMessage message,
RgnHandle showRegion,
Point showOrigin,
RgnHandle hideRegion,
Point hideOrigin,
void *dragDrawingRefCon,
DragRef theDrag
);
If you name your function MyDragDrawingCallback, you would declare it like this:
OSErr MyDragDrawingCallback (
DragRegionMessage message,
RgnHandle showRegion,
Point showOrigin,
RgnHandle hideRegion,
Point hideOrigin,
void *dragDrawingRefCon,
DragRef theDrag
);
A drag region drawing message from the Drag Manager. You use the message to determine what action your drag drawing callback function should take. These messages are defined by the enumeration
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 function.
The point corresponding to the original mouseDown location in the drag region within the specified showRegion parameter, in global screen coordinates.
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 function.
The point corresponding to the original mouseDown location in the drag region within the specified hideRegion parameter, in global screen coordinates.
A pointer to the reference constant that was provided when the SetDragDrawingProc function was called to install this function.
The drag reference of the drag.
A result code.
If your application set a custom drawing function for a drag using the SetDragDrawingProc function, the Drag Manager calls your drag drawing callback 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 callback function. The drag region port is for your drag drawing callback 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.
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.
© 2001 Apple Computer, Inc. (Last Updated July 17, 2001)