| Mac OS X header: | Carbon/Carbon.h |
| Mac OS 9 header: | Drag.h |
| Miscellaneous Functions | |
| ChangeDragBehaviors | |
| DisposeDragDrawingUPP | |
| DisposeDragInputUPP | |
| DisposeDragReceiveHandlerUPP | |
| DisposeDragSendDataUPP | |
| DisposeDragTrackingHandlerUPP | |
| GetDragAllowableActions | |
| GetDragDropAction | |
| GetDragHiliteColor | |
| InvokeDragDrawingUPP | |
| InvokeDragInputUPP | |
| InvokeDragReceiveHandlerUPP | |
| InvokeDragSendDataUPP | |
| InvokeDragTrackingHandlerUPP | |
| NewDragDrawingUPP | |
| NewDragInputUPP | |
| NewDragReceiveHandlerUPP | |
| NewDragSendDataUPP | |
| NewDragTrackingHandlerUPP | |
| SetDragAllowableActions | |
| SetDragDropAction | |
| SetDragImage | |
| InstallTrackingHandler | Installs a tracking handler function for one or all of your application’s windows. |
| InstallReceiveHandler | Installs a receive handler function for one or all of your application’s windows. |
| RemoveTrackingHandler | Removes a tracking handler function from one or all of your application’s windows. |
| RemoveReceiveHandler | Removes a receive handler function from one or all of your application’s windows. |
| NewDrag | Creates a new drag reference for your application to use with the Drag Manager. |
| DisposeDrag | Disposes of a drag reference and its associated data. |
| AddDragItemFlavor | Creates a drag item and adds a flavor to a drag item. |
| SetDragItemFlavorData | Sets the data or part of the data contained within an existing flavor. |
| SetDragSendProc | Sets the send data function for the Drag Manager to use with a particular drag. |
| SetDragInputProc | Sets the drag input function for the Drag Manager to use with a particular drag. |
| SetDragDrawingProc | Sets the drag drawing function for the Drag Manager to use with a particular drag. |
| TrackDrag | Drags an item or collection of items from your application. |
| CountDragItems | Gets the number of drag items that are contained in a drag reference. |
| GetDragItemReferenceNumber | Gets the item reference number of a specific item in a drag reference. |
| CountDragItemFlavors | Gets the number of drag item flavors that are contained within a drag item. |
| GetFlavorType | Gets the type of a specific flavor in a drag item. |
| GetFlavorFlags | Gets the flags for a specific flavor in a drag item. |
| GetFlavorDataSize | Gets the size of the flavor data for a specific flavor in a drag item. |
| GetFlavorData | Gets all or part of the flavor data for a specific flavor in a drag item. |
| GetDragItemBounds | Gets the bounding rectangle of a drag item. |
| SetDragItemBounds | Sets the bounding rectangle of a drag item. |
| GetDragAttributes | Gets the current set of drag attribute flags. |
| GetDragMouse | Gets the current mouse and pinned mouse locations. |
| SetDragMouse | Sets the current pinned mouse location. |
| GetDragOrigin | Gets the mouseDown parameter location that started the given drag. |
| GetDragModifiers | Gets the current set of keyboard modifiers. |
| GetDropLocation | Gets the AppleEvent function descriptor of the drop location. |
| SetDropLocation | Sets the AppleEvent descriptor for the drop location of a drag. |
| ShowDragHilite | Highlights an area of your window during a drag. |
| HideDragHilite | Removes highlighting created with the ShowDragHilite function. |
| DragPreScroll | Prepares your window or pane for scrolling. |
| DragPostScroll | Restores the drag highlight after scrolling part of your window. |
| UpdateDragHilite | Updates the portion of the drag highlight that was drawn over by your application. |
| WaitMouseMoved | Returns true if a mouse movement is the beginning of a drag. |
| ZoomRects | Animates a rectangle into a second rectangle. |
| ZoomRegion | Animates a region’s outline from one screen location to another. |
ChangeDragBehaviors |
| Carbon status: | Supported |
OSErr ChangeDragBehaviors (
DragRef theDrag,
DragBehaviors inBehaviorsToSet,
DragBehaviors inBehaviorsToClear
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 9 or later.
DisposeDragDrawingUPP |
| Carbon status: | Supported |
void DisposeDragDrawingUPP (
DragDrawingUPP userUPP
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DisposeDragInputUPP |
| Carbon status: | Supported |
void DisposeDragInputUPP (
DragInputUPP userUPP
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DisposeDragReceiveHandlerUPP |
| Carbon status: | Supported |
void DisposeDragReceiveHandlerUPP (
DragReceiveHandlerUPP userUPP
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DisposeDragSendDataUPP |
| Carbon status: | Supported |
void DisposeDragSendDataUPP (
DragSendDataUPP userUPP
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DisposeDragTrackingHandlerUPP |
| Carbon status: | Supported |
void DisposeDragTrackingHandlerUPP (
DragTrackingHandlerUPP userUPP
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragAllowableActions |
| Carbon status: | Under evaluation |
OSStatus GetDragAllowableActions (
DragRef theDrag,
DragActions *outActions
);
A result code.
Available in Mac OS X, version 10.0 and later.
GetDragDropAction |
| Carbon status: | Under evaluation |
OSStatus GetDragDropAction (
DragRef theDrag,
DragActions *outAction
);
A result code.
Available in Mac OS X, version 10.0 and later.
GetDragHiliteColor |
| Carbon status: | Supported |
OSErr GetDragHiliteColor (
WindowRef window,
RGBColor *color
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InvokeDragDrawingUPP |
| Carbon status: | Supported |
OSErr InvokeDragDrawingUPP (
DragRegionMessage message,
RgnHandle showRegion,
Point showOrigin,
RgnHandle hideRegion,
Point hideOrigin,
void *dragDrawingRefCon,
DragRef theDrag,
DragDrawingUPP userUPP
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InvokeDragInputUPP |
| Carbon status: | Supported |
OSErr InvokeDragInputUPP (
Point *mouse,
SInt16 *modifiers,
void *dragInputRefCon,
DragRef theDrag,
DragInputUPP userUPP
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InvokeDragReceiveHandlerUPP |
| Carbon status: | Supported |
OSErr InvokeDragReceiveHandlerUPP (
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag,
DragReceiveHandlerUPP userUPP
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InvokeDragSendDataUPP |
| Carbon status: | Supported |
OSErr InvokeDragSendDataUPP (
FlavorType theType,
void *dragSendRefCon,
DragItemRef theItemRef,
DragRef theDrag,
DragSendDataUPP userUPP
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InvokeDragTrackingHandlerUPP |
| Carbon status: | Supported |
OSErr InvokeDragTrackingHandlerUPP (
DragTrackingMessage message,
WindowRef theWindow,
void *handlerRefCon,
DragRef theDrag,
DragTrackingHandlerUPP userUPP
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDragDrawingUPP |
| Carbon status: | Supported |
DragDrawingUPP NewDragDrawingUPP (
DragDrawingProcPtr userRoutine
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDragInputUPP |
| Carbon status: | Supported |
DragInputUPP NewDragInputUPP (
DragInputProcPtr userRoutine
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDragReceiveHandlerUPP |
| Carbon status: | Supported |
DragReceiveHandlerUPP NewDragReceiveHandlerUPP (
DragReceiveHandlerProcPtr userRoutine
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDragSendDataUPP |
| Carbon status: | Supported |
DragSendDataUPP NewDragSendDataUPP (
DragSendDataProcPtr userRoutine
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDragTrackingHandlerUPP |
| Carbon status: | Supported |
DragTrackingHandlerUPP NewDragTrackingHandlerUPP (
DragTrackingHandlerProcPtr userRoutine
);
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragAllowableActions |
| Carbon status: | Under evaluation |
OSStatus SetDragAllowableActions (
DragRef theDrag,
DragActions inActions,
Boolean isLocal
);
A result code.
Available in Mac OS X, version 10.0 and later.
SetDragDropAction |
| Carbon status: | Under evaluation |
OSStatus SetDragDropAction (
DragRef theDrag,
DragActions inAction
);
A result code.
Available in Mac OS X, version 10.0 and later.
SetDragImage |
| Carbon status: | Supported |
OSErr SetDragImage (
DragRef theDrag,
PixMapHandle imagePixMap,
RgnHandle imageRgn,
Point imageOffsetPt,
DragImageFlags theImageFlags
);
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InstallTrackingHandler |
| Carbon status: | Supported |
Installs a tracking handler function for one or all of your application’s windows.
OSErr InstallTrackingHandler (
DragTrackingHandlerUPP trackingHandler,
WindowRef theWindow,
void *handlerRefCon
);
A pointer to a tracking handler function. Installing a tracking handler function allows your application to track the user’s movements through your application’s windows during a drag.
A pointer to the window for which to track and handle dragging. When the cursor moves into this window during a drag, the Drag Manager sends tracking messages to the tracking handler function. If you pass NULL, the tracking handler function is installed in the default handler space for your application. Tracking handler functions installed in this way are called when the user moves the mouse over any window that belongs to your application. You may install more than one drag tracking handler on a single window.
A pointer to a reference constant that will be forwarded to your tracking handler function when it is called by the Drag Manager. Use this constant to pass any data you wish to forward to your tracking handler function.
A result code.
The Drag Manager sequentially calls all of the tracking handler functions installed for a window when the user moves the cursor over that window during a drag.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
InstallReceiveHandler |
| Carbon status: | Supported |
Installs a receive handler function for one or all of your application’s windows.
OSErr InstallReceiveHandler (
DragReceiveHandlerUPP receiveHandler,
WindowRef theWindow,
void *handlerRefCon
);
A pointer to a receive handler function. Installing a receive handler function allows your application to accept a drag by getting drag item flavor data from the Drag Manager when the user releases the mouse button while dragging over one of your application’s windows.
A pointer to the window for which to install the receive handler. When a drop occurs over this window, the Drag Manager calls your receive handler function to allow your application to accept the drag. If you pass NULL, the receive handler function is installed in the default handler space for your application. Receive handler functions installed in this way are called when a drop occurs over any window that belongs to your application. You may install more than one receive handler function on a single window.
A pointer to a reference constant that will be forwarded to your receive handler function when it is called by the Drag Manager. Use this constant to pass any data you wish to forward to your drag receive handler.
A result code.
The Drag Manager sequentially calls all of the receive handler functions installed on a window when a drop occurs in that window.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
RemoveTrackingHandler |
| Carbon status: | Supported |
Removes a tracking handler function from one or all of your application’s windows.
OSErr RemoveTrackingHandler (
DragTrackingHandlerUPP trackingHandler,
WindowRef theWindow
);
A pointer to the tracking handler function to be removed.
A pointer to the window from which to remove the drag tracking handler function. Pass NULL to remove the specified tracking handler function from the default handler space for your application.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
RemoveReceiveHandler |
| Carbon status: | Supported |
Removes a receive handler function from one or all of your application’s windows.
OSErr RemoveReceiveHandler (
DragReceiveHandlerUPP receiveHandler,
WindowRef theWindow
);
A pointer to a receive handler function.
A pointer to the window from which to remove the receive handler function. Pass NULL to remove the specified receive handler function from the default handler space for your application.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
NewDrag |
| Carbon status: | Supported |
Creates a new drag reference for your application to use with the Drag Manager.
OSErr NewDrag (
DragRef *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.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DisposeDrag |
| Carbon status: | Supported |
Disposes of a drag reference and its associated data.
OSErr DisposeDrag (
DragRef 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.
A result code.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
AddDragItemFlavor |
| Carbon status: | Supported |
Creates a drag item and adds a flavor to a drag item.
OSErr AddDragItemFlavor (
DragRef theDrag,
DragItemRef theItemRef,
FlavorType theType,
const void *dataPtr,
Size dataSize,
FlavorFlags theFlags
);
A drag reference.
The drag item to add the flavor to. You create a new drag item by providing a unique item reference number here. You add a flavor to an existing item by using the same item reference number as in a previous call. You may use any item reference number when adding a flavor to an item. Item reference numbers do not need to be specified in order, nor must they be sequential. In many cases it is easiest to use index numbers as item reference numbers (1, 2, 3...). Item reference numbers are only used as unique “key” numbers for each item. Depending on your application, it might be easier to use your own internal memory addresses as item reference numbers (as long as each item being dragged has a unique item reference number).
The data type of the flavor to add. This may be any four-character scrap type. You may use your application’s signature for a unique type for internal use. You must add all of the drag item flavors to a drag item before calling the TrackDrag function. Once the TrackDrag function is called, receiving applications may not operate properly if new drag items or drag item flavors are added.
A pointer to the flavor data to add. Pass NULL to defer the creation of a particular data type until a receiver has specifically requested it. Flavors that are added by passing NULL cause the Drag Manager to call the drag’s send data function when the flavor is requested to get the data from your application.
The size, in bytes, of the flavor data to add.
The set of attributes to set for this flavor.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragItemFlavorData |
| Carbon status: | Supported |
Sets the data or part of the data contained within an existing flavor.
OSErr SetDragItemFlavorData (
DragRef theDrag,
DragItemRef theItemRef,
FlavorType theType,
const void *dataPtr,
Size dataSize,
UInt32 dataOffset
);
The drag reference whose flavor data will be set.
The drag item reference of the item that contains the flavor you wish to set all or part of the data for. The data pointed to by the dataPtr function with the size specified in the dataSize function is placed into the flavor structure at the offset specified by the dataOffset function.
The data type of the existing flavor for which all or part of the data will be set.
A pointer to the flavor data.
The size, in bytes, of the flavor data.
The offset, in bytes, into the flavor structure to place the data specified by the dataPtr function and the dataSize function parameters.
A result code.
This function is commonly used in situations where a flavor’s data is not added to the flavor when the flavor is created using the AddDragItemFlavor function. When the sender's drag send data function is called, the SetDragItemFlavorData function can be used to provide the requested data to the Drag Manager. This method is useful when the data needs to be translated by the sender and it would be expensive to compute the data before required.
Unlike the functions that add flavors, this function may be called both before and during a drag.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragSendProc |
| Carbon status: | Supported |
Sets the send data function for the Drag Manager to use with a particular drag.
OSErr SetDragSendProc (
DragRef theDrag,
DragSendDataUPP sendProc,
void *dragSendRefCon
);
The drag reference to set the send data function for.
The send data function that will be called by the Drag Manager when the receiver of a drop requests the flavor data of a flavor that has not been cached by the Drag Manager.
A pointer to a reference constant that will be forwarded to your send data function when it is called by the Drag Manager. Use this constant to pass any data you wish to forward to your send data function.
A result code.
The Drag Manager caches drag item flavor data when the flavor is added to a drag by calling the AddDragItemFlavor function. If NULL is passed to the AddDragItemFlavor function as the data pointer, the flavor data is not cached and the Drag Manager will call your send data function when the drag item flavor data is requested.
You do not need to provide a send data function if your application never passes NULL to the AddDragItemFlavor function when adding a drag item flavor to a drag.
Details for how to write a send data function are covered in the “Drag Manager Callbacks” section.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragInputProc |
| Carbon status: | Supported |
Sets the drag input function for the Drag Manager to use with a particular drag.
OSErr SetDragInputProc (
DragRef theDrag,
DragInputUPP inputProc,
void *dragInputRefCon
);
The drag reference for which the drag input function will be set.
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.
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.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragDrawingProc |
| Carbon status: | Supported |
Sets the drag drawing function for the Drag Manager to use with a particular drag.
OSErr SetDragDrawingProc (
DragRef theDrag,
DragDrawingUPP drawingProc,
void *dragDrawingRefCon
);
The drag reference for which the drag drawing function will be set.
The drag drawing function to be called by the Drag Manager to draw, move, and hide the “dotted outline” drag feedback on the screen during a drag.Your drag drawing function can implement any type of drag feedback, such as dragging a bitmap of the object being dragged. Details for how to write a drag drawing function are covered in the “Drag Manager Callbacks” section.
A pointer to a reference constant that will be forwarded to your drag drawing function when it is called by the Drag Manager. Use this constant to pass any data you wish to forward to your drag drawing function.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
TrackDrag |
| Carbon status: | Supported |
Drags an item or collection of items from your application.
OSErr TrackDrag (
DragRef theDrag,
const EventRecord *theEvent,
RgnHandle theRegion
);
A drag reference for performing the drag operation.
A pointer to the mouseDown event record that your application received that resulted in starting a drag.
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 using calling the PaintRgn function(not the FrameRgn function).
A result code.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
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.
CountDragItems |
| Carbon status: | Supported |
Gets the number of drag items that are contained in a drag reference.
OSErr CountDragItems (
DragRef theDrag,
UInt16 *numItems
);
The drag reference.
On return, a pointer to the number of drag items in the specified drag reference.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragItemReferenceNumber |
| Carbon status: | Supported |
Gets the item reference number of a specific item in a drag reference.
OSErr GetDragItemReferenceNumber (
DragRef theDrag,
UInt16 index,
DragItemRef *theItemRef
);
The drag reference.
The index of an item in a drag for which to get the item reference.
A pointer to the item reference number of the item with the specified index.
A result code. If index is 0 or larger than the number of items in the drag, the badDragItemErr result code is returned.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
CountDragItemFlavors |
| Carbon status: | Supported |
Gets the number of drag item flavors that are contained within a drag item.
OSErr CountDragItemFlavors (
DragRef theDrag,
DragItemRef theItemRef,
UInt16 *numFlavors
);
The drag reference.
An item reference number.
On return, a pointer to the number of drag item flavors in the specified drag item. When the CountDragItemFlavors function is called by an application other than the sender, the flavors that are marked with the flavorSenderOnly flavor flag are not included in the count.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetFlavorType |
| Carbon status: | Supported |
Gets the type of a specific flavor in a drag item.
OSErr GetFlavorType (
DragRef theDrag,
DragItemRef theItemRef,
UInt16 index,
FlavorType *theType
);
A drag reference.
An item reference number.
The index of the desired flavor item.
On return, a pointer to the type of the specified flavor. If a flavor is marked with the flavorSenderOnly flavor flag, it is not returned to any application other than the sender.
A result code. If index is 0 or larger than the number of flavors in the item, the badDragFlavorErr result code is returned.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetFlavorFlags |
| Carbon status: | Supported |
Gets the flags for a specific flavor in a drag item.
OSErr GetFlavorFlags (
DragRef theDrag,
DragItemRef theItemRef,
FlavorType theType,
FlavorFlags *theFlags
);
A drag reference.
An item reference number.
The flavor type for which to get the attributes.
On return, a pointer to the attributes of the specified flavor. If a flavor is marked with the flavorSenderOnly flavor flag, it is not returned to any application other than the sender.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetFlavorDataSize |
| Carbon status: | Supported |
Gets the size of the flavor data for a specific flavor in a drag item.
OSErr GetFlavorDataSize (
DragRef theDrag,
DragItemRef theItemRef,
FlavorType theType,
Size *dataSize
);
A drag reference.
An item reference number.
The flavor type for which to get the size.
On return, a pointer to the size of the specified drag item flavor data.
A result code.
Note that calling the GetFlavorDataSize function on a flavor that requires translation will force that translation be performed in order to determine the data size. Since translation may require a significant amount of time and memory during processing, call the GetFlavorDataSize function only when necessary.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetFlavorData |
| Carbon status: | Supported |
Gets all or part of the flavor data for a specific flavor in a drag item.
OSErr GetFlavorData (
DragRef theDrag,
DragItemRef theItemRef,
FlavorType theType,
void *dataPtr,
Size *dataSize,
UInt32 dataOffset
);
A drag reference.
An item reference number.
Specifies where to copy the requested flavor data. Your application is responsible for allocating the memory for the flavor data and for setting the dataSize parameter to the number of bytes that you have allocated for the data.
A pointer to the data buffer for which you have allocated memory. On return, the buffer contains the requested flavor data.
On input, a pointer to the size of the data (in bytes) that you have allocated memory for and wish to receive from the flavor. On return, a pointer to the actual number of bytes copied into the buffer specified by the dataPtr parameter. If you specify a dataSize that is smaller than the amount of data in the flavor, the data is copied into your buffer and, on return, the dataSize parameter is unchanged. If you specify a dataSize that is larger than the amount of data in the flavor, only the amount of data in the flavor is copied into your buffer and, on return, the dataSize parameter will contain the actual number of bytes copied. You have reached the end of the flavor’s data when the dataSize parameter points to a number of bytes lower than you provided. If you wish to receive the flavor data in smaller pieces than the entire size of the data, you can set the dataSize parameter to be as large as your buffer and call the GetFlavorData function multiple times while incrementing the dataOffset parameter by the size of your buffer.If the dataOffset parameter was larger than the amount of data contained within the flavor, 0 (zero) will be returned in the number pointed to by the dataSize parameter indicating that no data was copied into your buffer.
A pointer to the offset (in bytes) within the flavor structure to begin copying data.
A result code.
You can first determine the size of a flavor’s data by calling the GetFlavorDataSize function.
Note that calling the GetFlavorData function on a flavor that requires translation will force that translation to occur in order to return the data.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragItemBounds |
| Carbon status: | Supported |
Gets the bounding rectangle of a drag item.
OSErr GetDragItemBounds (
DragRef theDrag,
DragItemRef theItemRef,
Rect *itemBounds
);
A drag reference.
An item reference number.
On return, a pointer to the bounding rectangle (relative to the current pinned mouse position) of the specified item in global coordinates.
A result code.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragItemBounds |
| Carbon status: | Supported |
Sets the bounding rectangle of a drag item.
OSErr SetDragItemBounds (
DragRef theDrag,
DragItemRef theItemRef,
const Rect *itemBounds
);
A drag reference.
An item reference number.
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.
A result code.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragAttributes |
| Carbon status: | Supported |
Gets the current set of drag attribute flags.
OSErr GetDragAttributes (
DragRef theDrag,
DragAttributes *flags
);
A drag reference.
On return, a pointer to the drag attribute flags for the specified drag reference in the attributes parameter.
A result code.
If the GetDragAttributes function is called during a drag, the current set of DragAttributes is returned. If the GetDragAttributes function is called after a drag, the set of DragAttributes that were set at drop time is returned.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragMouse |
| Carbon status: | Supported |
Gets the current mouse and pinned mouse locations.
OSErr GetDragMouse (
DragRef theDrag,
Point *mouse,
Point *globalPinnedMouse
);
A drag reference.
On return, a pointer to 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.
On return, a pointer to 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 pinnedMouse location is different from the mouse location when the cursor is being constrained in either dimension by a tracking handler.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDragMouse |
| Carbon status: | Supported |
Sets the current pinned mouse location.
OSErr SetDragMouse (
DragRef theDrag,
Point globalPinnedMouse
);
A drag reference.
The pinned mouse location in global screen coordinates is used to draw the drag region on the screen.
A result code.
To constrain the mouse within one of your application’s windows, call the SetDragMouse function from within your tracking handler when you receive the dragTrackingInWindow messages. The Drag Manager updates the position of the drag region on the screen after each time your tracking handlers are called.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragOrigin |
| Carbon status: | Supported |
Gets the mouseDown parameter location that started the given drag.
OSErr GetDragOrigin (
DragRef theDrag,
Point *globalInitialMouse
);
A drag reference.
On return, a pointer to the mouseDown parameter location that started the drag in global screen coordinates, whether or not the drag has completed.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDragModifiers |
| Carbon status: | Supported |
Gets the current set of keyboard modifiers.
OSErr GetDragModifiers (
DragRef theDrag,
SInt16 *modifiers,
SInt16 *mouseDownModifiers,
SInt16 *mouseUpModifiers
);
A drag reference.
On return, a pointer to 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.
On return, a pointer to 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.
On return, a pointer to 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.
A result code.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
GetDropLocation |
| Carbon status: | Supported |
Gets the AppleEvent function descriptor of the drop location.
OSErr GetDropLocation (
DragRef theDrag,
AEDesc *dropLocation
);
A drag reference.
On return, a pointer to the AppleEvent function descriptor of the drop location. The drop location is only valid after the receiver has set the drop location by calling the SetDropLocation function. If the destination is in the Finder, the drop location will be an alias to the location in the file system that received the drag. If the receiver of the drag has not set a drop location by calling the SetDropLocation function, typeNull will be returned.
A result code.
The GetDropLocation function may be called both during a drag as well as after a drag has completed.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
SetDropLocation |
| Carbon status: | Supported |
Sets the AppleEvent descriptor for the drop location of a drag.
OSErr SetDropLocation (
DragRef theDrag,
const AEDesc *dropLocation
);
A drag reference.
A pointer to the AppleEvent descriptor of the drop location to set.
A result code.
This function is typically called by a receive handler before attempting to get any flavor data by using the GetFlavorDataSize or GetFlavorData functions. When a sender application's drag send data function is called to provide flavor data to a receiver, the GetDropLocation function can then be called to determine the drop location while providing data to the sender.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
ShowDragHilite |
| Carbon status: | Supported |
Highlights an area of your window during a drag.
OSErr ShowDragHilite (
DragRef theDrag,
RgnHandle hiliteFrame,
Boolean inside
);
The drag reference of the drag currently in progress.
A QuickDraw region of the frame of the window, pane, or shape you wish to highlight, in the window’s local coordinate system.
Pass true to draw the highlighting inside the frame shape. Otherwise it will be drawn outside the frame shape. Note that in either case, the highlight will not include the boundary edge of the frame. This allows you to highlight inside a window frame or a pane, or to highlight outside of a container or object in your window.
A result code.
The ShowDragHilite function creates a standard drag and drop highlight in your window. Your tracking handler function should call this if a drop is allowed at the current mouse position.
You can only have one highlight showing at a time, and if you call this function when a highlight is currently visible, the first one is removed before the newly requested highlight is shown.
The ShowDragHilite function uses a two pixel thick line when drawing the highlight.
The ShowDragHilite function assumes that the highlighting should be drawn in the current port. Your application should make sure that the correct port is set before calling the ShowDragHilite function . Also, highlighting drawn by the ShowDragHilite function is clipped to the current port. Make sure that the port’s clip region is appropriately sized to draw the highlighting.
The Drag Manager maintains the currently highlighted portion of your window if you use the HideDragHilite and UpdateDragHilite functions. If you intend to scroll the window that contains the highlighting, you can use the DragPreScroll and DragPostScroll functions to properly update the drag highlighting.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
HideDragHilite |
| Carbon status: | Supported |
Removes highlighting created with the ShowDragHilite function.
OSErr HideDragHilite (
DragRef theDrag
);
The drag reference that is currently showing a drag highlight.
A result code.
The HideDragHilite function assumes that the highlighting should be erased from the current port. Your application should make sure that the correct port is set before calling the HideDragHilite function. Also, highlighting erased by the HideDragHilite function is clipped to the current port. Make sure that the port’s clip region is appropriately sized to remove the highlighting.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DragPreScroll |
| Carbon status: | Supported |
Prepares your window or pane for scrolling.
OSErr DragPreScroll (
DragRef theDrag,
SInt16 dH,
SInt16 dV
);
The drag reference.
The horizontal distance you intend to scroll.
The vertical distance you intend to scroll.
A result code.
Removes any drag highlighting that would be scrolled away from the hiliteFrame specified to the ShowDragHilite function when scrolling part of your window while drag highlighting is showing. Use this function if you plan to scroll part of your window using the ScrollRect or CopyBits functions.
Scrolling part of your window may inadvertently move part of the drag highlighting with it. The DragPreScroll function is optimized to remove from the screen only the parts of the highlighting that will be scrolled away from the hiliteFrame region. After calling the DragPreScroll function with the dH and dV that you are going to scroll, you can then scroll your window followed by a call to the DragPostScroll function which redraws any necessary highlighting after the scroll.
If you use an offscreen port to draw your window into while scrolling, it is recommended that you simply use the HideDragHilite and ShowDragHilite functions to preserve drag highlighting in your offscreen port. The DragScroll functions are optimized for onscreen scrolling.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
DragPostScroll |
| Carbon status: | Supported |
Restores the drag highlight after scrolling part of your window.
OSErr DragPostScroll (
DragRef theDrag
);
The drag reference.
A result code.
The DragPostScroll function restores the drag highlight after scrolling part of your window. This function must be called following each call to the DragPreScroll function and any subsequent scrolling.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
UpdateDragHilite |
| Carbon status: | Supported |
Updates the portion of the drag highlight that was drawn over by your application.
OSErr UpdateDragHilite (
DragRef theDrag,
RgnHandle updateRgn
);
The drag reference.
The region that needs to be updated, typically the port’s updateRgn..
A result code.
Use this function if your application draws into the highlighted portion of your window during a drag. For example, dragging over a folder icon in the Finder causes the Finder to redraw the folder icon in its darkened (selected) color. The Finder calls the UpdateDragHilite function to redraw any portion of the drag highlight that may have intersected with the folder icon.
You must guarantee, however, that any current highlighting within the updateRgn thingee has been completely erased or is clipped out. If this function is asked to highlight over an area which is still highlighted, it will be redrawn incorrectly.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
WaitMouseMoved |
| Carbon status: | Supported |
Returns true if a mouse movement is the beginning of a drag.
Boolean WaitMouseMoved (
Point initialMouse
);
The point where a mouseDown event occurred in global screen coordinates.
True if the mouse moves away from the initialMouse location before the mouse button is released, otherwise false.
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.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
ZoomRects |
| Carbon status: | Supported |
Animates a rectangle into a second rectangle.
OSErr ZoomRects (
const Rect *fromRect,
const Rect *toRect,
SInt16 zoomSteps,
ZoomAcceleration acceleration
);
A pointer to the starting rectangle to animate from, in global coordinates.
A pointer to the ending rectangle to animate to, in global coordinates.
Specifies the number of animation steps to be shown between the source and destination rectangles. The minimum number of steps is 4. If less than 4 steps are specified, 4 will be used. The maximum number of steps is 25. If more than 25 steps are specified, 25 will be used.
Specifies how the intermediate animation steps will be calculated. Using the zoomNoAcceleration constant makes the distance between steps from the source to the destination equal. Using the zoomAccelerate constant makes each step from the source to the destination increasingly larger, making the animation appear to speed up as it approaches the destination. Using the zoomDecelerate constant makes each step from the source to the destination smaller, making the animation appear to slow down as it approaches the destination.
A result code.
The ZoomRects function animates a movement between two rectangles on the screen. It does this by drawing gray dithered rectangles incrementally toward the destination rectangle.
The ZoomRects function draws on the entire screen, outside of the current port. It does not change any pixels on the screen except during the animation. It also preserves the current port and the port’s settings.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
ZoomRegion |
| Carbon status: | Supported |
Animates a region’s outline from one screen location to another.
OSErr ZoomRegion (
RgnHandle region,
Point zoomDistance,
SInt16 zoomSteps,
ZoomAcceleration acceleration
);
The region to animate.
The horizontal and vertical distance from the starting point that the region will animate to.
Specifies the number of animation steps to be shown between the source and destination rectangles. The minimum number of steps is 4. If less than 4 steps are specified, 4 will be used. The maximum number of steps is 25. If more than 25 steps are specified, 25 will be used.
Specifies how the intermediate animation steps will be calculated. Using the zoomNoAcceleration constant makes the distance between steps from the source to the destination equal. Using the zoomAccelerate constant makes each step from the source to the destination increasingly larger, making the animation appear to speed up as it approaches the destination. Using the zoomDecelerate constant makes each step from the source to the destination smaller, making the animation appear to slow down as it approaches the destination.
A result code.
The ZoomRegion function animates a region from one location to another on the screen. It does this by drawing gray dithered regions incrementally toward the destination region.
The ZoomRegion function draws on the entire screen, outside of the current port. It does not change any pixels on the screen except during its animation. It also preserves the current port and the port’s settings.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2001 Apple Computer, Inc. (Last Updated July 17, 2001)