Scriptability Information
A scriptable application supplies scriptability information that formally lays out the AppleScript object model for the application and maps it to application objects. This scriptability information does two things:
It specifies the terminology available for use in scripts that target the application and supplies comments on the purpose and usage for that terminology.
It provides information, used by AppleScript and by Cocoa, about how support for that terminology is implemented in the application.
This information includes the KVC keys that Cocoa scripting uses to gain access to attribute and relationship information in the application's classes. Without these keys, scripts would not be able to manipulate properties of scriptable objects in the application's object model.
To uniquely identify terms in its scriptability information, an application uses constants called four-character codes (or Apple event codes). A four-character code is just four bytes of data that can be expressed as a string of four characters in the Mac OS Roman encoding. These codes are described in “Code Constants Used in Scriptability Information.”
Within an application's scriptability information, terminology associated with related functionality (for example, operations involving text, graphics, or databases) are generally collected into suites. Cocoa provides the predefined suites described in “Built-in Support for Standard and Text Suites.”
AppleScript uses the application’s scriptability information, including four-character codes, to compile scripts and send Apple events to the application. Cocoa uses the information to interpret received Apple events and create script command objects to perform the specified operations.
In this section:
Scriptability Information Formats
Viewing Scripting Terminology
Built-in Support for Standard and Text Suites
Built-in Support for Basic AppleScript Types
Loading Scriptability Information
Scriptability Information Formats
You define your application’s scriptability information using one of two formats. The first is the scripting definition or sdef format. This is an XML-based format that describes a set of scriptability terms and the commands, classes, constants, and other information that describe the application's scriptability. The sdef format was introduced in Mac OS X version 10.2 and is used natively by Cocoa starting in Mac OS X version 10.4. In the sdef format, an application's scriptability information is contained in a single scripting definition (or sdef) file, with the extension .sdef. The word sdef can be used to describe either the format or a file in that format.
Important: You can read about additional refinements to sdef usage in Cocoa applications for Mac OS X v10.5 in the Scripting section of Foundation Release Notes.
A second, older format uses property list files and is referred to as the script suite format. It supplies Cocoa and AppleScript with roughly the same information, in the form of a script suite file and a corresponding script terminology file:
A script suite file describes scriptable objects in terms of their attributes, relationships, and supported commands, and has the extension
.scriptSuite.A script terminology file provides AppleScript terminology—the English-like words and phrases a scripter can use in a script—for the class and command descriptions in the corresponding script suite file. Script terminology files have the extension
.scriptTerminology.
Defining scriptability information with either of these formats is a bit like defining your application interface with nib files, though you work with text rather than a graphic editor. In both cases you provide information up front that Cocoa uses at specific times to create objects and provide support for the task at hand. The information from an sdef (or the older property list form) is loaded just once per application launch, as described in “Loading Scriptability Information.” The loaded information is then used as needed to create script command objects to perform scriptable operations.
A scripting definition file follows the XML format defined in the sdef man page and described in more detail in “Preparing a Scripting Definition File.” Figure 1-3 shows the main XML elements in an sdef file.
As an example of specific sdef elements, Listing 1-1 shows the graphic and rectangle definitions from Sketch's sdef file. The graphic class defines several properties (such as x position and y position) that are inherited by other shape classes. The rectangle class adds an orientation property and specifies that the object responds to the rotate command, which is specific to rectangles.
Listing 1-1 Graphic and rectangle elements from Sketch's sdef file
... (from the Sketch suite) |
<class name="graphic" code="grph" |
description="A graphic. This abstract class represents the |
individual shapes in a Sketch document. |
There are subclasses for each specific type of graphic."> |
<cocoa class="SKTGraphic"/> |
<property name="x position" code="xpos" type="real" |
description="The x coordinate of the graphic's bounding rectangle."/> |
<property name="y position" code="ypos" type="real" |
description="The y coordinate of the graphic's bounding rectangle."/> |
<property name="width" code="widt" type="real" |
description="The width of the graphic's bounding rectangle."/> |
... (some properties omitted) |
</class> |
<class name="rectangle" code="d2rc" inherits="graphic" |
description="A rectangle graphic."> |
<cocoa class="SKTRectangle"/> |
<property name="orientation" code="orin" type="orientation"/> |
<responds-to name="rotate"> |
<cocoa method="rotate:"/> |
</responds-to> |
</class> |
Viewing Scripting Terminology
Users typically examine scripting terminology in a dictionary viewer to discover which features are scriptable and how to script an application. You can view the scripting terminology for a scriptable application with Script Editor or Xcode. Figure 1-4 shows the sdef file from the Sketch application in a dictionary viewer, with the graphic and rectangle classes visible.
Double-clicking an sdef file in the Finder opens it in a dictionary viewer like the one shown above. Double-clicking an sdef file in an Xcode project similarly opens it in a dictionary viewer window. To view or edit the XML for the file, open the sdef file with any plain text editor; in Xcode, select the sdef file and choose File > Open As > Plain Text File.
For related information, see “Editing Scriptability Information.”
Built-in Support for Standard and Text Suites
A scriptable application typically supports certain standard AppleScript terms, such as the count and make commands and the application class. Cocoa provides built-in support for these terms in the Standard suite. It also provides command classes, including NSCountCommand and NSCreateCommand, to implement standard commands. In addition, classes such as NSApplication and NSDocument implement certain aspects of standard scripting support.
Cocoa scripting also provides support for the get and set commands, including implementation of the command classes NSGetCommand and NSSetCommand. These commands are not part of the Standard suite, but are considered built-in AppleScript commands. Allowing scripters to get and set the values of properties and elements of scriptable objects is a key part of making an application scriptable.
Note: Though "Standard suite" is the current name, you may see it referred to as the "Core suite" (and you may see filenames that include “Core”). That usage dates back to the early days of AppleScript.
The Standard suite defines the following AppleScript commands: (for all classes) copy, count, create, delete, exists, and move; (for documents and windows) print, save, close. Note that there is no default implementation for the print command—see “Print” for information on how to support printing.
To support text-related classes such as rich text, word, and paragraph, Cocoa implements the Text suite.
Cocoa’s built-in support for the Standard and Text suites is described in more detail in “Use the Document Architecture” and “Access the Text Suite.” To include it in your application, you follow the steps described in “Turn On Scripting Support in Your Application”.
Built-in Support for Basic AppleScript Types
Cocoa scripting provides built-in support for basic AppleScript types and automatically associates them with appropriate Cocoa data types, as shown in Table 1-1. You can use these types without declaring them in your sdef file.
AppleScript type | Cocoa type | Code |
|---|---|---|
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|
| |
| ||
This type is used as the type of the |
| |
|
| |
| ||
|
| |
|
Loading Scriptability Information
When an application first needs to work with scriptability information, Cocoa scripting uses a global instance of NSScriptSuiteRegistry to load information from the application's sdef file:
For each class described in the sdef file, it instantiates a class description object (
NSScriptClassDescription) that stores information about objects of that type.This information includes the KVC keys that Cocoa scripting uses to access values of the application's scriptable objects.
For each script command described in the sdef file, it registers a handler routine for Apple events that specify that command.
It also instantiates a command description object (
NSScriptCommandDescription) that stores information such as the name of the scripting command class to instantiate to perform the command, as well as the command's arguments, and return type (if any).
Figure 1-5 shows the loaded class and command descriptions for an application. Cocoa uses the information to create instances of command classes and descriptions of application objects that it needs to handle Apple events received by the application.
Important: You don't typically instantiate scripting commands in your application—you list the commands your application supports in your sdef file and Cocoa instantiates them when your application receives the corresponding Apple events.
See “How Cocoa Applications Handle Apple Events” for information on how Cocoa handles Apple events other than those that are part of your application's scriptability information.
Application scriptability information automatically includes information to support the basic AppleScript types listed in Table 1-1 and to make the get and set commands available to all applications.
Last updated: 2008-03-11
  |
||
|
|
|
|
| ||
Get information on Apple products.
Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice |