Dictionary
Suite
Value Type
Record Type
Property
Enumeration
Enumerator

Class
Class Extension
Contents
Element
Property
Responds to

Command/Event
Direct Parameter
Parameter
Result

Other Elements
Documentation
Synonym
Cocoa
Type
XRef

Common Attributes
History
Bugs

Scripting Definition Reference


Scripting definition files (sdefs) are XML files that describe everything about an application’s scriptability: terminology, implementation information, and complete documentation. sdp(1) uses sdefs to generate a variety of implementation and definition files for use in an application and in AppleScript.

For basic concepts and style guidelines, see Technical Note TN2106, Scripting Interface Guidelines

If you have already been working with sdefs in Mac OS X 10.2, 10.3 or 10.4, read the History section, since the format has changed in 10.4 and 10.5.

If you are using Cocoa, Cocoa Scripting as of Mac OS X 10.4 (Tiger) supports using sdefs directly rather than preprocessing them with sdp(1). See the Sdef Scriptability Guide for Cocoa for details. (However, also see the Bugs section.)


Class

A class element is an abstract object definition that lists the properties, elements, and supported verbs for instances of that scriptable class. Class instances are called “objects”.

Every class should have a human-readable name and description and a four-character code to identify it. A class also typically specifies its properties (or attributes and to-one relationships) and elements (to-many relationships). A class element also lists the commands it responds to, using the responds-to element.

Attributes

name
See Commons Attributes.
id
See Commons Attributes.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.
plural
The plural name of the class. If omitted, defaults to the name with 's' appended.
inherits
The class, if any, that this one descends from.

Implementation

cocoa → class
The Cocoa or application Objective-C class that implements the class.

Class Extension

Class Extension is an extension to an existing class. In Objective-C terms, a category. Use one of these when you want to add behavior to an existing class, such as the base “application” class, without defining a subclass. You can also use it to break a class definition across multiple suites.

A class-extension has mostly the same content as a class, but because it is extending an existing class, it does not define its own name or code, but instead an extends attribute, and does not have a cocoa element.

Warning: class-extension is only available in Leopard and above. See History for details.

Attributes

extends
The name of the class this element extends.
id
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.

Command

Commands (aka method, member function.) and events, collectively called “verbs”, are messages that may be sent to an object. For documentation purposes, Scripting Definitions distinguish between commands, which are verbs a script would send to an object (e.g., “close”), and events, which are notifications sent to an object by a framework or system service (e.g., “did close”).

Unlike most object-oriented languages, verbs are defined independently of any particular class. A class may then list the verbs that it responds to. To Java and Objective-C programmers, Scripting Definitions verbs therefore resemble protocols more than member functions. You may specify the same command more than once with different parameters, such as to define a polymorphic “open” command that has different parameters depending on whether it is applied to a document or a database.

Attributes

name
See Commons Attributes.
id
See Commons Attributes.
code
See Commons Attributes. The code for a command and events is eight characters in length.
description
See Commons Attributes.
hidden
See Commons Attributes.

Implementation

cocoa → class
The Objective-C class, defined by Cocoa or the application, that Cocoa scripting should instantiate to handle the command (default is NSScriptCommand).
cocoa → name
A name used internally by Cocoa Scripting.

Contents

Contents is a special type of property: like a property, it defines a unique data member, but its name and code are optional. If omitted, they default to “contents” and ‘pcnt’, respectively. There may be at most one contents element in a class.

In Mac OS X 10.2 and later, Cocoa Scripting will treat the contents property as its class's implied container. Scripts may refer to properties and elements of the contents property as if they were elements of the class. For example, TextEdit documents have a “text” contents property. Technically, the first word of a document is “word 1 of text of document 1”, but because “text” is an implied container, a script can also say “word 1 of document 1”.

Attributes

name
See Commons Attributes.
code
See Commons Attributes.
type
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.
access
The allowed access for the contents: Read-only ('r'), Write-only ('w') or Read & Write ('rw').
Default is Read & Write.

Implementation

cocoa → key
An optional KVC key to be used by Cocoa scripting to access the element.

Dictionary

The root XML element in an sdef file is a dictionary element. A dictionary defines all the scriptability information for one application. Every sdef file you create should contain one dictionary definition. You typically name the dictionary after the application.

A dictionary element contains one or more suite elements. Most Cocoa applications include Cocoa’s default suites (the Standard and Text suites), as well as one or more suites of their own scriptability information.

Attributes

title
The title of the dictionary, which appears in the dictionary display.

Direct Parameter

direct-parameter is a special type of parameter: like a parameter, it defines a value included with a verb, but it has no name or code attribute, and may not be hidden. There may be at most one direct-parameter element in a verb.

The direct parameter of a verb is a value that appears immediately after the verb and specifies its target. The type of the direct parameter is usually an application class. For example, in the command “close window 1”, the direct parameter is “window 1”. Not all verbs have a direct parameter, in such cases, omit this element.

In Cocoa Scripting, the direct parameter is the object to which the message is sent (i.e., “self”) if the direct parameter is an application class. Otherwise, the message is sent to the application object with the direct parameter's value as a normal parameter.

Attributes

type
See Commons Attributes.
description
See Commons Attributes.
optional
Indicates whether the parameter is optional or required. The value may be “yes” (optional) or “no” (required, the default)

Documentation

When an element needs more exposition than a simple description attribute can provide, use a documentation element. A documentation element may contain any number of html elements, which contain text that will be displayed at that point in the dictionary. The text may contain HTML markup tags, but in order to keep the XML processor from interpreting them as XML, they must be escaped using either entities or a CDATA section, for example:

<property name="link" type="text">
 <documentation>
  <html>
   For answers to commonly asked questions about &lt;i&gt;do shell script&lt;/i&gt;,
   see <![CDATA[<a href="http://developer.apple.com/">TN2065</a>.]]>
  </html>
 </documentation>
</property>

Bear in mind that an sdef is intended to be a reference, not a tutorial. If you want to include any lengthy material, consider using a link to an external resource.

Documentation element can occurs in dictionary, suite, and in the following terminology elements: enumeration, enumerator, record-type, value-type, class, class-extension, property, command, event and parameter.


Element

An element defines a class of objects contained in another object and represents a to-many relationship. For each of its defined elements, an object may reference zero or more items of that type. For example, a “rich text” object can have any number of “character” elements, including none.

Attributes

type
See Commons Attributes. Should be a valid class name.
description
See Commons Attributes.
hidden
See Commons Attributes.
access
The allowed access for the element class: Read-only ('r'), Write-only ('w') or Read & Write ('rw').
Default is Read & Write.
accessors
Accessors is not attributes but elements. Accessors define which access forms an element supports. There are six forms:
  • - index: numeric index (window 1).
  • - name: named element (window "Bob").
  • - id: unique id (file id 8727). Ids are often numeric, but don't have to be.
  • - range: a range of elements (records 4 through 12).
  • - relative: relative to another object (word before paragraph 2).
  • - test: objects satisfying a test (shapes whose color is blue).

Accessor elements are currently only useful for aetes. Cocoa Scripting ignores them and figures out supported forms based on the element's properties.

Implementation

cocoa → key
An optional KVC key to be used by Cocoa scripting to access the element.

Enumeration

An enumeration element is a list of symbolic constants (enumerators). For example, the type of the “saving” parameter for “close” is the enumeration “yes/no/ask”.

Attributes

name
See Commons Attributes.
id
See Commons Attributes.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.
inline
Controls how many enumerators are displayed in-line. By default (with no attribute), all enumerators are displayed in-line. For example:
sdef:
<enumeration name="save options">
    <enumerator name="yes"/>
    <enumerator name="no"/>
    <enumerator name="ask"/>
</enumeration>
<parameter name="saving" type="save options"/>
display:
saving yes/no/ask
By specifying a number, that number of enumerators will be listed in-line, with a link to the complete definition. To show only the enumeration name, use inline="0". For example:
  • inline="2": saving yes/no/more…
  • inline="0": saving save options
This attribute only affects the display, it has no semantic meaning.

Implementation

cocoa → name
A name used internally by Cocoa Scripting.

Enumerator

A symbolic constant.

Attributes

name
See Commons Attributes.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.

Implementation

cocoa → name
A name used internally by Cocoa Scripting.
cocoa → *-value
The value of the enumerator constants (Leopard and above). See Cocoa for details.

Event

See Command.


Parameter

A named value included with a verb. Parameter names are often prepositions: “with”, “by”, etc.

Attributes

name
See Commons Attributes.
code
See Commons Attributes.
type
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.
optional
Indicates whether the parameter is optional or required. The value may be “yes” (optional) or “no” (required, the default).

Implementation

cocoa → key
A dictionary key to identify the entry in the “command” argument dictionary.

Property

A property is a unique data member of an object (aka field, instance variable, to-one relation). Properties always have a name, and there is always exactly one of them with a given name in an object. For example, the “name” of a “document” is a property.

Attributes

name
See Commons Attributes.
code
See Commons Attributes.
type
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.
access
The allowed access for the property: Read-only ('r'), Write-only ('w') or Read & Write ('rw').
Default is Read & Write.
in-properties
For frameworks that provide automatic support for a “properties” property, indicates whether or not this property should be included. The value may be “yes” (the default) or “no”.

Implementation

cocoa → key
An optional KVC key to be used by Cocoa scripting to access the element.

Record Type

A record-type element defines a simple structure, as opposed to a class. (In C terms, a “POD” or “Plain Old Data” type.) Points, rectangles, and print settings are all record-types.

Warning: scriptSuite and scriptTerminology files do not support record-type elements. You must use an sdef file directly.

Attributes

name
See Commons Attributes.
id
See Commons Attributes.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.

Responds to

Defines a verb that a class responds to. Cocoa Scripting only requires these in order to define a custom method for handling a verb (see Cocoa). They are otherwise purely for documentation.

Attributes

command
The name or id of the verb. (This attribute used to be called name, see History.)
hidden
See Commons Attributes.

Implementation

cocoa → method
Name of the cocoa method that should be invoked when command operates on an instance of the enclosing class.

Result

The type of value generated when a verb is executed. If there is no result, omit this element. result is a special case of parameter, it has only type and description attributes and may not be hidden or optional.

Attributes

type
See Commons Attributes.
description
See Commons Attributes.

Suite

A suite is a collection of related scriptability information and terms. Suites are purely an organizational aid to the user. They have no impact on scripts. There is no technical limit on how many items a suite can contain, but 10 to 15 items is considered a comfortable size

Attributes

name
The suite's name to be shown in the dictionary. This is not a term that may appear in scripts.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.

Implementation

cocoa → name
A name used internally by Cocoa Scripting.

Synonym

Defines an alternate term or code for the main element.

At least one of name or code is required. Depending on which attributes are present, the element will have different effects:

Name only
Use these to define an alternate term that may be used at compile time. It will decompile as the main term. For example, AppleScript uses “app” as a name-only synonym for “application”.
Cocoa scriptTerminology files do not support these, generate an aete resource for your application as well.
Code only
Use these when migrating from one code to another. (Typically, this happens when correcting an older version of the dictionary which used a non-standard code.) Compiled scripts that use the synonym code will decompile using the main term. Code-only synonyms are implicitly hidden. Because of how Cocoa scriptSuite files work, they must contain a cocoa element with a method or key attribute in order to generate a correct scriptSuite file.
Name and Code
Use these to define an alternate term that is preserved across compilation. Effectively, this is a separate term that happens to act the same as the main one. As with code-only synonyms, they must contain a cocoa element to generate a correct scriptSuite file.

Sdef synonym elements have nothing to do with "Synonyms" sections in Cocoa's suite definition files. Those are a trick to allow two different classes in the dictionary to share the same implementation class, this is necessary because suite definition files use the implementation class name as a key. If you have two classes that happen to share the same implementation, declare them separately, and point their implementation elements at the same class. sdp(1) will do the right thing and generate a "Synonyms" section for you.

Synonym element can occurs in the following terminology elements: enumerator, record-type, value-type, class, class-extension, property, command and event.

Warning: Cocoa Scripting does not currently support synonym elements. See Bugs.

Attributes

name
See above.
code
See above.
hidden
See Commons Attributes.

Type

Any element that has a type attribute may instead have one or more type elements. (Using both in the same element is an error.) Using more than one type element indicates that any of the types are allowed.
Using the list attribute indicates a list of the specified type.
Using type elements inside type elements, such as to express “list of list of integer”, is not currently supported.

Type element can occurs in the following elements: contents, element, property, direct-parameter, parameter and result.

Attributes

type
See Commons Attributes.
list
Indicates that the full type is a list of the type specified by the type attribute. May be “yes” or “no” (the default).

Examples

tabs (list of integer):
<property name="tabs">
    <type type="integer" list="yes"/>
</property>
frequency (number or text):
<property name="frequency">
    <type type="number"/>
    <type type="text"/>
 </property>

Value Type

A value-type element defines a simple type. A value-type has no properties and no elements accessible by your scripting. It is useful for defining new basic types, such as an image.

Attributes

name
See Commons Attributes.
id
See Commons Attributes.
code
See Commons Attributes.
description
See Commons Attributes.
hidden
See Commons Attributes.

Implementation

cocoa elements for values should declare the backing Cocoa class (typically NSData) using the class attribute, and may also declare the qualifier name using the name attribute, but this is only used inside the scriptSuite file. For example, an “image” type might be declared like this:

<value-type name="color" code="cRGB">
    <cocoa class="NSColor" />
</value-type>
cocoa → class
The backing Cocoa class.
cocoa → name
The qualifier name (scriptSuite file only).

Xref

Xref is a cross-reference. These are purely for documentation purposes. Use one to refer to another suite child that is somehow related. For example, “open” might have a cross-reference to “close”. The cross-referenced element does not need to be of the same type as the original. A class may refer to a command, for example.

Xref element can occurs in suite children (i.e., enumeration, record-type, value-type, class, class-extension, command and event).

Warning: xref is only available in Leopard and above. See History for details.

Attributes

target
The name or id of the referenced item.
hidden
See Commons Attributes.

Cocoa

Holds implementation information for Cocoa Scripting. Use the appropriate attribute for the containing element to describe the relevant bit of Cocoa implementation.

sdp (and “Cocoa Scripting”) will generate a default implementation name by capitalizing each word of the element's name except the first, and then removing the spaces. There are two special cases: classes also capitalize the first word, and elements start with the plural of the specified element type. For example, a property with the name “current resolution” would use the method “currentResolution”, a class with the name “refresh rate” would use the class “RefreshRate”.

This default name becomes the “class” for classes, the “key” for properties, elements and parameters, and the "name" for suites, verbs, enumerations, and enumerators. In Cocoa, verbs are implemented by a class, which Cocoa refers to in scriptSuite files as the CommandClass, the default is always NSScriptCommand. An explicit cocoa element is only necessary if you want to override these defaults.

Cocoa element can occurs in suite, synonym and in the following terminology elements: enumeration, enumerator, record-type, value-type, class, class-extension, contents, element, property, responds-to, command, event, parameter.

Warning: The above is correct for sdp(1) , but not for Cocoa Scripting. See Bugs.

Attributes

class
Specifies an Objective-C class name for class, and a command class name for command and event elements.
key
Specifies a string key for an NSDictionary of command parameters, or a key to be used by Cocoa scripting to access a property or element through key-value coding.
method
Specifies an Objective-C method name. Used to specify responds-to methods.
name
A name used internally by Cocoa Scripting (use for suites, command and event key names, enumerations, and enumerators).
boolean-value, string-value, integer-value
A value for an enumerators. For boolean-value, the value may be YES or NO, for string-value, any text, and for integer-value, any integer. You may use at most one of these three attributes in a given cocoa element. The default value is the numeric value of the enumerator’s code attribute.

Commons Attributes

name
For terminology elements, the scripting term for the element. Names must be one or more C identifiers (i.e., [A-Za-z_][A-Za-z0-9_]*) separated by a space. (Other elements have name attributes too, but for different purposes and with different content rules.)
code
The four-character code (eight-character for verbs) for the element. AppleScript and the Apple Event Manager use these codes to handle dispatching.
“Character” is something of a misnomer, a four-character code is really four bytes of data expressed as a string of four characters in the Mac OS Roman encoding.
A code may also be expressed as hexadecimal data with a leading “0x”. For example, “ABCD” and “0x41424344” are equivalent. This is useful when one of the bytes is not in the printable ASCII range of 0x20 to 0x7E, such as the code “0x00000001”.
type
The type of an element, property, or parameter. The value must be one of the primitive types “any”, “text”, “integer”, “real”, “number”, “boolean”, “specifier”, “location specifier”, “record”, “date”, “file”, “point”, “rectangle”, or “type”, or the name of a class, enumeration, record-type or value-type defined elsewhere in the Scripting Definition. To specify a complex type such as “list of integer” or “number or text”, use a type element.
Usage of type attributes changed significantly in Mac OS X 10.4. See History for details.
description
A short description of the element.
hidden
If an element is marked hidden, it is not shown in the dictionary, though it is still implemented. This is useful for obsolete or not-ready-for-prime-time scripting features. Cocoa scriptTerminology files do not support hidden terms, for best results, build an 'aete' into your application as well.
The value may be “yes” or “no” (the default).
id
A unique identifier for the element. Use one when you want to refer to one of a set of identically named elements in a responds-to or xref element.

History

Changes in Mac OS X 10.5 (Leopard):
• Added xref elements.
• html elements (children of documentation elements) are now declared to contain text, not XHTML elements. For example:

before: <html><b>Important</b><html>

after: <html><![CDATA[<b>Important</b>]]><html>

Both forms work in 10.4 and 10.5, but the former is now deprecated.
• The “name” attribute of responds-to elements is now called “command”, and may be an id or a name.
• Added *-value attribute of cocoa element for enumerator.
Changes in Mac OS X 10.4 (Tiger):
“collector” elements such as classes, types, and properties no longer exist. Their former children should be moved to their immediate ancestor element.
In general, children may be freely mixed now. For example, placing a command element next to a class element is perfectly acceptable.
• Some primitive types changed their names: “string” is now “text”, “object” is now “specifier”, and “location” is now “location specifier”.
• Complex types such as “list of integer” or “number or text” are now expressed using type elements, not complex strings. See the type documentation for complete details.
• Boolean attributes, that is, optional and hidden, now accept “yes” and “no” as values (formerly the attribute name, e.g. ‘hidden="hidden"’).
• The “not-in-properties” attribute is now named “in-properties”. Its possible values are “yes” (the default) and “no”.
Cocoa elements of property and element elements now use a “key” attribute (formerly “method”).
• The default Cocoa key for element elements is now the type’s plural (formerly its name).
• Added inline attribute of enumeration element.

Bugs

Cocoa Scripting in Tiger and above supports direct use of sdefs, but does a few things incorrectly: