Inside Macintosh: AppleScript Language Guide / Part 2 - AppleScript Language Reference

Chapter 4 - Commands / Types of Commands

Scripting Addition Commands

Scripting additions are files that provide additional commands or coercions you can use in scripts. Each scripting addition can contain one or more command handlers. If a scripting addition is located in the Scripting Additions folder (in the Extensions folder of the System Folder), the command handlers it provides are available for use by any script whose target is an application on that computer.

Like the target of an application command, the target of a scripting addition command is always an application object or a script object. If the script doesn't explicitly specify the target with a Tell statement, AppleScript sends the command to the default target application, which is usually the application running the script (for example, the Script Editor).

A scripting addition command performs its action only after the command has been received by a target application. Unlike application commands, scripting addition commands always work the same way regardless of the application to which they are sent.

For example, the scripting addition command Display Dialog displays a dialog box that can include text, one or more buttons, an icon, and a field in which the user can type text. In the script that follows, the target of the Display Dialog command is the Scriptable Text Editor application. When the script runs, the Scriptable Text Editor becomes the frontmost application (that is, its menus become visible and its windows become the frontmost windows on the screen) and passes the command to the scripting addition's handler for the Display Dialog command, which displays the dialog box.

tell application "Scriptable Text Editor"
   display dialog "What's your name?" default answer ""
end tell

In the next example, the Display Dialog command is not enclosed in a Tell statement, nor does it have a direct parameter, so its target is the Script Editor (or whatever application runs the script). When you run the script, the Script Editor passes the command to the scripting addition's handler for the Display Dialog command, which displays the dialog box in the Script Editor's layer (that is, in front of any other Script Editor windows that may be open), while the Script Editor is still the active application.

set theCount to number of words in front document of ÿ
   app "Scriptable Text Editor"
if theCount > 500 then
   display dialog "You have exceeded your word limit." 
end

Each scripting addition that contains command handlers has its own dictionary, which lists the reserved words--including the command names, parameter labels, and in some cases object names--used to invoke the commands supported by the scripting addition. If a scripting addition dictionary includes words that are also part of an application dictionary, then you cannot use
those words within Tell statements to that application.

For example, the Offset command provided by the String Commands scripting addition reports the offset, in characters, of a string within another string. Offset is also a property of several Scriptable Text Editor objects and is thus a word in the Scriptable Text Editor dictionary. Therefore, you cannot use Offset as a scripting addition command within Tell statements to the Scriptable Text Editor. If you do, you'll get a syntax error, because AppleScript treats the word Offset as a property of a text object.

tell front document of application "Scriptable Text Editor"
   offset of "great" in "To be great"
end tell
--result: syntax error

If you specify a script object as the target of a scripting addition command, the script object either handles the command itself (potentially modifying it) or passes the command to the default target application. For more information about scripting additions and script objects, see "Using Continue Statements to Pass Commands to Applications," which begins on page 280.

For information about the scripting additions available for AppleScript English and definitions of the commands they provide, see the AppleScript Scripting Additions Guide.