Some users navigate Standard File dialogs with no problem, but many others find them
tedious or even confusing. Users want to find and organize their files without having to
learn the intricacies of the hierarchical file system and Standard File dialogs. With
applications that use the Drag Manager, users will be able to work with files the way
they expect: by dragging files from the Finder into an application window. This article
and the accompanying sample program show how easily your application can provide
this valuable feature.
The Drag Manager is so new you won't find it in Inside Macintosh yet, but if your
application works with files, you'll want to learn more about what it can do for you.
This new Macintosh Toolbox manager lets users drag and drop data (such as text and
pictures) between windows in an application and between different applications. It also
allows users to drag document icons to and from the Finder.
Rather than describing the Drag Manager in depth, this article and its sample
application focus on using the Drag Manager to drag picture files (files of type 'PICT')
from the Finder into an application. The techniques used by the sample application can
easily be generalized to cover other cases.
The Drag Manager is currently packaged as a system software extension that you can
license to include with your products. It requires System 7, and to take advantage of
the Finder dragging described in this article you need Finder version 7.1.1 or later.
You can order the full Macintosh Drag and Drop Developer's Kit from APDA. The Drag
Manager will also be included in future system software releases.
Along with the sample application, called SimpleDrag, this issue's CD contains the
programmer's guide for the Drag Manager as well as theDrag and Drop Human
Interface Guidelines. After you've read this article and looked at the SimpleDrag code,
you should read these two documents to get a deeper understanding of the Drag Manager.
SimpleDrag not only allows picture files to be dragged from the Finder but also lets
PICT data be dragged from one application window into another; for the full story on
this, look at the code and documentation on the CD.
Dragging is a skill that every Macintosh user has mastered. It provides a quick, simple
alternative to commands as a way of performing common operations such as moving or
deleting files. This use of dragging gives users a sense of control because they can
manipulate objects directly with excellent visual feedback. And it's faster and more
intuitive than commands because it's not hidden in a menu.
Since all Macintosh users use dragging to arrange and manipulate files in the Finder, it
only makes sense that they should be able to drag files from the Finder into an
application window. But until now, the only way to select and specify files within an
application has been with Standard File dialogs. Now you can use the Drag Manager to
provide an alternate, more intuitive way to work with files: the user can open a file in
your application simply by dragging the file's icon into an application window.
Before we look at the sample code, we need to clarify a few terms that the Drag
manager introduces: drag items, drag flavors, drag handlers, senders, and receivers.
The objects that a user drags are called drag items. For example, a user who selects
and drags three files is dragging three different drag items.
Drag flavors describe the kind of data that a drag item contains. When a user drags an
item to an application window, the receiving application must determine whether it
can accept the data in the drag item. Each item can have more than one flavor, because
data can usually be described in more than one format or data type. For example, you
can describe text data as ASCII data, styled text data, or RTF interchange format; if a
program can't accept the more elaborate RTF format, it may be able to use the plain
ASCII text. The Drag Manager uses a four-character ResType to identify a flavor. In
our sample application, we use only two drag flavors: one that identifies files dragged
from the Finder, and another that identifies PICT data dragged from an application
window.
The Drag Manager uses an application's drag handlers to provide dragging feedback and
to complete a drag. There are two types of drag handlers: tracking handlers and receive
handlers. A tracking handler is called while an item is being dragged over an
application's windows; a receive handler is called when the user releases the mouse
button to drop the item in a window. Each window has a tracking handler and receive
handler installed for it, though several windows may use the same handler. When you
initialize your application or open a new window, you call the Drag Manager to install
your drag handler callback routines.
Because the Drag Manager provides interapplication drag and drop services, it's
important to know where the drag starts and where it ends. The application in which
the drag starts is called thesender. Any application that the item is dragged over is a
potential receiver of the drag; the application it's dropped into is the actual receiver.
The sender and receiver might be the same application -- but with interapplication
dragging, another application could be the receiver of the drag.
With the lingo out of the way, let's look at our SimpleDrag application. This
application displays pictures in its windows. One way the user specifies a picture file
to be displayed is by choosing the application's Open command and then selecting a file
from the Standard File dialog. But since the application uses the Drag Manager, the
user can also drag a picture file from the Finder into a SimpleDrag window. PICT data
displayed in a SimpleDrag window can even be dragged into another SimpleDrag
window.
Before you call any Drag Manager routines, make sure that the Drag Manager is
available by calling Gestalt with the selector gestaltDragMgrAttr and checking the
gestaltDragMgrPresent bit of the response. *
First let's consider the code for the Open command case. When the user chooses the
Open command, SimpleDrag calls the Standard File Package to present a dialog that
lists the picture files. Once the user has selected a file, SimpleDrag calls its
SetWindowPictureFromFile routine to read the file and display it.
To support dragging files from the Finder into the application, SimpleDrag installs two
drag handlers for each new window. While the user drags a PICT drag item over a
SimpleDrag window, the tracking handler provides visual feedback. If the user drops
the item in a SimpleDrag window, the Drag Manager calls the receive handler to read
and display the PICT information, which may be not only a picture file but also PICT
data dragged from another window; the receive handler calls
its SetWindowPictureFromFile routine if the drag item is a picture file (just as when
the user chooses Open from the File menu).
The following routine installs the tracking and receive handlers:
OSErr InstallDragHandlers(WindowPtr theWindow)
{
OSErr retCode;
retCode = InstallTrackingHandler(MyTrackingHandler, theWindow,
nil);
if (retCode == noErr) {
retCode = InstallReceiveHandler(MyReceiveHandler, theWindow,
nil);
if (retCode != noErr)
(void) RemoveTrackingHandler(MyTrackingHandler,
theWindow);
}
return retCode;
}
That's all you need to do to set up tracking and receive handlers for the given window.
You can also install a default handler, to be used for any window that you don't
explicitly install a handler for, by passing nil as the window pointer to the install
routine.
TRACKING THE DRAG
Now let's see what happens while the user drags an item around. Our main objective is
to indicate, with visual feedback, where it's OK to drop the item. SimpleDrag provides
the standard feedback highlighting for its type of windows and data -- a thin frame
highlight within the content region of the window. This highlight signals the user that
the item can be dropped there.
While the user drags an item (or items) over one of the application's windows, the
mouse movement determines what messages the tracking handler receives, as follows:
The tracking handler for SimpleDrag is as follows:
pascal OSErr MyTrackingHandler(DragTrackingMessage theMessage,
WindowPtr theWindow, void *handlerRefCon, DragReference theDrag)
{
#pragma unused (handlerRefCon)
RgnHandle tempRgn;
Boolean mouseInContentFlag;
OSErr retCode;
retCode = noErr;
switch (theMessage) {
case dragTrackingEnterHandler:
// Determine whether the drag item is acceptable and
// store that flag in the globals, plus reset the
// highlighted global flag.
gDragHandlerGlobals.acceptableDragFlag =
DragItemsAreAcceptable(theDrag);
gDragHandlerGlobals.windowIsHilightedFlag = false;
break;
case dragTrackingEnterWindow:
case dragTrackingInWindow:
case dragTrackingLeaveWindow:
// Highlighting of the window during a drag is done here.
// Do it only if we can accept this item and we're not
// in the source window.
if (gDragHandlerGlobals.acceptableDragFlag &&
DragIsNotInSourceWindow(theDrag)) {
if (theMessage == dragTrackingLeaveWindow)
mouseInContentFlag = false;
else
mouseInContentFlag = MouseIsInContentRgn(theDrag,
theWindow);
if (mouseInContentFlag &&
!gDragHandlerGlobals.windowIsHilightedFlag) {
ClipRect(&theWindow->portRect);
tempRgn = NewRgn();
RectRgn(tempRgn, &theWindow->portRect);
if (ShowDragHilite(theDrag, tempRgn, true) ==
noErr)
gDragHandlerGlobals.windowIsHilightedFlag =
true;
DisposeRgn(tempRgn);
}
else if (!mouseInContentFlag &&
gDragHandlerGlobals.windowIsHilightedFlag) {
ClipRect(&theWindow->portRect);
if (HideDragHilite(theDrag) == noErr)
gDragHandlerGlobals.windowIsHilightedFlag =
false;
}
}
break;
case dragTrackingLeaveHandler:
// Do nothing for the LeaveHandler message.
break;
default:
// Let the Drag Manager know we didn't recognize the
// message.
retCode = paramErr;
}
return retCode;
}
The EnterWindow message is sent when the drag enters the structure region of a
window, not the content region. The Drag and Drop Human Interface Guidelines specify
that the title bar of a window, which is outside the content region, should not be able to
receive drags. So upon receiving an EnterWindow message, the tracking handler needs
to check the mouse location before calling ShowDragHilite.*
To give the user visual feedback, the tracking handler uses the Drag Manager's
ShowDragHilite routine. This routine takes a region to be highlighted and draws an
inset or outset frame of that region. Here we use it to highlight inside the content
region of the window, but you can also use it to highlight panes within a window or any
arbitrary region that accepts a drag. We later call HideDragHilite when the drag leaves
the content region of our window.
As you can see in the above code, there are several conditions to check for before
calling the highlight routines. The DragItemsAreAcceptable routine, which the
tracking handler calls when it gets an EnterHandler message, checks that only one item
is being dragged (a limitation of our simple example) and that the drag item is PICT
data or a picture file.
Boolean DragItemsAreAcceptable(DragReference theDrag)
{
OSErr retCode;
unsigned short totalItems;
ItemReference itemRef;
Boolean acceptableFlag;
HFSFlavor currHFSFlavor;
Size flavorDataSize;
FlavorFlags currFlavorFlags;
acceptableFlag = false;
// This application can only accept the drag of a single item.
retCode = CountDragItems(theDrag, &totalItems);
if (retCode == noErr && totalItems == 1) {
retCode = GetDragItemReferenceNumber(theDrag, 1, &itemRef);
if (retCode == noErr) {
// Use GetFlavorFlags to see if the drag item is PICT
// data.
retCode = GetFlavorFlags(theDrag, itemRef, 'PICT',
&currFlavorFlags);
if (retCode == noErr)
acceptableFlag = true;
else {
// Check if the item is a file spec for a picture
// file.
flavorDataSize = sizeof(HFSFlavor);
retCode = GetFlavorData(theDrag, itemRef,
flavorTypeHFS, &currHFSFlavor,
&flavorDataSize, 0);
if (retCode == noErr &&
currHFSFlavor.fileType == 'PICT')
acceptableFlag = true;
}
}
}
return acceptableFlag;
}
DragItemsAreAcceptable calls GetFlavorFlags with type 'PICT' to determine whether
the drag item is PICT data. If it isn't PICT data, GetFlavorFlags returns
cantGetFlavorErr; DragItemsAreAcceptable then checks to see if the drag item is a
picture file, by calling GetFlavorData with flavorTypeHFS. This is a special flavor that
identifies files dragged from the Finder into an application. Data of type HFSFlavor
contains the file's Finder information and an FSSpec that you can use to open and read
the file.
typedef struct HFSFlavor {
OSType fileType; // file type
OSType fileCreator; // file creator
unsigned short fdFlags; // Finder flags
FSSpec fileSpec; // file system specification
};
typedef struct HFSFlavor HFSFlavor;
Another check made in the tracking handler is to ensure (with the routine
MouseIsInContentRegion) that the drag isn't over the title bar or over controls in the
application window. To implement drag and drop according to the guidelines, we accept
drags only in the content region of a window. Also, since SimpleDrag doesn't support
drag and drop within the same window, the tracking handler checks (with its
DragIsNotInSourceWindow routine) to make sure that the user isn't dragging over the
same window in which the drag originated.
RECEIVING THE DRAG
The receive handler is similar to the tracking handler, but it's called once, and we
must ask for all the data we want. We also make sure that the drag stopped in the
content region of the window and that the user isn't dragging back into the source
window.
Below is the code for SimpleDrag's receive handler. In a receive handler, you first ask
for the data type you prefer, whether picture, text, or some other type, and whether a
file from the Finder or data dragged directly from another window. In SimpleDrag, we
prefer to receive PICT data directly, so we look for it first. If the drag item isn't PICT
data, we use the HFS flavor to look for files of type 'PICT'.
pascal OSErr MyReceiveHandler(WindowPtr theWindow,
void *handlerRefCon, DragReference theDrag)
{
#pragma unused (handlerRefCon)
ItemReference itemRef;
Size dataSize;
Handle tempHandle;
HFSFlavor theHFSFlavor;
Boolean dataObtainedFlag;
OSErr retCode;
dataObtainedFlag = false;
if (!DragItemsAreAcceptable(theDrag) ||
!MouseIsInContentRgn(theDrag, theWindow) ||
!DragIsNotInSourceWindow(theDrag))
return dragNotAcceptedErr;
// There is only one item, so get its reference number.
retCode = GetDragItemReferenceNumber(theDrag, 1, &itemRef);
if (retCode != noErr)
return retCode;
// PICT data is preferred, so get it if it's available.
retCode = GetFlavorDataSize(theDrag, itemRef, 'PICT', &dataSize);
if (retCode == noErr) {
tempHandle = TempNewHandle(dataSize, &retCode);
if (tempHandle == nil)
tempHandle = NewHandle(dataSize);
if (tempHandle != nil) {
HLock(tempHandle);
retCode = GetFlavorData(theDrag, itemRef, 'PICT',
*tempHandle, &dataSize, 0);
if (retCode == noErr) {
retCode = SetWindowPicture(theWindow,
(PicHandle) tempHandle);
if (retCode == noErr)
dataObtainedFlag = true;
}
DisposeHandle(tempHandle);
}
}
if (!dataObtainedFlag) {
// Couldn't get PICT data so try to get HFS-flavor data.
dataSize = sizeof(HFSFlavor);
retCode = GetFlavorData(theDrag, itemRef, flavorTypeHFS,
&theHFSFlavor, &dataSize, 0);
if (retCode == noErr && theHFSFlavor.fileType == 'PICT') {
retCode = SetWindowPictureFromFile
(&theHFSFlavor.fileSpec, theWindow);
}
}
if (retCode != noErr)
(void) ReportErrorInWindow(nil,
"\pCannot display received picture. ", retCode);
return retCode;
}
If there's an error, this receive handler just displays a simple string. For commercial
products, you would never code strings inline as shown, for localization reasons.
Here we'll describe a couple of precautions you should take that will make your life
easier when you use the Drag Manager.
FINDER GOTCHAS
The Drag Manager works for documents and other standard files, but what about
folders and hard drive icons? The Finder uses the same HFS flavor to describe these
items. If the user drags them to your application, you'll see the FSSpec for the folder's
directory or the disk's root directory. The file type and creator information isn't
relevant to the file system, but it's useful for identifying the items being dragged. For
both folders and disk icons, the creator is set to 'MACS' to show that the system
software created them. For folders, the file type is 'fold', and for disk icons the file
type is 'disk'. In both cases the Finder flags for the folder or disk are set
appropriately. Remember that these file types serve only to quickly identify the items
being dragged and don't reflect what's in the catalog information of any volumes.
Some software that extends the functionality of the Finder, such as QuickDraw GX and
PowerTalk (the client server software based on the Apple Open Collaboration
Environment), adds new Finder icons such as desktop printers, letters, and mailboxes.
These items don't actually represent the state of the file system, but they can be
dragged like any Finder icon. This is a valuable and consistent metaphor for the Finder
interface, but it creates an inconsistency for your receive handler when receiving
drags from the Finder. Since these icons can't be described as FSSpecs, don't expect to
receive HFS flavors for them.
Just for completeness, you should know that the Users & Groups control panel also
uses the Drag Manager. The drag flavors that identify those icons make sense only to
the Finder, and don't have relevant information you could extract. The same is true for
contents of Finder suitcase files like the System file. Finder icons for sounds, keyboard
layouts, and fonts that are in suitcases are representations of resources in the suitcase
file, so they don't have HFS flavors to describe them. Note, however, that sound and
font files, which are not part of suitcases, use HFS flavors just like any other file.
WAITNEXTEVENT
Another precaution applies if, in drag handlers, you call WaitNextEvent, EventAvail,
GetNextEvent, or any other routine that would normally cause a process switch or a
background application to receive WaitNextEvent time. In these cases, don't expect
other applications to receive any background time, because the Drag Manager disables
process switching during a drag. Because process switching is disabled, you should be
careful when interacting with the user in your receive handler. You may not be the
frontmost process, and opening a dialog may hang the Macintosh.
The Drag Manager makes it easy to add drag and drop functionality to your application.
It gives users a familiar and intuitive way to manipulate files and data. This article and
the sample application emphasize how to implement dragging files from the Finder into
your application windows, but you can do much more than that with the Drag Manager.
So take a look at the documentation and guidelines on the CD and give it a go; your users
will think it's anything but a drag!
DAVE EVANS can often be found coding for the User Experience team of the AppleSoft OS
Platform Group. Although some still think he moonlights on the set of the TV show
"Beverly Hills 90210," Dave actually finds entertainment by throwing himself off
cliffs and cornices, plane struts and buildings (the last much to Apple Security's
chagrin). Dave does admit, though, to being deathly afraid of bungee jumps! *
GREG ROBBINS has been insisting for three years that he doesn't work for Apple. But
he has worked as a consultant to the Developer Technical Support and Macintosh
System Software groups since 1991, having given up an earlier passion for neural
networks to hack the Mac. Greg spends his off hours in the mountains of California,
looking for people even more lost than he is.*
For more on letters and mailboxes, see the article "Building PowerTalk-Savvy
Applications" in this issue of develop.*
THANKS TO OUR TECHNICAL REVIEWERSSteve Fisher, Rob Johnston, Jim Mensch, Andy
Nicholas *