ADC Home > Reference Library > Reference > Carbon > Interapplication Communication > Drag Manager Reference >

< Previous PageNext Page > Hide TOC

Deprecated Drag Manager Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in Mac OS X v10.4

SetDragImage

Associates an image with a drag reference. (Deprecated in Mac OS X v10.4. Use SetDragImageWithCGImage instead.)

OSErr SetDragImage (
   DragRef inDrag,
   PixMapHandle inImagePixMap,
   RgnHandle inImageRgn,
   Point inImageOffsetPt,
   DragImageFlags inImageFlags
);

Parameters
theDrag

The drag reference.

imagePixMap

A handle to a PixMap describing the image. The Drag Manager temporarily locks the PixMapHandle during the drag. The Drag Manager does not copy the information in this parameter; you must ensure that the data to which this parameter refers continues to exist until TrackDrag completes.

imageRgn

A mask describing the portion of the PixMap contained in the imagePixMap parameter which contains the drag image. Pass NULL for imageRgn if the entire PixMap, including white space, should be dragged.

The Drag Manager does not copy the imageRgn parameter data. Until TrackDrag completes or SetDragImage is called again to update the image, you must ensure that the data to which this parameter refers continues to exist.

Don't confuse the region passed to the function TrackDrag and that passed to the SetDragImage function. The former is what's drawn to the screen during dragging, while the latter is used only for drawing the correct portion of the drag image.

imageOffsetPt

The offset required to move the PixMap specified in the imagePixMap parameter to the global coordinates where the image initially appears. If this parameter is (0,0), the PixMap should already be in global coordinates.

theImageFlags

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

The sending application should call SetDragImage prior to calling TrackDrag. Prior to calling SetDragImage, the application should draw a solid, opaque image into the PixMap specified in the imagePixMap parameter. The Drag Manager will provide translucency effects. Your application can obtain a PixMap by calling the QuickDraw function GetGWorldPixMap and supplying a GWorld into which your application has drawn the image.

To allow the Drag Manager to analyze the PixMap’s colors in order to determine if it can be rendered on the available screens, Apple recommends using an 8-bit GWorld for the PixMap.

Special Considerations

SetDragImage installs a custom drawing procedure to do the translucent drawing. Applications calling SetDragImage should not also call SetDragDrawingProc for the same drag.

Availability
Declared In
Drag.h

Deprecated in Mac OS X v10.5

AddDragItemFlavor

Adds a flavor to a drag item, creating a new item if necessary. (Deprecated in Mac OS X v10.5.)

OSErr AddDragItemFlavor (
   DragRef theDrag,
   DragItemRef theItemRef,
   FlavorType theType,
   const void *dataPtr,
   Size dataSize,
   FlavorFlags theFlags
);

Parameters
theDrag

A drag reference.

theItemRef

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

theType

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.

dataPtr

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. If you pass NULL, a promise is added to the drag; when the flavor is requested, the Drag Manager calls the drag’s send data function to get the data from your application.

Note that this method of setting promises differs from the method of setting Scrap Manager promises. See the Scrap Manager function PutScrapFlavor for more information.

dataSize

The size, in bytes, of the flavor data to add. If you pass NULL in the dataPtr parameter, the value in this parameter is ignored.

theFlags

The set of attributes to set for this flavor.

Return Value

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

Availability
Declared In
Drag.h

CountDragItemFlavors

Gets the number of flavors that are contained within a drag item. (Deprecated in Mac OS X v10.5.)

OSErr CountDragItemFlavors (
   DragRef theDrag,
   DragItemRef theItemRef,
   UInt16 *numFlavors
);

Parameters
theDrag

The drag reference.

theItemRef

An item reference number.

numFlavors

On return, a pointer to the number of 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 flag are not included in the count.

Return Value

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

Availability
Declared In
Drag.h

CountDragItems

Gets the number of drag items that are contained in a drag reference. (Deprecated in Mac OS X v10.5.)

OSErr CountDragItems (
   DragRef theDrag,
   UInt16 *numItems
);

Parameters
theDrag

The drag reference.

numItems

On return, a pointer to the number of drag items in the specified drag reference.

Return Value

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

Availability
Declared In
Drag.h

DisposeDragDrawingUPP

Disposes of the universal procedure pointer (UPP) to a drag drawing callback. (Deprecated in Mac OS X v10.5.)

void DisposeDragDrawingUPP (
   DragDrawingUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Drag.h

DisposeDragReceiveHandlerUPP

Disposes of the universal procedure pointer (UPP) to a drag receive handler. (Deprecated in Mac OS X v10.5.)

void DisposeDragReceiveHandlerUPP (
   DragReceiveHandlerUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Drag.h

DisposeDragSendDataUPP

Disposes of the universal procedure pointer (UPP) to a drag send data callback. (Deprecated in Mac OS X v10.5.)

void DisposeDragSendDataUPP (
   DragSendDataUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Drag.h

DisposeDragTrackingHandlerUPP

Disposes of the universal procedure pointer (UPP) to a drag tracking handler. (Deprecated in Mac OS X v10.5.)

void DisposeDragTrackingHandlerUPP (
   DragTrackingHandlerUPP userUPP
);

Parameters
userUPP

The UPP to dispose of.

Availability
Declared In
Drag.h

DragPostScroll

Restores the drag highlight after scrolling part of your window. (Deprecated in Mac OS X v10.5.)

OSErr DragPostScroll (
   DragRef theDrag
);

Parameters
theDrag

The drag reference.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

DragPreScroll

Prepares your window or pane for scrolling. (Deprecated in Mac OS X v10.5.)

OSErr DragPreScroll (
   DragRef theDrag,
   SInt16 dH,
   SInt16 dV
);

Parameters
theDrag

The drag reference.

dH

The horizontal distance you intend to scroll.

dV

The vertical distance you intend to scroll.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

GetDragHiliteColor

Returns the drag highlight color for a window. (Deprecated in Mac OS X v10.5.)

OSErr GetDragHiliteColor (
   WindowRef window,
   RGBColor *color
);

Parameters
window

The window for which to return the drag highlight color.

color

On return, a pointer to the highlight color.

Return Value

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

Discussion

Use the GetDragHiliteColor function to determine the color the Drag Manager will use for a particular window. GetDragHiliteColor can safely be called when the gestaltDragMgrHasImageSupport bit is set in the Gestalt response to the selector gestaltDragMgrAttr. For more information on the gestaltDragMgrAttr selector, see Inside Mac OS X: Gestalt Manager Reference.

The Drag Manager chooses an appropriate color for highlighting, based on the color used for drag highlighting in the current Appearance Manager theme.

Availability
Declared In
Drag.h

GetDragItemReferenceNumber

Gets the reference number of a specific item in a drag reference. (Deprecated in Mac OS X v10.5.)

OSErr GetDragItemReferenceNumber (
   DragRef theDrag,
   UInt16 index,
   DragItemRef *theItemRef
);

Parameters
theDrag

The drag reference.

index

The index of an item in a drag for which to get the reference.

theItemRef

On return, a pointer to the reference number of the item with the specified index.

Return Value

A result code. See “Drag Manager Result Codes.” If index is 0 or larger than the number of items in the drag, GetDragItemReferenceNumber returns the badDragItemErr result code.

Availability
Declared In
Drag.h

GetDropLocation

Gets the Apple Event descriptor of the drop location. (Deprecated in Mac OS X v10.5.)

OSErr GetDropLocation (
   DragRef theDrag,
   AEDesc *dropLocation
);

Parameters
theDrag

A drag reference.

dropLocation

On return, a pointer to the Apple Event 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.

Return Value

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

Discussion

The GetDropLocation function may be called both during a drag as well as after a drag has completed.

Availability
Declared In
Drag.h

GetFlavorData

Gets all or part of the data for a specific flavor in a drag item. (Deprecated in Mac OS X v10.5.)

OSErr GetFlavorData (
   DragRef theDrag,
   DragItemRef theItemRef,
   FlavorType theType,
   void *dataPtr,
   Size *dataSize,
   UInt32 dataOffset
);

Parameters
theDrag

A drag reference.

theItemRef

The reference number of the drag item containing the flavor data.

theType

The flavor type of the flavor to get the data from.

dataPtr

A pointer to a data buffer. On return, the buffer contains 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.

dataSize

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 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 the dataSize parameter contains, on return, 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 is 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.

dataOffset

A pointer to the offset (in bytes) within the flavor structure at which to begin copying data.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

GetFlavorDataSize

Gets the size of the data for a specific flavor in a drag item. (Deprecated in Mac OS X v10.5.)

OSErr GetFlavorDataSize (
   DragRef theDrag,
   DragItemRef theItemRef,
   FlavorType theType,
   Size *dataSize
);

Parameters
theDrag

A drag reference.

theItemRef

The reference number of the drag item containing the flavor.

theType

The flavor type for which to get the size of the data.

dataSize

On return, a pointer to the size of the data for the specified drag item flavor.

Return Value

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

Discussion

Note that calling the GetFlavorDataSize function on a flavor that requires translation will force that translation to 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.

Availability
Declared In
Drag.h

GetFlavorFlags

Gets the flags for a specific flavor in a drag item. (Deprecated in Mac OS X v10.5.)

OSErr GetFlavorFlags (
   DragRef theDrag,
   DragItemRef theItemRef,
   FlavorType theType,
   FlavorFlags *theFlags
);

Parameters
theDrag

A drag reference.

theItemRef

The reference number of the drag item containing the flavor.

theType

The flavor type for which to get the attributes.

theFlags

On return, a pointer to the attributes of the specified flavor. If a flavor is marked with the flavorSenderOnly flag, it is not returned to any application other than the sender.

Return Value

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

Availability
Declared In
Drag.h

GetFlavorType

Gets the type of a specific flavor in a drag item. (Deprecated in Mac OS X v10.5.)

OSErr GetFlavorType (
   DragRef theDrag,
   DragItemRef theItemRef,
   UInt16 index,
   FlavorType *theType
);

Parameters
theDrag

A drag reference.

theItemRef

The reference number of the drag item containing the flavor.

index

The index of the desired flavor.

theType

On return, a pointer to the type of the specified flavor. If a flavor is marked with the flavorSenderOnly flag, it is not returned to any application other than the sender.

Return Value

A result code. See “Drag Manager Result Codes.” If index is 0 or larger than the number of flavors in the item, GetFlavorType returns the badDragFlavorErr result code.

Availability
Declared In
Drag.h

GetStandardDropLocation

Gets the standard drop location set by the receiver of a drag. (Deprecated in Mac OS X v10.5.)

OSStatus GetStandardDropLocation (
   DragRef theDrag,
   StandardDropLocation *outDropLocation
);

Parameters
theDrag

The drag reference.

outDropLocation

A pointer to a value that, on return, represents the location where the drag was dropped. You can use the GetStandardDropLcoation function to easily determine whether a drag landed in the trash; if the drop location is the trash, the value of this parameter is kDragStandardDropLocationTrash. Otherwise, the value returned here is kDragStandardDropLocationUnknown. See “Standard Drop Locations” for more information on these values.

Return Value

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

Availability
Declared In
Drag.h

HideDragHilite

Removes highlighting created with the ShowDragHilite function. (Deprecated in Mac OS X v10.5.)

OSErr HideDragHilite (
   DragRef theDrag
);

Parameters
theDrag

The drag reference that is currently showing a drag highlight.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

InstallReceiveHandler

Installs a receive handler function for one or all of your application’s windows. (Deprecated in Mac OS X v10.5.)

OSErr InstallReceiveHandler (
   DragReceiveHandlerUPP receiveHandler,
   WindowRef theWindow,
   void *handlerRefCon
);

Parameters
receiveHandler

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.

theWindow

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

handlerRefCon

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.

Return Value

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

Discussion

The Drag Manager sequentially calls all of the receive handler functions installed on a window when a drop occurs in that window.

Availability
Declared In
Drag.h

InstallTrackingHandler

Installs a tracking handler function for one or all of your application’s windows. (Deprecated in Mac OS X v10.5.)

OSErr InstallTrackingHandler (
   DragTrackingHandlerUPP trackingHandler,
   WindowRef theWindow,
   void *handlerRefCon
);

Parameters
trackingHandler

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.

theWindow

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

handlerRefCon

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.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

InvokeDragDrawingUPP

Calls your drag drawing callback. (Deprecated in Mac OS X v10.5.)

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

Return Value

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

Discussion

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

Availability
Declared In
Drag.h

InvokeDragReceiveHandlerUPP

Calls your drag receive handler. (Deprecated in Mac OS X v10.5.)

OSErr InvokeDragReceiveHandlerUPP (
   WindowRef theWindow,
   void *handlerRefCon,
   DragRef theDrag,
   DragReceiveHandlerUPP userUPP
);

Return Value

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

Discussion

You should not need to use the function InvokeDragReceiveHandlerUPP, as the system calls your drag receive handler for you.

Availability
Declared In
Drag.h

InvokeDragSendDataUPP

Calls your drag send data callback. (Deprecated in Mac OS X v10.5.)

OSErr InvokeDragSendDataUPP (
   FlavorType theType,
   void *dragSendRefCon,
   DragItemRef theItemRef,
   DragRef theDrag,
   DragSendDataUPP userUPP
);

Return Value

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

Discussion

You should not need to use the function InvokeDragSendDataUPP, as the system calls your drag send data callback for you.

Availability
Declared In
Drag.h

InvokeDragTrackingHandlerUPP

Calls your drag tracking handler. (Deprecated in Mac OS X v10.5.)

OSErr InvokeDragTrackingHandlerUPP (
   DragTrackingMessage message,
   WindowRef theWindow,
   void *handlerRefCon,
   DragRef theDrag,
   DragTrackingHandlerUPP userUPP
);

Return Value

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

Discussion

You should not need to use the function InvokeDragTrackingHandlerUPP, as the system calls your drag tracking handler for you.

Availability
Declared In
Drag.h

NewDragDrawingUPP

Creates a new universal procedure pointer (UPP) to a drag drawing callback. (Deprecated in Mac OS X v10.5.)

DragDrawingUPP NewDragDrawingUPP (
   DragDrawingProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your drag drawing callback.

Return Value

On return, a UPP to the drag drawing callback. See the description of the DragDrawingUPP data type.

Availability
Declared In
Drag.h

NewDragReceiveHandlerUPP

Creates a new universal procedure pointer (UPP) to a drag receive handler. (Deprecated in Mac OS X v10.5.)

DragReceiveHandlerUPP NewDragReceiveHandlerUPP (
   DragReceiveHandlerProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your drag receive handler.

Return Value

On return, a UPP to the drag receive handler. See the description of the DragReceiveHandlerUPP data type.

Availability
Declared In
Drag.h

NewDragSendDataUPP

Creates a new universal procedure pointer (UPP) to a drag send data callback. (Deprecated in Mac OS X v10.5.)

DragSendDataUPP NewDragSendDataUPP (
   DragSendDataProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your drag send data callback.

Return Value

On return, a UPP to the drag send data callback. See the description of the DragSendDataUPP data type.

Availability
Declared In
Drag.h

NewDragTrackingHandlerUPP

Creates a new universal procedure pointer (UPP) to a drag tracking handler. (Deprecated in Mac OS X v10.5.)

DragTrackingHandlerUPP NewDragTrackingHandlerUPP (
   DragTrackingHandlerProcPtr userRoutine
);

Parameters
userRoutine

A pointer to your drag tracking handler.

Return Value

On return, a UPP to the drag tracking handler. See the description of the DragTrackingHandlerUPP data type.

Availability
Declared In
Drag.h

RemoveReceiveHandler

Removes a receive handler function from one or all of your application’s windows. (Deprecated in Mac OS X v10.5.)

OSErr RemoveReceiveHandler (
   DragReceiveHandlerUPP receiveHandler,
   WindowRef theWindow
);

Parameters
receiveHandler

A pointer to a receive handler function.

theWindow

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

Return Value

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

Availability
Declared In
Drag.h

RemoveTrackingHandler

Removes a tracking handler function from one or all of your application’s windows. (Deprecated in Mac OS X v10.5.)

OSErr RemoveTrackingHandler (
   DragTrackingHandlerUPP trackingHandler,
   WindowRef theWindow
);

Parameters
trackingHandler

A pointer to the tracking handler function to be removed.

theWindow

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

Return Value

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

Availability
Declared In
Drag.h

SetDragDrawingProc

Sets the drag drawing function for the Drag Manager to use with a particular drag. (Deprecated in Mac OS X v10.5.)

Not recommended

OSErr SetDragDrawingProc (
   DragRef theDrag,
   DragDrawingUPP drawingProc,
   void *dragDrawingRefCon
);

Parameters
theDrag

The drag reference for which the drag drawing function will be set.

drawingProc

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.

dragDrawingRefCon

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.

Return Value

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

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

SetDragItemFlavorData

Sets the data or part of the data contained within an existing flavor. (Deprecated in Mac OS X v10.5.)

OSErr SetDragItemFlavorData (
   DragRef theDrag,
   DragItemRef theItemRef,
   FlavorType theType,
   const void *dataPtr,
   Size dataSize,
   UInt32 dataOffset
);

Parameters
theDrag

The drag reference whose flavor data will be set.

theItemRef

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 parameter with the size specified in the dataSize parameter is placed into the flavor structure at the offset specified by the dataOffset parameter.

theType

The data type of the existing flavor for which all or part of the data will be set.

dataPtr

A pointer to the flavor data.

dataSize

The size, in bytes, of the flavor data.

dataOffset

The offset, in bytes, into the flavor structure at which to place the data specified by the dataPtr and the dataSize parameters.

Return Value

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

Discussion

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 it is required.

Unlike the functions that add flavors, this function may be called both before and during a drag.

Availability
Declared In
Drag.h

SetDragSendProc

Sets the send data function for the Drag Manager to use with a particular drag. (Deprecated in Mac OS X v10.5.)

OSErr SetDragSendProc (
   DragRef theDrag,
   DragSendDataUPP sendProc,
   void *dragSendRefCon
);

Parameters
theDrag

The drag reference to set the send data function for.

sendProc

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.

dragSendRefCon

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.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

SetDropLocation

Sets the Apple Event descriptor for the drop location of a drag. (Deprecated in Mac OS X v10.5.)

OSErr SetDropLocation (
   DragRef theDrag,
   const AEDesc *dropLocation
);

Parameters
theDrag

A drag reference.

dropLocation

A pointer to the Apple Event descriptor of the drop location to set.

Return Value

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

Discussion

This function is typically called by a receive handler before attempting to get any flavor data 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 be called to determine the drop location while providing data.

Availability
Declared In
Drag.h

SetStandardDropLocation

Used by the receiver of a drag to set the standard drop location for a drag. (Deprecated in Mac OS X v10.5.)

OSStatus SetStandardDropLocation (
   DragRef theDrag,
   StandardDropLocation dropLocation
);

Parameters
theDrag

The drag reference.

dropLocation

A value representing the location where the drag was dropped. See “Standard Drop Locations” 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

ShowDragHilite

Highlights an area of your window during a drag. (Deprecated in Mac OS X v10.5.)

OSErr ShowDragHilite (
   DragRef theDrag,
   RgnHandle hiliteFrame,
   Boolean inside
);

Parameters
theDrag

The drag reference of the drag currently in progress.

hiliteFrame

A QuickDraw region of the frame of the window, pane, or shape you wish to highlight, in the window’s local coordinate system.

inside

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.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

UpdateDragHilite

Updates the portion of the drag highlight that was drawn over by your application. (Deprecated in Mac OS X v10.5.)

OSErr UpdateDragHilite (
   DragRef theDrag,
   RgnHandle updateRgn
);

Parameters
theDrag

The drag reference.

updateRgn

The region that needs to be updated, typically the port’s updateRgn.

Return Value

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

Discussion

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

Availability
Declared In
Drag.h

ZoomRects

Animates a rectangle into a second rectangle. (Deprecated in Mac OS X v10.5.)

OSErr ZoomRects (
   const Rect *fromRect,
   const Rect *toRect,
   SInt16 zoomSteps,
   ZoomAcceleration acceleration
);

Parameters
fromRect

A pointer to the starting rectangle to animate from, in global coordinates.

toRect

A pointer to the ending rectangle to animate to, in global coordinates.

zoomSteps

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.

acceleration

Specifies how the intermediate animation steps will be calculated. Using the kZoomNoAcceleration constant makes the distance between steps from the source to the destination equal. Using the kZoomAccelerate 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 kZoomDecelerate constant makes each step from the source to the destination smaller, making the animation appear to slow down as it approaches the destination.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

ZoomRegion

Animates a region’s outline from one screen location to another. (Deprecated in Mac OS X v10.5.)

OSErr ZoomRegion (
   RgnHandle region,
   Point zoomDistance,
   SInt16 zoomSteps,
   ZoomAcceleration acceleration
);

Parameters
region

The region to animate.

zoomDistance

The horizontal and vertical distance from the starting point that the region will animate to.

zoomSteps

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.

acceleration

Specifies how the intermediate animation steps will be calculated. Using the kZoomNoAcceleration constant makes the distance between steps from the source to the destination equal. Using the kZoomAccelerate 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 kZoomDecelerate constant makes each step from the source to the destination smaller, making the animation appear to slow down as it approaches the destination.

Return Value

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

Discussion

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.

Availability
Declared In
Drag.h

< Previous PageNext Page > Hide TOC

© 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-12)

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