Inside Macintosh: Interapplication Communication /

Chapter 7 - Introduction to Scripting

Making Your Application Recordable

If you decide to make your application scriptable, you can also make it recordable. A recordable application is an application that uses Apple events to report user actions to the Apple Event Manager for recording purposes. A recordable event is any Apple event that a recordable application sends to itself while recording is turned on for the local computer (with the exception of events sent with the kAEDontRecord flag set in the sendMode parameter of AESend).

When a user turns on recording by clicking the Record button in the Script Editor application, the Apple Event Manager sends copies of all subsequent recordable events to Script Editor. The AppleScript component handles each copied event for Script Editor by translating it into compiled expressions and recording the compiled expressions as part of a script. (Figure 7-6 on page 7-15 shows how the AppleScript component uses the 'aete' and 'aeut' resources when it records a script.) The user can view the equivalent decompiled source data in Script Editor while the script is being recorded. When a user executes a recorded script, the AppleScript component sends the corresponding Apple events to the applications in which they were recorded.

Applications generally have two parts: the code that implements the application's user interface and the code that actually performs the work of the application when the user manipulates the interface. One way to make your application recordable is to separate these two parts of your application, using Apple events to connect user actions with the work your application performs. This is called factoring your application. In a fully factored application, almost all tasks are carried out in response to Apple events. The application translates low-level events that result in significant actions into recordable Apple events and then sends them to itself.

Factoring your application is the recommended method of making your application recordable. However, it is also possible for your application to report user actions by means of Apple events even though it actually performs those actions by some means other than Apple events. You can indicate that you want the Apple Event Manager to record events in this manner, without executing them, by adding the constant kAEDontExecute to the sendMode parameter of AESend.

Before you decide how to map the user's potential actions to recordable Apple events supported by your application, you need to answer these questions:

• What are the significant (that is, undoable) actions a user can perform with your application that you want to record?
• Which actions can you execute by means of Apple events, and which actions should cause Apple events to be sent but not executed?
• How do you want to record actions that can be described in a scripting language in several different ways?

For example, if your application is a word processor, the user's selection of a range of text should probably not generate an Apple event, because users often select various different pieces of text before deciding to do something to the selection. However, if a user changes the font of a selection, a recordable word processor should generate a corresponding Apple event so that the scripting component can record the change.

In general, a recordable application should generate Apple events for any user action that the user could reverse by choosing Undo. A recordable application can usually handle a greater variety of Apple events than it can record, because it must record the same action the same way every time even though Apple events might be able to trigger that action in several different ways.

For more information about recordable applications, factoring, and the Apple Event Manager's recording mechanism, see the chapter "Recording Apple Events" in this book. For a description of the role of the 'aete' and 'aeut' resources when the AppleScript component records a script, see "How AppleScript Uses Terminology Information," which begins on page 7-13.