Object Specifiers and KVC

Cocoa scripting relies on key-value coding (KVC) when evaluating object specifiers. When an application first needs to work with scriptability information, Cocoa scripting loads information from the application's sdef file into a global instance of NSScriptSuiteRegistry. At that time, it registers class descriptions for your scriptable classes. As a result, Cocoa and your application can obtain script class description information, including keys, about scriptable classes for use with object specifiers.

For more information, see Loading Scriptability Information.

When to Implement an Object Specifier Method

Any class in your application that is part of the containment hierarchy for your scriptability support will most likely require an object specifier method. When a script statement targets your application, the application may need to return a reply. For example, the result of a get command is often an object or a list of objects. When Cocoa returns these objects in the reply Apple event, it does not return pointers to Objective-C objects, it returns object specifiers that locate scriptable objects within the containment hierarchy. As part of building these specifiers, Cocoa calls on your scriptable objects to supply specifiers for themselves.

You provide an object specifier for a scriptable class by implementing the objectSpecifier method. That method is defined in NSScriptObjectSpecifiers (note the trailing "s"), a category on NSObject that implements a version that just returns nil.

About Object Specifier Classes

An objectSpecifier method returns an instance of one of the classes listed in Table 6-1, which are subclasses of NSScriptObjectSpecifier. Classes such as NSNameSpecifier and NSUniqueIDSpecifier represent the standard AppleScript reference forms, so you shouldn't need to subclass them. You pick the best version for the object you need to specify—see Scripting Interface Guidelines for guidance. For example, if the object has a unique name or unique ID, use the corresponding specifier type. For an unnamed object with no ID, such as a rectangle or a paragraph of text, you may want to return an index specifier.

Most subclasses of NSScriptObjectSpecifier have a specific initializer that you should use.

Most initializer methods for an object specifier class include the following parameters:

• (NSScriptClassDescription *)classDescription

  Here you supply a class description for the container class of the specified object. You must always supply a class description for a specifier.

  If you already have an object specifier for a container, you can obtain a class description for that container object using the NSScriptObjectSpecifier method keyClassDescription, as shown in Listing 6-1.

  When you can get the class of a container object (for example, by invoking [NSApp class]), you can use the classDescriptionForClass method to determine the container description, as shown in Listing 6-2. If you have an instance of the container’s class, you can instead use the NSObject instance method classDescription to obtain a container description.

• (NSScriptObjectSpecifier *)specifier

  Here you supply an object specifier for the parent container of the specified object. You typically obtain it by invoking the objectSpecifier method of the containing object.

  An object that has no container specifier is known as the top-level specifier. In most cases, the top-level specifier is the application itself. You can specify the top-level specifier by passing nil for this parameter. (That is the only time you can pass nil for a container specifier, and even then you must specify a container class description.)

• (NSString *)key

  Here you supply a key that tells the parent container how to find the specified object. The key you pass is based on information supplied in your sdef file. For example, Sketch defines the "graphics" key to identify the graphics array in a Sketch document. (Sketch actually defines the singular "graphic" as an element of the document class, but Cocoa scripting applies its default rules, described in Provide Keys for Key-Value Coding, to convert this key to the string "graphics".)

For an annotated example of an objectSpecifier method, see An Object Specifier Method for a Rectangle in Sketch.

A Closer Look at an Object Specifier

Consider the object model and containment hierarchy diagram for the Sketch sample application, shown in Figure 6-1. The left side of this illustration shows scriptable Sketch objects, the right side the corresponding application containment hierarchy. For a script statement that identifies a rectangle object on the left, Cocoa scripting supplies an object specifier that locates the rectangle and its containing document within the containment hierarchy on the right.

Each object specifier contains a reference to its containing object, which allows object specifiers to represent objects that can be deeply nested within an object hierarchy. The outermost container, represented by a nil object specifier, is usually the application object, although it can be an object specifier involved in a whose clause (NSWhoseSpecifier) or the container for a range evaluation.

Figure 6-2 shows the nested object specifiers for the statement first rectangle in document "SketchDocOne":

Here is how to interpret the information in this figure:

1. An index specifier specifies the first rectangle, which is an object of class SKTRectangle. The specifier has these components:

   • The index for the specified object, which in this example has the value 0.

     This is the zero-based index of the specified rectangle in its containing array. Because Sketch's graphics arrays can contain other kinds of graphics, the index for the first rectangle won't always have the value 0—for example, if preceded by four circle graphics, the index would have the value 4.

   • A key that specifies the collection for the specified object, which in this example has the value "graphics".

     The graphics array is the collection for the indexed object. The key matches information provided by your sdef and made available in the running application as described in Object Specifiers and KVC.

   • A container reference that specifies the parent for this object specifier. In this example the container is the object specifier for the document "SketchDocOne".

2. A name specifier specifies the document containing the first rectangle, which is an object of class SKTDrawDocument. The specifier has these components:

   • The name for the specified object, which in this example has the value "SketchDocOne".

   • A key that specifies the collection for the specified object, which in this example has the value "orderedDocuments".

     The application's ordered array of documents is the collection for the named document, though in this case, the order is unimportant.

   • A container reference that specifies the parent for this object specifier. In this example, the reference is nil, specifying that the array of documents is contained by the application object.

   A script statement, and thus an object specifier, can specify objects that don't currently exist in the application, causing an error condition when the script is executed. For example, the specified document may not exist, or it may not contain the specified graphic. Code within a command class should check for and be prepared to handle common error conditions. (Validation is not considered appropriate for KVC getter and setter methods.)

Evaluation of Nested Specifiers

When Cocoa scripting prepares a script command for a script that contains a reference, it converts the reference into a nested series of object specifiers, such as the ones shown in Figure 6-2. It packages these nested object specifiers as a receiver of the command (or in some cases as an argument of the command). When the command is executed, the application evaluates the object specifiers in its own context to discover the specified objects.

Evaluation starts with the top-level specifier and proceeds down the chain of object specifiers, evaluating and resolving each until the identity of the final, nested child object is determined. This object is a receiver (or receivers) of the command or one of the command’s arguments. Key-value coding is used as the standard mechanism for evaluation. An object specifier queries its evaluated container for the value of the key associated with the object specifier.

Evaluation of object specifiers is described in more detail in Script Commands and Object Specifiers.

An Object Specifier Method for a Rectangle in Sketch

Listing 6-1 shows how the Sketch sample application (available from Apple) implements the objectSpecifier method for the SKTGraphic class.

Listing 6-1  An object specifier method for a rectangle

- (NSScriptObjectSpecifier *)objectSpecifier{

    NSArray *graphics = [[self document] graphics];// 1

    unsigned index = [graphics indexOfObjectIdenticalTo:self];// 2

    if (index != NSNotFound) {

       NSScriptObjectSpecifier *containerRef = [[self document] objectSpecifier];// 3

        return [[[NSIndexSpecifier allocWithZone:[self zone]]

            initWithContainerClassDescription:[containerRef keyClassDescription]

            containerSpecifier:containerRef key:@"graphics" index:index] autorelease];// 4

    } else {

        return nil;// 5

    }

}

Here’s a description of how this method provides an object specifier for a graphics object. The returned specifier consists of an index specifier for the graphic in its container, and a container specifier for the document that contains the array of graphics:

1. From its document, it gets the array of graphics and determines the index of the receiving graphic, if it is contained in the array.

2. It gets the object specifier of the document that contains the graphic.

   Sketch defines the SKTDrawDocument class as a subclass of NSDocument. The object specifier method for NSDocument returns an instance of NSNameSpecifier that identifies the document by name within the application's array of ordered documents.

3. It creates and initializes an index specifier (type NSIndexSpecifier) for the receiving graphic and returns it.

   The specifier locates the graphic by index within the graphics in its document. Although an AppleScript script asks for indexed items as though they are one-based, this index specifier, which locates objects within an array that correspond to the specified items, works with zero-based values. For information about the other parameters, see About Object Specifier Classes.

Specifying the Application Object as a Container

To specify the application object as the top-level container for a specifier, you can use code like the following. This snippet is part of the document class and obtains an object specifier for the document by name (rather than by index, which may become invalid if the document ordering changes):

Listing 6-2  Specifying the application as a container

NSScriptClassDescription *containerClassDesc = (NSScriptClassDescription *)

    [NSScriptClassDescription classDescriptionForClass:[NSApp class]];// 1

return [[[NSNameSpecifier alloc]

    initWithContainerClassDescription:containerClassDesc

    containerSpecifier:nil key:@"orderedDocuments"

    name:[self lastComponentOfFileName]] autorelease];// 2

Here’s a description of what this code snippet does:

1. The application is the container for a list of ordered documents, so this code first obtains a class description from the global application object, NSApp. (You never pass nil for the class description.)

2. It then creates and returns an autoreleased object specifier of type NSNameSpecifier, passing nil for the containerSpecifier parameter to specify the top-level container, the application. (This is the only case in which you can pass nil for the container.)

   It invokes the NSDocument method lastComponentOfFileName to obtain the name of the document and uses it to construct a name specifier object.