MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
� 2001 K. J. Bricknell

CHAPTER 23

DRAG AND DROP

Overview

The Drag Manager

Using the Drag Manager, you can provide your application with the capability to drag objects from your application's windows, to your application's windows, and within your application's windows.

The Three Phases of a Drag

All drag and drop operations comprise the following three distinct phases:

• Starting the drag.

• Tracking the drag.

• Finishing the drag.

Different applications may be involved in each of these three phases. For example, when the user drags an item from one application to another, the source application starts the drag, other applications through whose windows the user drags the item may track the drag, and the application owning the target window finishes the drag by accepting the drop (see Fig 1).

Of course, when the drag and drop is wholly within one of an application's document windows, that single application starts the drag, tracks it through the window, and accepts the drop.

Starting the Drag

A drag is initiated when the user clicks on a selected object, keeps the mouse button down, and begins to move the mouse (see the left hand window at Fig 1). Using the function WaitMouseMoved, you can determine if the mouse has moved far enough to initiate a drag. If WaitMouseMoved returns true, your application should call NewDrag to create a new drag reference. A drag reference is an opaque data type that you use to refer to a specific drag process.

Having created a drag reference, and for each item in the drag, you must then add at least one drag item flavour to that reference using the function AddDragItemFlavor. Drag item flavours represent the various data formats in which each individual item may be produced. The concept is similar to that applying to Scrap flavours as described at Chapter 20.

With the drag item flavour (or flavours) added, your application can then initiate tracking by calling the function TrackDrag.

Tracking the Drag - Drag Tracking Handlers

The Drag Manager tracks the drag through each window the cursor moves over as the user drags the selection across the screen. During this process, the user is presented with the following feedback:

• Destination highlighting will occur when the cursor has left the source location. (See the middle window at Fig 1, whose owner application supports drag and drop and can accept the drop).

• If a container under the cursor (such as a folder in the Finder) can accept the drop, that container will be highlighted.

As the cursor moves through, for example, the middle window at Fig 1, the Drag Manager calls a function, called a drag tracking handler, defined by that window's owner application. Drag tracking handlers inspect the description of the item, or items, being dragged and highlight the window if this inspection reveals that the window can accept the drop. The application's drag tracking handler uses the functions ShowDragHilite and HideDragHilite to create and remove the highlighting. (The acceptable drop region, and thus the region highlighted, does not necessarily have to be the whole of the window's content region.)

Finishing the Drag - Drag Receive Handlers

When the user releases the mouse button in, for example, the right hand window at Fig 1, the Drag Manager calls a function, called a drag receive handler, defined by that window's owner application. Drag receive handlers accept the drop and insert the selection at its final destination.

More on Drag Items, Drag Item Flavours, and Handlers

Drag Items and Item Reference Numbers

A drag item is a single distinct object, which could be, for example, a selection from a painting in a painting program, a selection of objects in a drawing program, or a continuous range of text editing program.. A discontinuous selection of text (resulting from using the Command key in some programs) would result in multiple drag items.

A new drag item is created if the item reference number passed in the theItemRef parameter of a call to AddDragItemFlavor is different from any other item reference number.

In many cases it is easiest to use index numbers as item reference numbers (e.g., 1, 2, 3...). Item reference numbers are only used as unique "key" numbers for each item. Item reference numbers do not need to be given in order, nor must they be sequential. 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).

Drag Item Flavours

Any item that can be dragged can generally be represented using several different flavours (that is, data formats). At the start of a drag, your application must inform the Drag Manager, using the function AddDragItemFlavor, of the flavours that you can provide to the receiver of the drag. For example, if the drag item is a selection of text, you might elect to provide the data in both the standard 'TEXT' format and in the Rich Text Format (RTF). Alternatively, instead of supplying the data in RTF, you might supplement the 'TEXT' data with 'styl' data. You might also provide the data in your application's own internal data format to cater for a drag and drop to one of your application's documents, including the source document.

Your application adds additional flavours to an item by passing the same item reference number in the AddDragItemFlavor call as was used in the AddDragItemFlavor call which created the item and added the first flavour.

Different destinations may prefer different data formats, and there is no certainty as to whether a drag will contain the preferred, or an acceptable, flavour. Thus, as previously stated, the destination application needs to inspect the description of the items being dragged to determine whether an acceptable flavour is available and only highlight the relevant window if it can accept a drop. The function GetFlavorFlags is used to determine whether the drag contains a specific flavour type.

Flavour Flags

The following flavour flags, which are used by the Drag Manager and its clients to provide additional information about a specific drag item flavour, may be passed in the theFlags parameter of the function AddDragItemFlavor and retrieved by the function GetFlavorFlags:

Note that the Finder does not save flavour types marked with the flavorSenderTranslated, flavorNotSaved, and flavorSystemTranslated flags into clippings files.

Drag Handlers

Drag tracking handlers and drag receive handlers are callback functions that your application registers with the Drag Manager using the functions InstallTrackingHandler and InstallReceiveHandler. The window reference of the window on which the handlers are to be installed is passed in the theWindow parameter of the two handler installer functions. You can install more than one tracking handler and more than one receive handler on the same window, in which case the Drag Manager calls each of the handlers in the order they were installed.

If you pass NULL in the theWindow parameter of the handler installer functions, the Drag Manager will register the handler in a special area that is used when the drag occurs in any window of your application. Handlers installed in this special area are called default handlers.

Drag Tracking Handlers

As the user moves the mouse through your application's windows during the drag, the Drag Manager sends status messages to your tracking handler. These messages are as follows:

Fig 2 illustrates the receipt of tracking messages involving multiple applications and windows.

Drag Receive Handlers

When the user drops an item, or a collection of items, in one of your application's windows, the Drag Manager calls any receive handlers installed on the destination window. Your receive handler can then request the drag item flavour, or flavours, that you wish to accept and insert the data at its final destination.

When the drop occurs within the window in which the drag originated, and the user did not press the option key either before the mouse button went down or before it was released, receive handlers must delete the original selection before inserting the dropped data. If the option button was not pressed, receive handlers must not delete the selection.

Creating the Drag Region and Setting the Drag Image

Creating the Drag Region

Recall that your application initiates tracking by calling the function TrackDrag. This function takes a region, specifically, the drag region, in its theRgn parameter. This is the region, drawn by the Drag Manager in the dithered gray pattern (Mac OS 8/9) or gray colour (Mac OS X), that moves with the mouse during the drag (see Fig 1).

As an example, to create a drag region when a single item is selected, your application should:

• Copy the drag item's region to a temporary region and inset the temporary region by 1 pixel.

• Use DiffRgn to subtract the temporary region from a copy of the item's region.

The resulting copy of the item's region has the same outline as the item's original region but is only one pixel thick (see Fig 3).

Setting the Drag Image - Translucent Drags

The drag region may also be visually represented to the user by a translucent image of the original selection (see Fig 4).

To support translucent dragging of a text selection on Mac OS 8/9, you should:

• Create an offscreen graphics world the size of the bounding rectangle of the highlight region. The offscreen graphics world should be eight bits deep.

• Copy the area of the window enclosed by the highlight region's bounding rectangle to the offscreen graphics world.

• Create a region for a mask which is exactly the same shape as the highlight region. (Note that, if you do not supply a mask, the entire rectangular area of the offscreen pixel map, including white space, will be dragged.)

• Call SetDragImage to associate the image with the drag reference, passing in the handle to the offscreen pixel map, the handle to the mask region, and a constant specifying the required level of translucency. SetDragImage installs a custom drawing function (see below) to perform the translucent drawing.

The level of translucency may be specified using one of the following drag image flags:

Drag Functions - Overriding Drag Manager Default Behaviour

If you wish to override the Drag Manager's default behaviour, you can supply it with several different kinds of drag function. Only the sender can specify drag functions.

Drawing Function

When a drawing function is installed, the Drag Manager sends that function a sequence of messages that allow the application to assume responsibility for drawing the drag region (or similar feedback) on the screen. If translucent dragging is used, you must not install a custom drawing function.

Send Data Function

If you install a send data function, the Drag Manager calls that function when the receiver application requests a drag item flavour that the Drag Manager does not currently have the data cached for.

Ordinarily, the Drag Manager caches the flavour data for all flavours that were added to the drag with the AddDragItemFlavor function. If a receiver calls GetFlavorData to get a flavour's data, the Drag Manager simply returns the cached data to the receiver.

However, if your application passes NULL as the pointer to the flavour data in the AddDragItemFlavor call, the Drag Manager does not cache the data. In effect, your application has made a "promise" to later supply the data in the event that a receiver requests it. Thus, if a receiver calls GetFlavorData for that particular flavour, the Drag Manager will call your send data function to get the data from the sender. Your send data function should then create that flavour's data and call SetDragItemFlavorData to send the data to the Drag Manager.

This mechanism of "promising" data that may, in the event, not be called for by a receiver is useful where the sender must perform expensive computations to produce the data or if the resulting data requires a large amount of memory to store.

Drag Input Function

If you install a drag input function, the Drag Manager calls that function when sampling the mouse position and keyboard state to allow the application to override the current state of the input devices. The Drag Manager passes the current mouse location, mouse button state, and keyboard modifier status to your drag input function, which can then modify those parameters.

Main Drag Manager Constants, Data Types, and Functions

Constants

Flavour Flags

flavorSenderOnly               = (1 << 0)
flavorSenderTranslated         = (1 << 1)
flavorNotSaved                 = (1 << 2)
flavorSystemTranslated         = (1 << 8)

Drag Attributes

kDragHasLeftSenderWindow       = (1L << 0)
kDragInsideSenderApplication   = (1L)
kDragInsideSenderWindow        = (1L << 2)

Drag Tracking Handler Messages

kDragTrackingEnterHandler      = 1
kDragTrackingEnterWindow       = 2
kDragTrackingInWindow          = 3
kDragTrackingLeaveWindow       = 4
kDragTrackingLeaveHandler      = 5

Drag Image Flags

kDragStandardTranslucency      = 0L
kDragDarkTranslucency          = 1L
kDragDarkerTranslucency        = 2L
kDragOpaqueTranslucency        = 3L

Drag Drawing Handler Messages

kDragRegionBegin               = 1
kDragRegionDraw                = 2
kDragRegionHide                = 3
kDragRegionIdle                = 4
kDragRegionEnd                 = 5

Data Types

typedef struct OpaqueDragRef *DragRef;
typedef UInt32  DragItemRef;
typedef OSType  FlavorType;
typedef UInt32  DragAttributes;
typedef UInt32  FlavorFlags;
typedef SInt16  DragTrackingMessage;
typedef SInt16  DragRegionMessage;

Functions

Installing and Removing Drag Handlers

OSErr   InstallTrackingHandler(DragTrackingHandlerUPP trackingHandler,WindowRef theWindow,
        void *handlerRefCon);
OSErr   InstallReceiveHandler(DragReceiveHandlerUPP receiveHandler,WindowRef theWindow,
        void *handlerRefCon);
OSErr   RemoveTrackingHandler(DragTrackingHandlerUPP trackingHandler,WindowRef theWindow);
OSErr   RemoveReceiveHandler(DragReceiveHandlerUPP receiveHandler,WindowRef theWindow);

Creating and Disposing of Drag References

OSErr   NewDrag(DragRef *theDrag);
OSErr   DisposeDrag(DragRef theDrag);

Adding Drag Item Flavors

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

Performing a Drag

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

Getting Drag Item Information

OSErr   CountDragItems(DragRef theDrag,UInt16 *numItems);
OSErr   GetDragItemReferenceNumber(DragRef theDrag,UInt16 index,DragItemRef *theItemRef);
OSErr   CountDragItemFlavors(DragRef theDrag,DragItemRef theItemRef,UInt16 *numFlavors);
OSErr   GetFlavorType(DragRef theDrag,DragItemRef theItemRef,UInt16 index,
        FlavorType *theType);
OSErr   GetFlavorFlags(DragRef theDrag,DragItemRef theItemRef,FlavorType theType,
        FlavorFlags *theFlags);
OSErr   GetFlavorDataSize(DragRef theDrag,DragItemRef theItemRef,FlavorType theType,
        Size *dataSize);
OSErr   GetFlavorData(DragRef theDrag,DragItemRef theItemRef,FlavorType theType,
        void * dataPtr,Size *dataSize,UInt32 dataOffset);

Getting and Setting Drag Status Information

OSErr   GetDragAttributes(DragRef theDrag,DragAttributes *flags);
OSErr   GetDragMouse(DragRef theDrag,Point *mouse,Point *globalPinnedMouse);
OSErr   SetDragMouse(DragRef theDrag,Point globalPinnedMouse);
OSErr   GetDragOrigin(DragRef theDrag,Point *globalInitialMouse);
OSErr   GetDragModifiers(DragRef theDrag,SInt16 *modifiers,SInt16 *mouseDownModifiers,
        SInt16 *mouseUpModifiers);

Window Highlighting Utilities

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

Drag Manager Utilities

Boolean WaitMouseMoved(Point initialMouse);

Setting Drag Functions

OSErr   SetDragSendProc(DragRef theDrag,DragSendDataUPP sendProc,void *dragSendRefCon);
OSErr   SetDragInputProc(DragRef theDrag,DragInputUPP inputProc,void *dragInputRefCon);
OSErr   SetDragDrawingProc(DragRef theDrag,DragDrawingUPP drawingProc,void *dragDrawingRefCon);

Setting the Drag Image � Translucent Dragging

OSErr   SetDragImage (DragRef theDrag, PixMapHandle imagePixMap,RgnHandle imageRgn,
                      Point imageOffsetPt,DragImageFlags theImageFlags);

Creating and Disposing of Universal Procedure Pointers

DragTrackingHandlerUPP  NewDragTrackingHandlerUPP(DragTrackingHandlerProcPtr userRoutine);
DragReceiveHandlerUPP   NewDragReceiveHandlerUPP(DragReceiveHandlerProcPtr userRoutine);
DragSendDataUPP         NewDragSendDataUPP(DragSendDataProcPtr userRoutine);
DragInputUPP            NewDragInputUPP(DragInputProcPtr userRoutine);
DragDrawingUPP          NewDragDrawingUPP(DragDrawingProcPtr userRoutine);
void    DisposeDragTrackingHandlerUPP(DragTrackingHandlerUPP userUPP);
void    DisposeDragReceiveHandlerUPP(DragReceiveHandlerUPP userUPP);
void    DisposeDragSendDataUPP(DragSendDataUPP userUPP);
void    DisposeDragInputUPP(DragInputUPP userUPP);
void    DisposeDragDrawingUPP(DragDrawingUPP userUPP);

Application Defined (Callback) Functions

OSErr   myDragTrackingHandler(DragTrackingMessage message,WindowRef theWindow,
        void *handlerRefCon,DragRef theDrag);
OSErr   myDragReceiveHandler(WindowRef theWindow,void *handlerRefCon,DragRef theDrag);
OSErr   muDragSendDataFunction(FlavorType theType,void *dragSendRefCon,DragItemRef theItemRef,
        DragRef theDrag);
OSErr   myDragInputFunction(Point *mouse,SInt16 *modifiers,void *dragInputRefCon,
        DragRef theDrag);
OSErr   myDragDrawingFunction(DragRegionMessage message,RgnHandle showRegion,
        Point showOrigin,RgnHandle hideRegion,Point hideOrigin,void *dragDrawingRefCon,
        DragRef theDrag);

Relevant TextEdit Function

OSErr   TEGetHiliteRgn(RgnHandle region,TEHandle hTE);