Legacy Document

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

Inside Macintosh: Interapplication Communication /: Chapter 4 - Responding to Apple Events / Handling Apple Events

Installing Entries in the Apple Event Dispatch Tables
When your application receives an Apple event, use the AEProcessAppleEvent function to retrieve the data buffer of the event and to route the Apple event to the appropriate Apple event handler in your application. Your application supplies an Apple event dispatch table to map the Apple events your application supports to the Apple event handlers provided by your application.
To install entries in your application's Apple event dispatch table, use the AEInstallEventHandler function. You usually install entries for all of the Apple events that your application accepts into your application's Apple event dispatch table.
To install an Apple event handler in your Apple event dispatch table, you must specify

the event class of the Apple event
the event ID of the Apple event
the address of the Apple event handler for the Apple event
a reference constant

You provide this information to the AEInstallEventHandler function. In addition, you indicate whether the entry should be added to your application's Apple event dispatch table or to the system Apple event dispatch table.
The system Apple event dispatch table is a table in the system heap that contains system Apple event handlers--handlers that are available to all applications and processes running on the same computer. The handlers in your application's Apple event dispatch table are available only to your application. If AEProcessAppleEvent cannot find a handler for the Apple event in your application's Apple event dispatch table, it looks in the system Apple event dispatch table for a handler (see
"How Apple Event Dispatching Works" on page 4-9 for details). If it doesn't find a handler for the event, it returns the errAEEventNotHandled result code.
If you add a handler to the system Apple event dispatch table, the handler should reside in the system heap. If there was already an entry in the system Apple event dispatch table for the same event class and event ID, it is replaced unless you chain it to your system handler. See "Creating and Managing the Apple Event Dispatch Tables" on page 4-62 for details.

Installing Entries for the Required Apple Events
Listing 4-3 illustrates how to add entries for the required Apple events to your application's Apple event dispatch table.
Listing 4-3 Adding entries for the required Apple events to an application's Apple event dispatch table
myErr := AEInstallEventHandler(kCoreEventClass, 
                               kAEOpenApplication, 
                               @MyHandleOApp, 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallEventHandler(kCoreEventClass, 
                               kAEOpenDocuments, 
                               @MyHandleODoc,0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallEventHandler(kCoreEventClass, 
                               kAEPrintDocuments, 
                               @MyHandlePDoc, 0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallEventHandler(kCoreEventClass,
                               kAEQuitApplication,
                               @MyHandleQuit, 0, FALSE); 
IF myErr <> noErr THEN DoError(myErr);  
The code in Listing 4-3 creates entries for all four required Apple events in the Apple event dispatch table. (For examples of handlers that correspond to these entries, see "Handling the Required Apple Events," which begins on page 4-11.) The first entry creates an entry for the Open Application event. The entry indicates the event class and event ID of the Open Application event, supplies the address of the handler for that event, and specifies 0 as the reference constant.
The Apple Event Manager passes the reference constant to your handler each time your handler is called. Your application can use this reference constant for any purpose. If your application doesn't use the reference constant, use 0 as the value.
The last parameter to the AEInstallEventHandler function is a Boolean value that determines whether the entry is added to the system Apple event dispatch table or to your application's Apple event dispatch table. To add the entry to your application's Apple event dispatch table, use FALSE as the value of this parameter. If you specify TRUE, the entry is added to the system Apple event dispatch table. The code shown in Listing 4-3 adds entries to the application's Apple event dispatch table.

Installing Entries for Apple Events Sent by the Edition Manager
If your application supports the Edition Manager, you should also add entries to your application's Apple event dispatch table for the Apple events that your application receives from the Edition Manager. Listing 4-4 shows how to add these entries.
Listing 4-4 Adding entries for Apple events sent by the Edition Manager to an application's Apple event dispatch table
myErr := AEInstallEventHandler(sectionEventMsgClass, 
                               sectionReadMsgID, 
                               @MyHandleSectionReadEvent, 
                               0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallEventHandler(sectionEventMsgClass, 
                               sectionWriteMsgID, 
                               @MyHandleSectionWriteEvent, 
                               0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
myErr := AEInstallEventHandler(sectionEventMsgClass, 
                               sectionScrollMsgID, 
                               @MyHandleSectionScrollEvent, 
                               0, FALSE);
IF myErr <> noErr THEN DoError(myErr);
See "Handling Apple Events Sent by the Edition Manager" on page 4-20 for the parameters associated with these events. See the chapter "Edition Manager" in this book for information on how your application should respond to the Apple events sent by the Edition Manager.

How Apple Event Dispatching Works
In addition to the Apple event handler dispatch tables, applications can add entries to a special handler dispatch table in either the application heap or the system heap. These dispatch tables are used for various specialized handlers; for more information, see "Creating and Managing the Special Handler Dispatch Tables," which begins on page 4-99.
When an application calls AEProcessAppleEvent, the function looks first in the application's special handler dispatch table for an entry that was installed with the constant keyPreDispatch. If the application's special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, the function looks in the application's Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event.
If the application's Apple event dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, the AEProcessAppleEvent function looks in the system special handler dispatch table for an entry that was installed with the constant keyPreDispatch. If the system special handler dispatch table does not include such a handler or if the handler returns errAEEventNotHandled, the function looks in the system Apple event dispatch table for an entry that matches the event class and event ID of the specified Apple event.
If the system Apple event dispatch table does not include such a handler, the Apple Event Manager returns the result code errAEEventNotHandled to the server application and, if the client application is waiting for a reply, to the client application.

WARNING
Before an application calls a system Apple event handler, system software has set up the A5 register for the calling application. For this reason, if you provide a system Apple event handler, it should never use A5 global variables or anything that depends on a particular context; otherwise, the application that calls the system handler may crash.
For any entry in your Apple event dispatch table, you can specify a wildcard value for the event class, event ID, or both. You specify a wildcard by supplying the typeWildCard constant when installing an entry into the Apple event dispatch table. A wildcard value matches all possible values. Wildcards make it possible to supply one Apple event handler that dispatches several related Apple events.
For example, if you specify an entry with the typeWildCard event class and the kAEOpenDocuments event ID, the Apple Event Manager dispatches Apple events of any event class with an event ID of kAEOpenDocuments to the handler for that entry.
If you specify an entry with the kCoreEventClass event class and the typeWildCard event ID, the Apple Event Manager dispatches Apple events of the kCoreEventClass event class with any event ID to the handler for that entry.
If you specify an entry with the typeWildCard event class and the typeWildCard event ID, the Apple Event Manager dispatches all Apple events of any event class and any event ID to the handler for that entry.
If an Apple event dispatch table contains one entry for an event class and a specific event ID, and also contains another entry that is identical except that it specifies a wildcard value for either the event class or the event ID, the Apple Event Manager dispatches the more specific entry. For example, if an Apple event dispatch table includes one entry that specifies the event class as kAECoreSuite and the event ID as kAEDelete, and another entry that specifies the event class as kAECoreSuite and the event ID as typeWildCard, the Apple Event Manager will dispatch the Apple event handler associated with the entry that specifies the event ID as kAEDelete.

IMPORTANT
If your application sends Apple events to itself using a typeProcessSerialNumber address descriptor record with the lowLongOfPSN field set to kCurrentProcess, the Apple Event Manager jumps directly to the appropriate Apple event handler without going through the normal event-processing sequence. For this reason, your application will not appear to run more slowly when it sends Apple events to itself. For more information, see "Addressing an Apple Event for Direct Dispatching" on page 5-13.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.