Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events

What to Record

Factoring an application involves making decisions about which user actions generate Apple events, about the content of those events, and about when to send events for recording purposes. For example, the preceding section, "Sending Apple Events Without Executing Them," describes how an application should generate an Apple event that corresponds to a change in the position of a window. Other actions can be more complicated to define in terms of Apple events. This section provides general guidelines for deciding which user actions should generate Apple events and how those events should be defined.

When the user records a series of actions as a script, playing the recorded script back later in exactly the same circumstances must produce exactly the same result. If the circumstances at execution time are similar but not exactly the same as when the script was recorded, the script should also work correctly. However, certain differences will always lead to unexpected results or cause execution to fail.

The goal of these guidelines is to help you create scripts that will work correctly in the largest number of circumstances with the fewest post-recording changes by the user. To accomplish this goal, a recordable application should send itself Apple events that describe as specifically as possible the user's actions in the application's domain without making guesses about the user's intentions.

The way your application uses Apple events to record a user's actions depends in part on the kind of script being recorded. From the user's perspective, there are at least three kinds of scripts:

• A script application. The icons for these files appear in the Finder, for example, in the Apple Menu Items folder or the Startup Items folder.
• A script that functions like a menu command, usually acting on the current selection in the current application, and stored either as a compiled script file that appears in the Finder or as a script stored within an application or one of its documents.
• A script that is "embedded" in an application--that is, explicitly associated with something in a document, such as a field in a form, a cell or row of a spreadsheet, or a button.

The recording guidelines in the sections that follow apply to the recording of scripts that function like menu commands and scripts that are embedded in an application. Because such scripts are executed under a user's direct control, the user expects their execution to cause something to happen, possibly changing the current selection, the Clipboard, or the active window.

The execution of a script application, however, may cause a scripting component to send events to one or more applications intermittently without the user's knowledge. If the script in a script application refers to the current selection, the Clipboard, or the active window, its execution may interfere with other tasks being performed by the user or tasks performed during the execution of other scripts. To create a script application and ensure that it works correctly when executed, a scripter may need to modify the script after it has been recorded.

For example, to eliminate references to the Clipboard, a scripter can use a script variable as a user-defined Clipboard and convert Cut, Copy, and Paste statements to appropriate combinations of Move, Copy, New, and Delete statements, while supplying the previously defined selection as the argument. It may also be necessary to convert a description such as "the front document" to a specific filename or a variable.

---

Subtopics

Recording User Actions

Recording the Selection of Text Objects

Recording Insertion Points

Recording Typing

Recording the Selection of Nontext Objects

Identifying Objects

Moving the Selection During Recording

Recording Interactions With Dialog Boxes