TweetFollow Us on Twitter

MACINTOSH C CARBON: A Hobbyist's Guide To Programming the Macintosh in C
Version 1.0
2001 K. J. Bricknell
Go to Contents Go to Program Listing




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:




Set by the sender if the flavour should only be available to the sender.


Set if the flavour data is translated by the sender. Useful if the receiver needs to ascertain whether the sender is performing its own translation to generate this data type.


Set by the sender if the flavour data should not be stored by the receiver. Useful for marking flavour data that will become stale after the drag is completed.


Set if the flavour data is translated by the Translation Manager. If this flavour is requested, the Drag Manager will acquire the required data type from the sender and then use the Translation Manager to provide the data requested by the receiver.

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:



Enter handler

Received when the focus of the drag enters a window handled by your tracking handler from a window not handled by your tracking handler.

Enter window

Received when the focus of a drag enters any window handled by your tracking handler.

In window

Received as the user drags within a window handled by your tracking handler.

Leave window

Received when the focus of a drag leaves a window that is handled by your tracking handler.

Leave handler

Received when the focus of a drag enters a window that is not handled by your tracking handler.

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:




kDragStandardTranslucency 0L

65% image translucency. This is the recommended level.

kDragDarkTranslucency 1L

50% image translucency.

kDragDarkerTranslucency 2L

25% image translucency.

kDragOpaqueTranslucency 3L

0% image translucency (opaque).

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


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;


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


Community Search:
MacTech Search:

Software Updates via MacUpdate

The best games like Animal Crossing on m...
Animal Crossing amiibo Festival is out right now for the Wii U, reminding us of just how much fun that world can be. Or at least to go back and check in on our villages once in a while. [Read more] | Read more »
Between 2 Taps - Tap for Tap interview M...
Hello, and welcome back to Between 2 Taps, Tap for Tap’s Indie Dev interview series. [Read more] | Read more »
Facility 47 (Games)
Facility 47 1.0.1 Device: iOS Universal Category: Games Price: $3.99, Version: 1.0.1 (iTunes) Description: You wake up alone and freezing in an icy cell. You try the cell door but it’s locked, it seems that you are stuck with no... | Read more »
The best Photoshop alternative on iPad
Instagram and Lightroom are great and all, but sometimes people need to get extra creative with their image editing.Like, Photoshop creative. If you're one of these people, take a look at our pick for the best mobile Photoshop experience on iPad... | Read more »
The Walking Dead: No Man’s Land guide -...
A new update for The Walking Dead: No Man’s Land was released last week, making it the perfect time for you to head back to your base and take out some walkers. Here’s the lowdown on what’s new to the game, and how to take advantage. [Read more] | Read more »
Goat Rider guide - Tips and tricks to st...
We've all been there. One second, we're riding high on a crazed goat, and the next, we've been tossed off it like someone who's no good at goat ridin'. [Read more] | Read more »
Real Boxing 2 CREED: How to become a gre...
Just in time for Rocky fans who can’t wait to see CREED, the latest movie, we have the official tie-in game,Real Boxing 2 CREED. It builds on the success of its predecessor and there’s lots to take in so we at 148apps thought we’d run you through... | Read more »
CoinOp Heroes 2 guide - How to build an...
CoinOp Heroes 2 justlaunched and, like all clickers, it's dangerously addictive stuff. You have to furiously tap your screen to defeat wave after wave of foes and earn an insane amount of cash to spend on character upgrades and an army of minions... | Read more »
Dr. Panda Firefighters (Education)
Dr. Panda Firefighters 1.0.1 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0.1 (iTunes) Description: FIGHT FIRES AND SAVE THE DAY!Work together with Dr. Panda and his firefighting team to rescue his trapped... | Read more »
Puddle + (Games)
Puddle + 1.0 Device: iOS iPhone Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: Puddle is back in a new "+" edition featuring enhanced graphics, new videos and Apple TV support ! No IAP and No Ads. Dive into Puddle... | Read more »

Price Scanner via

Save $30-$40 on new Apple TVs after rebate
Adorama has new Apple TVs on sale for up to $40 off MSRP after mail-in rebate, good through December 15th. Shipping is free, and Adorama charges NY & NJ sales tax only: - 32GB Apple TV: $119.99... Read more
13-Inch Haswell MacBook Air At Two Years – Th...
The 13-inch mid-2013 “Haswell” MacBook Air I ordered in Apple’s November 2013 Black Friday sale was my first new Mac in four and a half years — the longest interval I’ve gone between system upgrades... Read more
Target Black Friday Early Access deals: $100...
Target is offering early access to their Black Friday deals on Apple products on their online store for today, the 25th, only. Choose free shipping or free local store pickup (if available): - Apple... Read more
BlackBerry Q3 Mobility Index Report Finds iOS...
BlackBerry has announced results of its thirteenth Good Mobility Index Report, showing that organizations are increasingly building custom secure apps. Among Good Powered by BlackBerry (formerly Good... Read more
Wednesday roundup of early Black Friday Mac s...
Save up to $500 on a new Mac with these early Black Friday deals from Apple resellers, currently the lowest prices available for these models: (1) B&H Photo has all new Macs on sale for up to $... Read more
iPod nano on sale for $119, $30 off MSRP
Walmart has the 16GB iPod nano (various colors) on sale for $119.20 on their online store for a limited time. That’s $30 off MSRP. Choose free shipping or free local store pickup (if available). Sale... Read more
Adorama Black Friday deals: Up to $400 off Ma...
Adorama has released their Black Friday deals for 2015. Save up to $400 on MacBook Pros, $200 on MacBooks and MacBook Airs, and $270 on iMacs. Use code RYBFDEAL during checkout to see these prices.... Read more
B&H Photo Deals: $200 off 12-inch 1.2GHz...
In addition to the B&H Photo Black Friday week sales we posted yesterday, B&H has lowered their price on two products to $200 off MSRP: - 12″ 1.2GHz Gray Retina MacBook: $1399 save $200 - 13... Read more
Best Buy Early Access: Today only, Up to $125...
Best Buy has iPad Air 2s on sale for up to $125 off MSRP and Apple Watch models on sale on their online store for up to $100 off MSRP with special codes through midnight CT tonight. Choose free... Read more
UPPERCASE DESIGNS Premium Ultra Thin Keyboard...
UPPERCASE Designs today announced its new Premium Ultra Thin Keyboard Protector and its Palm Rest Protector Set for the 12-inch MacBook. The accessories provide durable protection for the 12-inch... Read more

Jobs Board

Hardware Systems Integration Engineer - *App...
# Hardware Systems Integration Engineer - Apple Watch Job Number: 39380139 Santa Clara Valley, Califo ia, United States Posted: Apr. 23, 2015 Weekly Hours: **Job Read more
Sr. Technical/Project Manager, *Apple* Educ...
# Sr. Technical/Project Manager, Apple Education Job Number: 36588557 New York City, New York, United States Posted: Jul. 30, 2015 Weekly Hours: 40.00 **Job Summary** Read more
*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Merchant Operations Manager: *Apple* Pay -...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
*Apple* Pay QA Manager - Apple Inc. (United...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more than Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.