Next Previous

Cocoa Scripting Classes and Categories

The tables in this chapter provide brief descriptions for the listed Cocoa scripting classes. The accompanying material provides information on when your application uses these classes, as well as hints on which ones you might need to subclass.

About thirty public classes in Cocoa's Foundation framework support the basic structure of Cocoa scripting. Several methods in the Application Kit framework add scriptability features for applications, windows, documents, and text objects. Together, this provides support for the AppleScript commands listed in Summary of AppleScript Command Support (such as get, set, move, delete, and so on).

In many cases, Cocoa scripting creates and manipulates instances of these classes, such that your application needs only to respond when a method of a particular application object is invoked. That is, your application rarely needs to declare or instantiate any of the basic Cocoa scripting classes.

On the other hand, some applications will need to define subclasses of one or more of Cocoa scripting's command classes to provide support for operations specific to the application. Even in those cases, however, the application is not responsible for creating instances of the commands—Cocoa scripting does that, based on the scriptability information provided in the application's sdef file. The process of working with commands is described in detail in Script Commands.

There is one case where your application typically creates instances of Cocoa scripting classes. In object specifier methods for your scriptable classes, you'll create instances of the object specifier classes listed in Table 9-2.

Script Commands and Scriptability Information

The following classes provide the base class for script commands, the context in which commands are executed, and the scriptability information associated with an application. Instances of these classes are created automatically by the Cocoa scripting, in a process described in Script Commands Overview. Except for NSScriptCommand, most applications will not need to subclass or even call methods of these classes.

**Table 9-1** Scripting information and command classes
Class	Description
`NSScriptSuiteRegistry`	A shared instance of this class loads and registers the scriptability information associated with an application, whether from sdef files or the older script suite and script terminology files. Provides methods to get loaded suites, class descriptions, and command descriptions, but applications rarely call these methods.
`NSClassDescription`	Abstract class that provides the interface for querying the properties of a class. Instantiated by the global instance of `NSScriptSuiteRegistry` when it loads the application's scriptability information.
`NSScriptClassDescription`	A subclass of `NSClassDescription` that represents a description of a scriptable class in a script suite. Provides methods to get attributes, relationships, supported commands, and related information for a scriptable class. Instantiated by the global instance of `NSScriptSuiteRegistry` when it loads the application's scriptability information.
`NSScriptCommandDescription`	A subclass of `NSObject` that represents a definition of a command supported by a suite. Provides methods to get command class and return and argument types for a script command class. Instantiated by the global instance of `NSScriptSuiteRegistry` when it loads the application's scriptability information.
`NSScriptCommand`	Encapsulates an AppleScript command sent to an application as an Apple event. Uses its methods to evaluate object references (receivers and arguments) and execute the command. Cocoa scripting subclasses for the major AppleScript commands are described in Table 9-4. You can create your own subclasses to handle operations specific to your application. For more information, see Object-first Versus Verb-first Script Commands.
`NSScriptExecutionContext`	Represents the context in which an AppleScript command is executed and tracks global state related to that command. You do not need to subclass this class.

Object Specifiers, Logical Tests, and Related Categories

NSScriptObjectSpecifier, an abstract class. Instances of these classes—object specifiers—know how to evaluate themselves within the context of a container object specifier. Some of these classes represent relative or logical tests performed with object specifiers (particularly NSWhoseSpecifier objects).

These are among the few classes provided by Cocoa scripting that your application routinely instantiates. It does so when creating object specifiers. You shouldn’t need to subclass these classes, but you will need to implement some of the methods in the described categories, particularly in providing object specifier methods for your scriptable objects. For detailed information, see Object Specifiers.

**Table 9-2** Object specifiers and related classes
Class or category	Description
`NSScriptObjectSpecifier`	An abstract parent class for subclasses that represent AppleScript references. An object specifier knows how to evaluate itself (to actual objects) in the context of a container specifier.
`NSIndexSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify an object in a collection by index. Though scripters typically specify one-based items, an index specifier, which typically locates objects within an array that correspond to the specified items, uses zero-based values.
`NSMiddleSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify the middle object in a collection.
`NSNameSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify an object in a collection by name.
`NSPositionalSpecifier`	A subclass of `NSObject` for object specifiers that represent an insertion point by reference to a point before or after another object, or at the beginning or end of a collection. It contains an object specifier that represents the object referred to for position.
`NSPropertySpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that represent an attribute or relationship of an object.
`NSRandomSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify an arbitrary object in a collection.
`NSRangeSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify a range of objects in a collection by indexes. Though scripters typically specify a one-based range of items, a range specifier, which typically locates objects within an array that correspond to the specified items, uses zero-based values.
`NSRelativeSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify the position of an object in relation to another object.
`NSUniqueIDSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify an object in a collection by unique ID.
`NSWhoseSpecifier`	A subclass of `NSScriptObjectSpecifier` for object specifiers that specify an object in a collection that matches a specified condition defined by a Boolean expression.
`NSScriptObjectSpecifiers`	Category on `NSObject` that defines methods that scriptable objects can implement to provide a fully specified object specifier to themselves within an application, and to perform their own specifier evaluation.
`NSLogicalTest`	A subclass of `NSScriptWhoseTest` for objects that represent the Boolean operations `AND`, `OR`, and `NOT`; used with one or more instances of `NSSpecifierTest`.
`NSSpecifierTest`	A subclass of `NSScriptWhoseTest` for objects that represent a comparison between two objects (which can be object references before being evaluated) using a given comparison method.
`NSScriptWhoseTest`	An abstract class for objects that represent Boolean expressions (qualifiers) involving object specifiers (also called `whose` clauses, as in `every word whose color is blue`).
`NSComparisonMethods`	Category on `NSObject` that defines a set of default comparison methods useful for the comparisons in `NSSpecifierTest`.
`NSScriptingComparisonMethods`	Category on `NSObject` that defines a set of additional comparison methods you may need to implement for comparisons in cases where the correct way to compare two objects for scripting is different from the correct way to compare objects otherwise.

Key-Value Coding and Value Coercion

The following perform essential functions related to scripting. For information on the use of these classes, see Key-Value Coding and Cocoa Scripting and Coercion.

**Table 9-3** Scripting utilities
Class or category	Description
`NSScriptCoercionHandler`	A shared instance of this class coerces object values to objects of another class, using information supplied by classes who register with it. Coercions frequently are required during key-value coding. For more information, see Coercion.
`NSScriptKeyValueCoding`	Category on `NSObject` that defines additions to the implementation of key-value coding related to scripting, such as getting and setting key values by index in collections and coercing (or converting) a key value.

Subclasses for Standard AppleScript Commands

The following classes implement standard AppleScript commands. They are all subclasses of NSScriptCommand, which is described in Table 9-1. Your application can create a subclass of one of these classes to replace the default behavior, or to selectively modify that behavior in some circumstances. In most cases, the default behavior should be sufficient.

For more information on working with commands, see Script Commands.

**Table 9-4** Subclasses for standard script commands
Class	Description
`NSCloneCommand`	Copies the specified scriptable object or objects (such as words, paragraphs, images, and so on) and inserts them in the specified location. This class handles the `duplicate` AppleScript command.
`NSCloseCommand`	Closes the specified scriptable object or objects—typically a document or window.
`NSCountCommand`	Counts the number of items of a specified class in the specified object container (such as the number of rectangles in a document).
`NSCreateCommand`	Creates the specified scriptable object (such as a document or graphic), optionally supplying the new object with the specified attributes. This class handles the `make` AppleScript command.
`NSDeleteCommand`	Deletes the specified scriptable object or objects.
`NSExistsCommand`	Determines whether a specified scriptable object, such as a word, paragraph, or image, exists.
`NSGetCommand`	Gets the specified value or object from the specified scriptable object. For related information, see Getting and Setting Properties and Elements.
`NSMoveCommand`	Moves the specified scriptable object or objects. For related information, see Modifying a Standard Command.
`NSQuitCommand`	Quits the specified application.
`NSSetCommand`	Sets one or more attributes or relationships of the specified scriptable object to one or more values. For related information, see Getting and Setting Properties and Elements.

Manipulation of Apple Events

You can use the following classes to directly manipulate Apple events and the data structures they contain. However, you can make your application scriptable with little or no direct use of these classes.

**Table 9-5** Classes for manipulating Apple events
Class	Description
`NSAppleEventDescriptor`	Represents a descriptor, the basic building block for Apple events. Descriptors can consist of arbitrarily nested lists of other descriptors. Every Apple event is itself a descriptor and is made up of descriptors. For information on the underlying structure of descriptors, see Building an Apple Event in Apple Events Programming Guide.
`NSAppleEventManager`	Provides access to a small set of Apple Event Manager features. Used primarily for directly registering Apple event handlers and for suspending and resuming Apple events (described in Suspending and Resuming Apple Events and Script Commands). For background information, see Apple Event Manager Reference and Apple Events Programming Guide.
`NSAppleScript`	Provides the ability to load, compile, and execute scripts.

Next Previous