---

Apple Event Handling Overview

All Mac OS X applications that present a graphical user interface should be able to respond to certain Apple events that are sent by the Mac OS. These events, sometimes called the required events, include those the application can receive at launch (the open application, open documents, print documents, and open contents events), as well as others it receives when already running (again including open documents and print documents, as well as the reopen and quit events). These events can also be sent by other applications and by users executing scripts.

If an application is scriptable, it can receive additional events that target the scriptable features it supports.

In this section:

Basics of Apple Event Handling
Handling Apple Events in a Cocoa Application

Basics of Apple Event Handling

Applications work with the Apple Event Manager to receive and extract information from Apple events. The processing of Apple events typically follows this pattern:

1. For the Apple events an application expects to receive, it registers callback routines, called Apple event handlers, with the Apple Event Manager.

2. When the application receives an Apple event, it uses the Apple Event Manager to dispatch the event to the appropriate event handler and to identify the object or objects in the application on which to perform the specified operation. (The details vary depending on the programming environment in use.)

You can read more about this process in Apple Events Programming Guide and Apple Event Manager Reference. The implementation of code to handle Apple events can be somewhat complex. However, Cocoa provides a lot of built-in support for handling Apple events, minimizing the need for your application to work directly with Apple event data structures or the Apple Event Manager.

Handling Apple Events in a Cocoa Application

For every Cocoa application, the Application Kit automatically installs event handlers for Apple events it knows how to handle, including those sent by the Mac OS. These event handlers implement a default behavior, described in “Apple Events Sent by the Mac OS,” that in some cases depends on code implemented by your application.

Nonscriptable Applications

A nonscriptable application can support or modify the default behavior provided by the Application Kit's Apple event handlers in these ways:

• It can implement or override the appropriate methods invoked by the Cocoa handlers, as described in “Apple Events Sent by the Mac OS.” This is the standard mechanism.

• It can install handlers to supersede the ones installed by Cocoa. To replace a specific event handler, read the information about that event in “Apple Events Sent by the Mac OS,” then read how to install a new handler in “Installing an Apple Event Handler.”

A nonscriptable application can also install handlers for other Apple events. But if your nonscriptable application needs to install many handlers, you should consider making it scriptable.

Scriptable Applications

A scriptable application can support or modify the default behavior provided by the Application Kit's Apple event handlers in the same ways a nonscriptable application can (by implementing or overriding the appropriate methods, or by installing a replacement event handler).

For other Apple events, a scriptable application doesn't typically install handlers directly (although it is free to do so) because it can use the script command mechanism. That mechanism, which automatically installs handlers based on information in the application's sdef file, is summarized in “Snapshot of Cocoa Scripting” and described in more detail in “Script Commands.”

---