Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Handling Apple Events Sent by the Mac OS

Mac OS X sends Apple events to communicate with applications in certain common situations, such as when launching the application or asking it to open a list of documents. These events are sometimes referred to as the “required” events, although applications are not required to support all of them. For example, if your application isn’t document-based, it won’t support the open documents or print documents events. However, any application that presents a graphical user interface through the Human Interface Toolbox or the Cocoa application framework should respond to as many of these events as it makes sense for that application to support.

Carbon applications typically install Apple event handlers to handle these events, though in some cases a default handler may be installed automatically (as described in “Common Apple Events Sent by the Mac OS”).

For Cocoa applications, most of the work of responding to events sent by the Mac OS happens automatically, though in some cases applications may want to step in and modify the default behavior. For more details, including some information of general interest, see How Cocoa Applications Handle Apple Events in Cocoa Scripting Guide.

In this section:

Common Apple Events Sent by the Mac OS
Installing Handlers for Apple Events Sent by the Mac OS

Common Apple Events Sent by the Mac OS

The following are Apple events your application is likely to receive from the Mac OS. For information on the constants associated with these events, see “Event ID Constants for Apple Events Sent by the Mac OS.”

• open application (or launch)

  Received when your application is launched. The application should perform any tasks required when a user launches it without opening or printing any existing documents, though it may of course open a new, untitled document.

  Starting in Mac OS X version 10.4, an open application Apple event may contain information about whether the application was launched as a login item or as a service item. For details on working with this kind of information, see “Launch Apple Event Constants” in “Apple Event Manager Constants” in Apple Event Manager Reference.

• reopen application

  Received when the application is reopened—for example, when the application is open but not frontmost, and the user clicks its icon in the Dock. The application should perform appropriate tasks—for example, it might create a new document if none is open.

• open documents

  Received with a list of documents for the application to open. Listing 5-5 shows a complete Apple event handler for this event.

  Starting in Mac OS X version 10.4, the open documents Apple event may contain an optional parameter identified by the key keyAESearchText. If present, the parameter contains the search text from the Spotlight search that identified the documents to be opened. The application should make a reasonable effort to display an occurrence of the search text in each opened document—for example by scrolling text into view that contains all or part of the search text.

• print documents

  Received with a list of documents for the application to print. You can obtain file system references to the items in the list using code like that you use when handling an open documents event. See “Interacting With the User” for information on when it is appropriate to display a dialog or perform other interaction.

  Starting in Mac OS X version 10.3, the print documents event was extended to include an optional print settings parameter that defines the settings for the print job or jobs, and an optional print dialog parameter that specifies whether the application should display the Print dialog. By default, the application should not show the Print dialog if the caller doesn't specify a print dialog parameter. For details, see Technical Note TN2082, The Enhanced Print Apple Event.

• open contents

  Available starting in Mac OS X version 10.4. Received when content, such as text or an image, is dropped on the application icon—for example, when a dragged image is dropped on the icon in the Dock.

  The structure of this event is very similar to the open documents event. The direct object parameter consists of a list of content data items to be opened. The descriptorType for each item in the list indicates the type of the content ('PICT', 'TIFF', 'utf8', and so on).

  The application should use the content in an appropriate way—for example, if a document is open, it might insert the content at the current insertion point; if no document is open, it might open a new document and insert the provided text or image.

  If your Carbon application provides a service that can accept the type of data in an open contents Apple event it receives, you can handle the event without even installing an event handler for it—a default handler will be installed, if one isn’t present, and invoked automatically. As a result, your service provider will receive a {kEventClassService, kEventServicePerform} Carbon event.

  Because there is no way to return data from an open contents Apple event, the default handler only invokes a service that accepts the given data type but returns nothing.

  If your application doesn’t support services, or if you want to provide special handling for the open contents Apple event, your application can install a handler for the event.

  For information on working with services, see Setting Up Your Carbon Application to Use the Services Menu.

• quit application

  Received when the application should quit. The application can perform any special operations required at that time.

  If your application calls RunApplicationEventLoop, a simple quit handler is installed automatically. If you install your own handler, it can perform any required operations, then return errAEEventNotHandled so that the default handler continues quitting the application. If you return another error value, the application will not quit. However, your quit handler can call QuitApplicationEventLoop, which causes RunApplicationEventLoop to quit and return back to main(). In that case you can return noErr from your handler instead of errAEEventNotHandled.

  If your application does not call RunApplicationEventLoop, you should supply your own quit handler.

  You should not terminate your application from within a quit event handler. Instead, you should set a flag that you check outside the handler.

• show preferences

  Received when the user chooses the Preferences menu item. Carbon applications that handle the Preferences command can install an Apple event handler for this event, but they more commonly install a Carbon event handler for kEventCommandProcess and check for the kHICommandPreferences command ID.

• application died

  Received by an application that launched another application when the launched application quits or terminates. Your application can respond to the information that the other application is no longer running.

Installing Handlers for Apple Events Sent by the Mac OS

Listing 5-6 shows how your application installs handlers for various Apple events that are sent by the Mac OS. The listing assumes that you have defined the functions OpenApplicationAE, ReopenApplicationAE, OpenDocumentsAE, and PrintDocumentsAE to handle the Apple events open application, reopen, open documents, and print documents, respectively.

This function doesn’t install handlers for the open contents and quit Apple events, so the application will rely on the default handlers for those events (described previously in “Common Apple Events Sent by the Mac OS”).

Listing 5-6  Installing event handlers for Apple events from the Mac OS

static  OSErr   InstallMacOSEventHandlers(void)

{

    OSErr       err;

    err     = AEInstallEventHandler(kCoreEventClass, kAEOpenApplication,

                NewAEEventHandlerUPP(OpenApplicationAE), 0, false);

    require_noerr(err, CantInstallAppleEventHandler);

    err     = AEInstallEventHandler(kCoreEventClass, kAEReopenApplication,

                NewAEEventHandlerUPP(ReopenApplicationAE), 0, false);

    require_noerr(err, CantInstallAppleEventHandler);

    err     = AEInstallEventHandler(kCoreEventClass, kAEOpenDocuments,

                NewAEEventHandlerUPP(OpenDocumentsAE), 0, false);

    require_noerr(err, CantInstallAppleEventHandler);

    err     = AEInstallEventHandler(kCoreEventClass, kAEPrintDocuments,

                NewAEEventHandlerUPP(PrintDocumentsAE), 0, false);

    require_noerr(err, CantInstallAppleEventHandler);

CantInstallAppleEventHandler:

    return err;

}

For a description of the parameters you pass to the AEInstallEventHandler function, see “Installing Apple Event Handlers.”

< Previous PageNext Page > Hide TOC

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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice