Legacy Documentclose button

Important: The information in this document is obsolete and should not be used for new development.

Previous Book Contents Book Index Next

Inside Macintosh: Devices /
Chapter 1 - Device Manager


Writing a Desk Accessory

Desk accessories are small applications designed like device drivers. Desk accessories typically provide a user interface with a window and a menu, perform some limited function, and are opened from the Apple menu. The Chooser is an example of a desk accessory.

Desk accessories were originally created for the Macintosh because they offered two distinct advantages over applications. They provided both a limited degree of multitasking and a primitive form of interapplication communication. However, modern Macintosh applications enjoy far more sophisticated versions of these capabilities. Users can even open applications from the Apple menu. For these reasons, you would be better served by writing a small application than by writing a desk accessory.

Control panels have largely replaced desk accessories as a user interface for device drivers. In addition to providing a more consistent and extensible interface, control panels can include an initialization ('INIT') resource to load and execute your device driver at system startup. For more information about control panels, see the chapter "Control Panels" in Inside Macintosh: More Macintosh Toolbox.

If you're certain you need to write a desk accessory, you should read this section. You might also want to read the chapters "Event Manager," "Window Manager," "Dialog Manager," and "Menu Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

How Desk Accessories Work

When the user opens a desk accessory (or when an application calls the OpenDeskAcc function), the system performs a major context switch, loads the desk accessory into the system heap, and calls the desk accessory driver open routine. The desk accessory can respond by creating its window and menu.

When events occur, the Event Manager directs them to the desk accessory by calling its driver control routine. The Event Manager handles switching between applications and desk accessories in the system heap.

When the user closes the desk accessory (by closing its window or choosing Quit from its menu) or an application closes the desk accessory (by calling the CloseDeskAcc function), the desk accessory disposes of its window and any other data structures associated with it.

In a single-application environment in System 6, and in a multiple-application environment in which the desk accessory is launched in the application's partition (for example, a desk accessory opened by the user from the Apple menu while holding down the Option key), the Event Manager handles events for desk accessories in a slightly different manner, although it still translates them into control requests. For details, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

Creating a Driver Resource for a Desk Accessory

You create a desk accessory by creating a driver resource and storing it in a resource file, as described in "Creating a Driver Resource," beginning on page 1-24. Typically, you store your desk accessory driver resource in a file of type 'dfil', which the user places in the Apple Menu Items folder.

Three fields of the driver resource header are of particular importance to desk accessories:

All desk accessories must implement open, close, and control routines. Your desk accessory can implement a prime and status routine if needed.

Opening and Closing a Desk Accessory

When the user chooses an item from the Apple menu, the foreground application calls the OpenDeskAcc function, which determines whether the item is a desk accessory, application, or document, and schedules it for execution. Applications call the CloseDeskAcc function if the user chooses the Close menu item from the File menu when the foreground window does not belong to the application. These functions are described in "Device Manager Reference," beginning on page 1-53.

Opening a desk accessory is similar to launching an application. In your desk accessory driver open routine, you should do the following:

If your driver open routine is unable to complete its tasks (because of insufficient memory, for example), you should modify the code so it doesn't respond to events, and display an alert indicating failure.

As for all drivers, your close routine should undo the actions taken by the open routine, dispose of the desk accessory's window and private storage, clear the window pointer in the device control entry, and remove any menus that were added to the menu bar.

Responding to Events

When the Event Manager determines an event has occurred that your desk accessory should handle, it checks the drvrEMask field of the driver header and, if that field indicates your desk accessory handles the event type, it passes the event to your desk accessory by calling your driver control routine.

The Event Manager passes one of nine values in the csCode field to indicate the action to take:
Constant nameValueMeaning
accEvent64Handle a given event
accRun65Time for periodic action
accCursor66Change cursor shape if appropriate
accMenu67Handle a given menu item
accUndo68Handle the Undo command
accCut70Handle the Cut command
accCopy71Handle the Copy command
accPaste72Handle the Paste command
accClear73Handle the Clear command

Along with the accEvent message, the Event Manager sends a pointer to an event record in the csParam field. Your desk accessory can respond to the event in whatever way is appropriate. For example, when your desk accessory becomes active, it might install its menu in the menu bar.

Note
If your desk accessory window is a modeless dialog box and you are calling the Dialog Manager function IsDialogEvent in response to the event, you should set the windowKind field of your window record to 2 before you call IsDialogEvent. Setting this field to 2 allows the Dialog Manager to recognize and handle the event properly. You should restore the original value of the windowKind field before returning from your control routine.
The Event Manager periodically sends the accRun message if your desk accessory has requested time for background processing. To request this service, you set the dNeedTime flag in the drvrFlags field of your desk accessory driver header. See "Writing Control and Status Routines," beginning on page 1-34, for more information.

The accCursor message makes it possible to change the shape of the cursor when it is inside your desk accessory window and your desk accessory window is active. Your control routine should check whether the mouse location is in your window and, if so, should set the cursor appropriately by calling the QuickDraw function InitCursor.

If your desk accessory window is a dialog box, you should respond to the accCursor message by generating a null event (storing the event code for a null event in an event record) and passing it to the Dialog Manager function DialogSelect. This allows the Dialog Manager to blink the insertion point in editText items.

When the Event Manager sends an accMenu message, it provides the menu ID followed by the menu item number in the csParam field. You should take the appropriate action and then call the Menu Manager function HiliteMenu with a value of 0 for the menuID parameter to remove the highlighting from the menu bar.

You should respond to the last five messages, accUndo through accClear, by processing the corresponding editing command in the desk accessory window, if appropriate. The chapter "Scrap Manager" in Inside Macintosh: More Macintosh Toolbox contains information about cutting and pasting.

Your desk accessory routines should restore the current resource file and graphics port if it changes either one.


Subtopics
How Desk Accessories Work
Creating a Driver Resource for a Desk Accessory
Opening and Closing a Desk Accessory
Responding to Events

Previous Book Contents Book Index Next

© Apple Computer, Inc.
3 JUL 1996