AppleScript: The Definitive Guide

Scriptable, Recordable, Attachable

These three adjectives refer to three levels on which an application can be scriptable. They aren’t really levels, but they seem to form a natural progression. That progression seems to have diminishing returns, since very few scriptable applications are also recordable, and very few scriptable applications are also attachable.

Scriptable

An application is scriptable by means of AppleScript if it defines a repertory of Apple events to which it is prepared to respond, and publishes that repertory in a dictionary. So, the usual way to learn whether an application is scriptable is to try to open its dictionary with an editor such as the Script Editor. If it has a dictionary, it’s scriptable.

(At least, that’s how things are supposed to work. We’re assuming here that all the pieces of the mechanism are behaving properly. It’s possible for an application to lie. For example, it could publish a dictionary giving the impression that it responds to Apple events it doesn’t respond to. At the furthest extreme, an application could look scriptable, in the sense that it publishes a dictionary, but not actually be scriptable. Yes, I’ve seen applications that do that.)

Recordable

The idea of a scriptable application’s being recordable is that the application can help the user learn to drive it with AppleScript by constructing a script in reverse: the user performs ordinary actions in the application, choosing from menu items, pushing buttons, or whatever, and meanwhile these actions are translated into the code that would be used to accomplish the same effect via AppleScript.

To try this out, start with a recordable application; here, we’ll use BBEdit. Start it up. Now use a dedicated script editor such as the Script Editor. In the Script Editor’s main window, there’s a Record button. Press it. Now switch to BBEdit and type -N to make a new window. Now return to the Script Editor and press the Stop button. You will notice that the following text has magically appeared in the Script Editor window:

tell application "BBEdit"
        activate
        make new text window
end tell

That is the AppleScript code you would have to execute in order to cause the same actions to occur through a script.

Recording is implemented partly by AppleScript and partly by the application. Pressing the Record button in Script Editor signals to AppleScript that it should start watching for recordable events. When it sees a recordable event, AppleScript decompiles it and sends the decompiled text to Script Editor, which displays the text. The only question is then what constitutes a recordable event. The answer turns out to be surprisingly simple: it’s any Apple event that an application sends to itself. In fact, an application is allowed to send itself a “fake” Apple event just so that if recording happens to be turned on, this Apple event will be detected and treated as the AppleScript equivalent for whatever else is happening in the application.

An application can deal elegantly both with recordability and with scriptability by being written in a factored style. A factored application is one that triggers its own functionality (or at least some portion of it) by sending itself Apple events. For example, in BBEdit when you type -N (or choose New from the File menu), BBEdit responds by sending itself the Apple event that commands a new text window to be created; it then receives this Apple event and responds to it by creating a new text window.^[4] Under this architecture, it makes no difference to BBEdit whether a user working inside BBEdit types -N or whether a script tells it to “make new text window,” because ultimately BBEdit receives the same Apple event in either case, without knowing or caring whether it came from itself or from a script. So in a factored application, scriptability is built in at a deep level, and the user interface is wrapped around that. A factored application has some advantages for the developer, making it easier to continue modifying the application while maintaining scriptability; plus, of course, it makes the application recordable “for free.”

There is no way to find out whether an application is recordable, if you don’t know in advance, other than by trying to record it. Very few applications are recordable on Mac OS X. As of this writing, there is some indication that the Finder may be recordable in Mac OS X 10.3; if so, this should please users accustomed to the Finder’s recordability in Mac OS 9 and before, who have missed this feature in earlier versions of Mac OS X.

Attachable

An attachable application gives the user the opportunity to interfere with certain incoming Apple events by means of a script. This means that the user can customize what happens when an Apple event arrives. If the application is scriptable, then the user may be able to customize the effect of scripting the application. If the application is factored, then the user may be able to customize the effect of performing an action within the user interface. The only applications I know that are strongly and deeply attachable in this canonical sense are Script Debugger and Smile.

There are no standards for how attachability is to be implemented, however, and as a result it is not entirely clear what constitutes attachability. Perhaps one should distinguish between degrees of attachability. For example, folder actions (see Section 2.5 and Section 24.3) may be seen as a mild form of attachability, since you are customizing what happens when certain events take place in the Finder’s user interface. On that definition, one could also call BBEdit’s factored menu implementation a form of attachability: when you choose a menu item in BBEdit, if there is an appropriately named script in the BBEdit Support/Menu Scripts folder, that script is called, so you can customize what happens in response to the menu item.

---

^[4] Wittgenstein asked, “What is left over when I subtract the fact that my arm goes up, from the fact that I raise my arm?” Now we know: an Apple event.