Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events

About Recordable Applications

A recordable application is an application that uses Apple events to report user actions to the Apple Event Manager for recording purposes. One way to do this is to separate the code that implements your application's user interface from the code that actually performs work when the user manipulates the interface. This is called factoring your application. A factored application translates low-level events generated by the user into recordable Apple events that the application sends to itself to perform tasks.

A recordable event is any Apple event that any recordable application sends to itself while recording is turned on for the local computer, with the exception of events that are sent with the kAEDontRecord flag set in the sendMode parameter of AESend. A recording process is any process (for example, the Script Editor application) that can turn recording on and off and can receive and record recordable Apple events.

After Apple event recording has been turned on by a recording process, the Apple Event Manager sends that process copies of all recordable Apple events on the local computer. For example, when a user presses the Record button in the Script Editor application, it calls a scripting component routine to turn on recording for the AppleScript component (or any other scripting component). While recording is on, the Apple Event Manager sends Script Editor copies of all subsequent recordable Apple events, which Script Editor records (with the aid of the scripting component) in the form of a compiled script. After turning off recording from Script Editor, the user can edit or execute the recorded script.

Although factoring your application is the recommended method of making your application recordable, it is also possible to report user actions by means of Apple events only when Apple event recording is turned on, even though the application may respond to those actions by some means other than Apple events. In effect, the application uses Apple events to describe user actions without actually using the events to perform the action. To indicate that you want the Apple Event Manager to send a copy of a recordable event to the recording process without actually sending the event to your application, add the constant kAEDontExecute to the sendMode parameter of the AESend function.

Even in a factored application, it may not always be possible to send an Apple event that actually executes the task initiated by the user. For example, if the user types some text, it is more practical to use standard TextEdit or QuickDraw routines to draw the text than to send a separate Apple event each time the user presses a key. In this case, the application can draw the text as it is typed in the most convenient manner available; then, when the user finishes typing a sequence of characters--by clicking the mouse button while the cursor is somewhere else in the document or performing some other action--the application can create an Apple event that corresponds to the typing and add the constant kAEDontExecute to the sendMode parameter when it sends the Apple event.

If your application needs to know when Apple event recording is turned on and off, it should install handlers for the Recording On and Recording Off events.

Recording On--perform actions associated with beginning of recording session
Event class	kCoreEventClass
Event ID	kAENotifyStartRecording
Parameters	None
Description	Sent by the Apple Event Manager to all running processes on the local computer to inform them that recording has been turned on

Recording Off--perform actions associated with end of recording session
Event class	kCoreEventClass
Event ID	kAENotifyStopRecording
Parameters	None
Description	Sent by the Apple Event Manager to all running processes on the local computer to inform them that recording has been turned off

When a recording process turns on recording, the Apple Event Manager sends all running processes on the local computer a Recording On event. When a user turns off recording, 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 to send an event for recording purposes. If your application needs to know which recording process 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.

Factoring your application is the recommended method of making your application recordable because it guarantees that any action a user can perform via your application's user interface can also be accomplished via Apple events. Factoring also allows you to avoid duplicating code within your application. Instead of using one piece of code to respond to some user action within your application, and another piece of code to respond to the equivalent Apple event, you can use the same code to respond to the Apple event, whether it is sent by your application in response to a user action, by some other application, or by a scripting component in the course of executing a script.

The next section, "Factoring Your Application for Recording," provides some examples of how to go about factoring your application. Regardless of how you factor your application, making it recordable requires you to make decisions about the most useful methods of recording user actions that can be described in several different ways in scripts. If a user moves a window, for example, the window can be described in the corresponding recorded script as window 1, or the window named Fred, or the first window. Although the OSA permits recording at a high level and thus avoids many of the problems users encounter with applications that record low-level events such as keystrokes and mouse clicks, scripting components cannot predict what information a user cares about in a given situation. Therefore, a recordable application should send Apple events that correspond to the simplest possible statements in a scripting language. "What to Record," which begins on page 9-14, provides some general guidelines for making these kinds of decisions.

"How Apple Event Recording Works," which begins on page 9-35, describes the Apple Event Manager's recording mechanism in more detail, including the role of the Recording On and Recording Off events.