Cocoa Scripting Guide: Script Suite Files

< Previous PageNext Page >

Hide TOC

Script Suite Files

A script suite file describes scriptable objects in terms of their attributes, relationships, and supported commands. You can think of a script suite file as supplying scripting information for use by Cocoa’s internal scripting support; that information can also be used by your application. “Script Terminology Files” describes the files used to store the scripting terminology that corresponds to the information in a script suite file. That terminology defines the terms actually used by scripters to control the application.

The information in a script suite file consists of a nested list of key-value pairs. Script suites are always property lists, but in addition they must conform to the format described in “The Structure of a Script Suite File.” For information on creating them, see “Creating Your Own Script Suite Files.”

Frameworks, loadable bundles, and applications that support scripting can include a script suite file as a language-independent resource. The name of the file takes the form suiteName.scriptSuite, where suiteName uniquely identifies the script suite file. An example would be MyApplication.scriptSuite.

Script suites are located in the (nonlocalized) Resources directory of an application, framework, or bundle. For example, for a framework named MyStuff.framework, the script suite file (named MyStuff.scriptSuite) would reside in MyStuff.framework/Resources/.

Listing B-1 shows the class description for the NSApplication class, taken from NSCoreSuite.scriptSuite, Cocoa's script suite file for the AppleScript Standard suite. The class description is shown as exported in “XML Property List File” format by the Property List Editor application. You can find the full version of this script suite file on your system by following the Resources symbolic link at /System/Library/Frameworks/Foundation.framework.

Listing B-1 NSApplication class from the script suite file for the Standard suite

        <key>NSApplication</key>

        <dict>

            <key>AppleEventCode</key>

            <string>capp</string>

            <key>Attributes</key>

            <dict>

                <key>isActive</key>

                <dict>

                    <key>AppleEventCode</key>

                    <string>pisf</string>

                    <key>ReadOnly</key>

                    <string>YES</string>

                    <key>Type</key>

                    <string>NSNumber&lt;Bool&gt;</string>

                </dict>

                <key>name</key>

                <dict>

                    <key>AppleEventCode</key>

                    <string>pnam</string>

                    <key>ReadOnly</key>

                    <string>YES</string>

                    <key>Type</key>

                    <string>NSString</string>

                </dict>

                <key>version</key>

                <dict>

                    <key>AppleEventCode</key>

                    <string>vers</string>

                    <key>ReadOnly</key>

                    <string>YES</string>

                    <key>Type</key>

                    <string>NSString</string>

                </dict>

            </dict>

            <key>Superclass</key>

            <string>NSCoreSuite.AbstractObject</string>

            <key>SupportedCommands</key>

            <dict>

                <key>NSCoreSuite.Open</key>

                <string>handleOpenScriptCommand:</string>

                <key>NSCoreSuite.Print</key>

                <string>handlePrintScriptCommand:</string>

                <key>NSCoreSuite.Quit</key>

                <string>handleQuitScriptCommand:</string>

            </dict>

            <key>ToManyRelationships</key>

            <dict>

                <key>orderedDocuments</key>

                <dict>

                    <key>AppleEventCode</key>

                    <string>docu</string>

                    <key>LocationRequiredToCreate</key>

                    <string>NO</string>

                    <key>ReadOnly</key>

                    <string>YES</string>

                    <key>Type</key>

                    <string>NSDocument</string>

                </dict>

                <key>orderedWindows</key>

                <dict>

                    <key>AppleEventCode</key>

                    <string>cwin</string>

                    <key>ReadOnly</key>

                    <string>YES</string>

                    <key>Type</key>

                    <string>NSWindow</string>

                </dict>

            </dict>

        </dict>

Each scriptable class in a script suite file must have a “class description” which, in key-value form, declares the attributes and relationships of the class in terms of type and four-character code (or Apple event code). For example, the four-character code for NSApplication in Listing B-1 is the string "capp". You can read more about four-character codes in “Code Constants Used in Scriptability Information.” The primary key for a class description must be a class name such as NSApplication that identifies a real Objective-C class.

The class description also declares the AppleScript commands the class supports and specifies the superclass, if the superclass also supports scripting of its objects. In this case, the superclass for NSApplication is AbstractObject, which is the root of the scriptable class hierarchy, and corresponds to the NSObject class.

The Structure of a Script Suite File

A script suite file is a text file containing key-value pairs in the form of a series of nested dictionaries, with two main categories: class descriptions and command descriptions.

A class description describes the attributes and relationships of a scriptable class. Relationships can be one-to-one or one-to-many. A class description also lists the commands a class supports and specifies whether a particular method of the class handles the command or the command’s default implementation is used to execute the command. A description of a class can designate a scriptable superclass, and thus inherit the attributes, relationships, and supported commands of that class. Class descriptions for the classes defined in an application's script suite file are instantiated by the global instance of NSScriptSuiteRegistry when it loads the application's scriptability information.

A command description defines the characteristics of an AppleScript command that the application, framework, or bundle specifically supports. This information includes the class of the command, the type of the return value, and the number and types of arguments. Many of the commands defined in the Standard suite (such as copy, duplicate, move, and so on) have default implementations in subclasses of NSScriptCommand, listed in “Subclasses for Standard AppleScript Commands.” Command descriptions for the commands defined in an application's script suite file are instantiated by the global instance of NSScriptSuiteRegistry when it loads the application's scriptability information. For more information on the script command mechanism, see “Script Commands.”

A script suite file may contain additional declarations, such as enumerations. For example, NSCoreSuite.scriptSuite contains a declaration for the SaveOptions enumeration, which defines the AppleScript values for yes, no, and ask that are used when closing a file.

The following tables describe the structure of a script suite file, including its optional and required keys.

**Table B-1** Suite dictionary
Key	Value type or reference	Description
“name”	`NSString`	Name of suite (required); the name can be placed anywhere in the definition, as long as it is a first-level element
“`AppleEventCode`”	`NSString`	Four-character code for this suite (required)
“`Classes`”	Class list dictionary (Table B-2)	optional (no classes defined by default)
“`Commands`”	Command list dictionary (Table B-7)	optional (no classes defined by default)
“`Synonyms`”	Synonym list dictionary (Table B-10)	optional (no synonyms defined by default)
“`Enumerations`”	Enumeration list dictionary (Table B-11)	optional (no enumerations defined by default)

**Table B-2** Class list dictionary
Key	Reference	Description
“className”	Class dictionary (Table B-3)	One per each scriptable class. Must be the name of an Objective-C class defined by Cocoa or the application.

**Table B-3** Class dictionary
Key	Value type or reference	Description
“`Superclass`”	`NSString`	Scriptable superclass; must be the name of an Objective-C class. All attributes, relationships, and supported commands are inherited and can be overridden. You can use the notation suiteName.className to designate the class. (Optional.) You can also use the `AbstractObject` class to specify a base class your scriptable classes can inherit from that contains no scriptability of its own.
“`AppleEventCode`”	`NSString`	Four-character code for this class (required)
“`Attributes`”	Property list dictionary (Table B-4)	Attributes of the class (optional)
“`ToOneRelationships`”	Property list dictionary (Table B-4)	One-to-one relationships of the class (optional)
“`ToManyRelationships`”	Property list dictionary (Table B-4)	One-to-many relationships of the class (optional)
“`SupportedCommands`”	Supported commands dictionary (Table B-6)	Commands supported by the class (optional)

**Table B-4** Property list dictionary
Key	Reference	Description
“propertyName”	Property dictionary (Table B-5)	Definition of an attribute or relationship. attributeName should map to an instance variable of the class for which there are accessor methods.

**Table B-5** Property dictionary
Key	Value type	Description
“`Type`”	`NSString`	Name of class of values of this property (required)
“`AppleEventCode`”	`NSString`	Four-character code for this suite (required)
“`ReadOnly`”	`NSString`	“Yes” or “No” (optional; “No” by default)

**Table B-6** Supported commands dictionary
Key	Value type	Description
“commandName”	`NSString`	Name of method this class uses to implement the command or ““ if the default implementation is sufficient. commandName should be in suiteName.commandName notation if command is not in the same suite as the class.

**Table B-7** Command list dictionary
Key	Reference	Description
“commandName”	Command dictionary (Table B-12)	Command definition.

**Table B-8** Command dictionary
Key	Value type or reference	Description
“`CommandClass`”	`NSString`	Class of command. Set this value to `NSScriptCommand` for default behavior. If not using default, must be set to a subclass of `NSScriptCommand` (required).
“`AppleEventCode`”	`NSString`	Four-character code for this command (required)
“`AppleEventClassCode`”	`NSString`	Four-character class constant for this command (optional; by default, is the constant for the script suite)
“`Type`”	`NSString`	Class name of result of command or “” if no result (optional; no result by default)
“`ResultAppleEventCode`”	`NSString`	Four-character code for the return type of the command. Must be present if “Type” value is assigned. Can be “****” if the return type is variable.
“`Arguments`”	Argument list dictionary (Table B-13)	Arguments of command (optional; no arguments by default)

**Table B-9** Argument list dictionary
Key	Value type or reference	Description
“`Type`”	`NSString`	Name of class for this argument (required)
“`AppleEventCode`”	`NSString`	Four-character code for this argument (required)
“`Optional`”	`NSString`	“Yes” or “No” (optional; “No” by default)

**Table B-10** Synonym list dictionary
Key	Value type or reference	Description
“`Apple event code`”	`NSString`	Class name for which four-character code is a synonym.

**Table B-11** Enumeration list dictionary
Key	Reference	Description
“enumerationName”	Enumeration dictionary (Table B-12)	One per enumeration.

**Table B-12** Enumeration dictionary
Key	Value type or reference	Description
“`AppleEventCode`”	`NSString`	Four-character code for this enumeration (required)
“`Enumerators`”	Enumerators list dictionary (Table B-13)	Enumerators in the enumeration (required)

**Table B-13** Enumerators dictionary
Key	Value type or reference	Description
“enumeratorName”	`NSString`	Four-character Apple event code for this enumerator (required)

< Previous PageNext Page >

Hide TOC

Last updated: 2008-03-11

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	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