Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 4 - Responding to Apple Events / Handling Apple Events

Accepting an Apple Event

To accept or send Apple events (or any other high-level events), you must set the appropriate flags in your application's 'SIZE' resource and include code to handle high-level events in your application's main event loop.

Two flags in the 'SIZE' resource determine whether an application receives high-level events:

• The isHighLevelEventAware flag must be set for your application to receive any high-level events.
• The localAndRemoteHLEvents flag must be set for your application to receive high-level events sent from another computer on the network.

Note that in order for your application to respond to Apple events sent from remote computers, the user of your application must also allow network users to link to your application. The user does this by selecting your application in the Finder, choosing Sharing from the File menu, and clicking the Allow Remote Program Linking checkbox. If the user has not yet started program linking, the Sharing command offers to display the Sharing Setup control panel so that the user can start program linking. The user must also authorize remote users for program linking by using the Users & Groups control panel. Program linking and setting up authenticated sessions are described in the chapter "Program-to-Program Communications Toolbox" in this book.

For a complete description of the 'SIZE' resource, see the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials.

Apple events (and other high-level events) are identified by a message class of kHighLevelEvent in the what field of the event record. You can test the what field of the event record to determine whether the event is a high-level event.

Listing 4-1 is an example of a procedure called from an application's main event loop to handle events, including high-level events. The procedure determines the type of event received and then calls another routine to take the appropriate action.

Listing 4-1 A DoEvent procedure

PROCEDURE DoEvent (event: EventRecord);
BEGIN       
   CASE event.what OF         {determine the type of event}
      mouseDown:
         DoMouseDown (event);
      .
      . {handle other kinds of events}
      .
      {handle high-level events, including Apple events}
      kHighLevelEvent: DoHighLevelEvent (event);
   END;
END; 

Listing 4-2 is an example of a procedure that handles both Apple events and the high-level event identified by the event class mySpecialHLEventClass and the event ID mySpecialHLEventID. Note that, in most cases, you should use Apple events to communicate with other applications.

Listing 4-2 A DoHighLevelEvent procedure for handling Apple events and other high-level events

PROCEDURE DoHighLevelEvent (event: EventRecord);
VAR
   myErr: OSErr;
BEGIN
   IF (event.message = LongInt(mySpecialHLEventClass)) AND
      (LongInt(event.where) = LongInt(mySpecialHLEventID)) 
   THEN
      {it's a high-level event that doesn't use AEIMP}
      myErr := HandleMySpecialHLEvent(event)
   ELSE
      {otherwise, assume that the event is an Apple event}
      myErr := AEProcessAppleEvent(event);
   
   {check and handle error}
   IF myErr <> noErr THEN DoError(myErr);
END;

If your application accepts high-level events that do not follow the Apple Event Interprocess Messaging Protocol (AEIMP), you must dispatch these high-level events before calling AEProcessAppleEvent. To dispatch high-level events that do not follow AEIMP, you should check the event class, the event ID, or both for each event to see whether your application can handle the event.

After receiving a high-level event (and, if appropriate, checking whether it is a high-level event other than an Apple event), your application typically calls the AEProcessAppleEvent function. The AEProcessAppleEvent function determines the type of Apple event received, gets the event buffer that contains the parameters and attributes of the Apple event, and calls the corresponding Apple event handler in your application.

You should provide an Apple event handler for each Apple event that your application supports. This handler is responsible for performing the action requested by the Apple event and if necessary can return data in the reply Apple event.

If the client application requests a reply, the Apple Event Manager passes a default reply Apple event to your handler. If the client application does not request a reply, the Apple Event Manager passes a null descriptor record (a descriptor record of descriptor type typeNull and a data handle whose value is NIL) to your handler instead of a default reply Apple event.

After your handler finishes processing the Apple event and adds any parameters to the reply Apple event, it must return a result code to AEProcessAppleEvent. If the client application is waiting for a reply, the Apple Event Manager returns the reply Apple event to the client.