Installing Entries in the Apple Event Dispatch Tables
When your application receives an Apple event, use theAEProcessAppleEvent
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
You provide this information to the
- 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
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 theerrAEEventNotHandled
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, useFALSE
as the value of this parameter. If you specifyTRUE
, 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 constantkeyPreDispatch
. If the application's special handler dispatch table does not include such a handler or if the handler returnserrAEEventNotHandled
, 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
, theAEProcessAppleEvent
function looks in the system special handler dispatch table for an entry that was installed with the constantkeyPreDispatch
. If the system special handler dispatch table does not include such a handler or if the handler returnserrAEEventNotHandled
, 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.
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
- 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.
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 thekAEOpenDocuments
event ID, the Apple Event Manager dispatches Apple events of any event class with an event ID ofkAEOpenDocuments
to the handler for that entry.If you specify an entry with the
kCoreEventClass
event class and thetypeWildCard
event ID, the Apple Event Manager dispatches Apple events of thekCoreEventClass
event class with any event ID to the handler for that entry.If you specify an entry with the
typeWildCard
event class and thetypeWildCard
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 askAEDelete
, and another entry that specifies the event class askAECoreSuite
and the event ID astypeWildCard
, the Apple Event Manager will dispatch the Apple event handler associated with the entry that specifies the event ID askAEDelete
.
- IMPORTANT
- If your application sends Apple events to itself using a
typeProcessSerialNumber
address descriptor record with thelowLongOfPSN
field set tokCurrentProcess
, 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.