Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events

How Apple Event Recording Works

Scripting components use the Apple Event Manager's recording mechanism to allow a recording process such as the Script Editor application to control recording into scripts. Script editors and applications that provide their own recording capabilities can take advantage of the recording mechanism via standard scripting component routines.

This section describes how scripting components use Apple event recording. You need to read this section if you are developing a scripting component or a script-editing application, or if you want your application to initiate and control Apple event recording. For information about using the standard scripting component routines to turn recording off and on, see "Recording Scripts" on page 10-26.

When a user turns on recording for a recording process (for example, by clicking the Record button in Script Editor), the recording process calls a scripting component routine (OSAStartRecording) to turn recording on. The scripting component responds by sending a Start Recording event to the recording process (or any running process on the local computer).

Start Recording--begin sending copies of recordable events to recording process
Event class	kCoreEventClass
Event ID	kAEStartRecording
Parameters	None
Description	Sent by a scripting component to the recording process (or to any running process on the local computer), but handled by the Apple Event Manager. The Apple Event Manager responds by turning on recording and sending a Recording On event to all running processes on the local computer. This event must be addressed using a process serial number (PSN); it should never be sent to an address specified as kCurrentProcess.

The recording process should not handle the Start Recording event. Instead, the Apple Event Manager handles it by sending a Recording On event to all running processes on the local computer and sending copies of all subsequent recordable events to the recording process. (The Recording On event is described on page 9-4.)

If an application that supports Apple events is launched on a computer for which recording is turned on, the Apple Event Manager will also send it a Recording On event for each recording process that is currently recording.

The recording process receives recordable events by means of a Receive Recordable Event handler--that is, a handler installed in the Apple event dispatch table for event class kCoreEventClass and event ID kAENotifyRecording. Scripting components install this handler on behalf of a recording process when recording is first turned on and remove the handler when recording is turned off. Much like a handler for event class typeWildCard and event ID typeWildCard, the Receive Recordable Event handler handles all recordable events sent to the recording process by the Apple Event Manager. Any other Apple events received by the recording process are dispatched in the usual manner. The Receive Recordable Event handler handles recordable events by recording them in the script specified by the recording process's call to OSAStartRecording.

Receive Recordable Event--receive and record a copy of a recordable event
Event class	kCoreEventClass
Event ID	kAENotifyRecording
Parameters	Same as Apple event being recorded
Description	Wildcard event class and event ID handled by a recording process in order to receive and record copies of recordable events sent to it by the Apple Event Manager. Scripting components install a handler for this event on behalf of a recording process when recording is turned on and remove the handler when recording is turned off.

Whenever the Receive Recordable Event handler receives a recordable event, the scripting component sends your application a Recorded Text event. The Recorded Text event contains the decompiled source data for the recorded event in the form of styled text. For a description of the Recorded Text event, see "Recording Scripts" on page 10-26.

When a user turns off recording (for example, by clicking Script Editor's Stop button), the recording process calls a scripting component routine (OSAStopRecording) to turn recording off. The scripting component responds by sending a Stop Recording event to the recording process (or any running process on the local computer).

Stop Recording--stop sending copies of recordable events to recording process
Event class	kCoreEventClass
Event ID	kAEStopRecording
Parameters	None
Description	Sent by a scripting component to the recording process (or to any running process on the local computer), but handled by the Apple Event Manager. The Apple Event Manager responds by sending a Recording Off event to all running processes on the local computer. This event must be addressed using a process serial number (PSN); it should never be sent to an address specified as kCurrentProcess.

Like the Start Recording event, the Stop Recording event is handled by the Apple Event Manager. The Apple Event Manager responds by sending a Recording Off event to all running processes on the local computer. (The Recording Off event is described on page 9-4.)

Recording continues, and the recording process may continue to receive recordable events, until the Apple Event Manager has notified all running processes that recording has been turned off for that recording process. The Apple Event Manager sends all running processes the Recording Off event with the kAEWaitReply flag set. If an application has stored some data (for instance, keystrokes) that needs to be recorded as an Apple event, this is the last chance for the application to send the event for recording purposes. Recording stops only after the Apple Event Manager returns a reply for the Stop Recording event.

The Apple Event Manager supports multiple simultaneous recording processes. A Stop Recording event sent for one of them does not affect the others. If your application needs to know which of several recording processes has turned recording on or off, it can check the keyOriginalAddressAttr attribute of the Recording On or Recording Off event for the address of the recording process.

If the Apple Event Manager does not receive a Stop Recording event for a recording process that quits unexpectedly, the applications being recorded don't find out immediately. When it attempts to send a copy of a recordable event to a recording process that is no longer active, the Apple Event Manager sends a Recording Off event to all running processes on behalf of that recording process and specifies the address for that process in the keyOriginalAddressAttr attribute. If a recording process that quits is the only actively recording process, recording stops completely after the Apple Event Manager has informed all running processes that recording has been turned off.