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:
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.
- 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.
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 thewhat
field of the event record. You can test thewhat
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 classmySpecialHLEventClass
and the event IDmySpecialHLEventID
. 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 callingAEProcessAppleEvent
. 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. TheAEProcessAppleEvent
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 isNIL
) 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.