Section 3.11. Modes of Scriptability

3.11. Modes of Scriptability

An application is scriptable if it defines a repertory of Apple events to which it is prepared to respond and publishes that repertory as a dictionary. The dictionary should contain terms that expose the application's core functionality (that caveat is intended to handle the case of applications that publish a dictionary but are not in fact scriptable in any meaningful way; see "Is This Application Scriptable?" in Chapter 1).

There are two additional modes (or levels, or aspects) whereby an application can be scriptable:

Recordable

An application is recordable if it can generate AppleScript code when the user performs ordinary actions in its graphical user interface. This ability can be useful for helping the programmer learn to script the application. There is no way to find out whether and to what extent an application is recordable, other than by trying to record it.

Attachable

The term attachable is somewhat ambiguously defined. Strictly, an attachable application is one that allows the user to customize, by means of a script, what happens when the application receives an Apple event. But it may also be said that an application that allows the user to customize any of its event responses through a script is attachable.

3.11.1. Recordability

As an example of a recordable application, let's take BBEdit. In a script editor application such as Script Editor or Script Debugger, make a new script window, and choose Script Record (or press the Record button). In BBEdit, press -N to make a new window. Back in the script editor application, choose Script Stop (or press the Stop button). In the the script window, the following compiled script has appeared:

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

BBEdit has recorded the actions you performed; you switched to it and made a new window, and BBEdit has provided the AppleScript code you would have to execute in order to cause the same actions to occur through a script. Obviously, this can be a good way to learn how to script an application. A scriptable application, in effect, has two interfaces: a graphical user interface and the scripting interface. But it isn't always obvious how they intersect. What would I have to say to BBEdit using AppleScript to get the same effect that I see when I press -N? Recording that action answers that question. Unfortunately, very few applications are recordable (far fewer on Mac OS X than in previous systems).

Recording is implemented partly by AppleScript and partly by the scriptable application. Pressing the Record button in a script editor application 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 the script editor application, which displays the text.

But precisely 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 occurring in the application.

The developers of an application can elegantly implement both scriptability and recordability by factoring the application as they develop it. A factored application is one that responds to events in the graphical user interface by sending itself Apple events. So, in BBEdit when you press -N (or choose File New), BBEdit does not simply obey by creating a new text window; rather, it sends itself the Apple event that commands a new text window to be created. BBEdit then receives this Apple eventand -N or a script says "make new text document"; BBEdit ultimately receives the same Apple event in either case, without knowing or caring whether it came from its own graphical user interface or from a script. Picture a factored application as being scriptable at a deep level, with the user interface wrapped around that.

3.11.2. Attachability

The most deeply attachable applications I know are the script editor applications Smile and the earlier version of Script Debugger (version 3). For example, Script Debugger implements attachability through a special compiled script file called Attachments. Let's say you edit this file to give it an execute handler. This means that every time Script Debugger is about to perform its own execute functionality, it performs the code in this handler instead. Script Debugger's execute functionality is what it does when it runs a script in one of its script windows. It doesn't matter whether you trigger this functionality by choosing Script Run, by pressing the Run button in a script window, or by scripting Script Debugger with AppleScript (telling it to "execute a certain window)in all of these cases, Script Debugger does what your customizing code tells it to do, rather than what it would normally do. In other words, Script Debugger is factored, and it permits you to customize all the actions that you could normally perform either through the graphical user interface or through the scripting interface.

Now consider an application like BBEdit. Recall (from "Automatic Location" in Chapter 2) that BBEdit has a factored menu implementation: when you choose a menu item in BBEdit, if there is an appropriately named script in BBEdit's Menu Scripts folder, that script is called, so you can customize what happens in response to that menu item. Is BBEdit attachable? Well, it's certainly not as deeply attachable as Script Debugger, because you can't modify what happens when BBEdit receives the "make new text document" Apple event; if BBEdit receives an Apple event, it's going to do what it normally does, and you have no way to customize that. On the other hand, you can modify what happens when a menu item is chosen, so you are certainly customizing how BBEdit responds to an event in its own graphical user interface. So it seems silly to deny BBEdit attachability on the grounds that it is not fully attachable; it merely implements a milder form of attachability than Script Debugger.

Another application that's attachable in a manner similar to BBEdit is Creator , a layout program from MultiAd. It will call a handler in your script when a document is created, opened, closed, saved, or printed, and your script can override the application's default behavior. (Creator is scriptable in other powerful ways as well. You can dynamically add and remove menu items in the menu bar and in the contextual menu, each menu item having its own scripted functionality; and your scripts can even create dialog boxes and other utility windows, with interface widgets that respond interactively through scripts.)

The sign of an application's being truly attachable, I think, is that a user's script can effectively break the application. A simple script given the special name File·Save and placed in BBEdit's Menu Scripts folder can prevent BBEdit from saving files at all. Thus true attachability is dangerous, which is perhaps one reason why it is so rare. The other applications mentioned in "Automatic Location" in Chapter 2 are willing to run your script at a set moment as a way of customizing their overt behavior, but this is not attachability in the classic sense. Apple Mail, for example, will run a script as part of obeying a rulethat is, as a way of answering the question, "How should I respond when a mail message of a certain type arrives?" But mail will still arrive and rules will still be obeyed. What your script is doing here, therefore, amounts to no more than an elaborate way of setting a preference, and doesn't come under the rubric of true attachability. (See also Chapter 26.)