Structure of a Scripting Definition File
A scripting definition file provides a statically stored representation of a set of scriptability terms and the classes, constants, and other information used to support an application's scriptability. Here is another look at the organization of the main XML structures used in the sdef format. All valid sdef files follow this structure, differing primarily in the contents of the application-specific suite elements.
Note: The sdef information in this chapter is provided to demonstrate the general construction of sdefs for scriptable Cocoa applications. It is not meant to be an exhaustive description of the sdef format.
In this section:
Code Constants Used in Scriptability Information
Features Common to Many Scripting Definition File Elements
High-level XML Elements
Code Constants Used in Scriptability Information
Four-character codes (or Apple event codes, or simply codes), are used throughout AppleScript to identify various kinds of information. 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. For example, 'docu' is the code that specifies the document class. The codes defined by Apple and the header files in which they are defined are described in “Apple Event Constants” in Building an Apple Event in Apple Events Programming Guide. They are also documented in Apple Event Manager Reference and AppleScript Terminology and Apple Event Codes Reference.
You use codes in your sdef file to identify scriptable commands, classes, properties, elements, and other items your application supports. When choosing a code, use an existing code from one of the Apple headers for a standard object—for example, use 'capp' for an application object. If you need to refer to the value in your code, you can use the corresponding Apple constant cApplication, but in the sdef you simply use the string literal ('capp'). For new codes you define, you can define a corresponding constant, if necessary.
Important: If you use a term (or a code) that is defined in AppleScript's built-in terminology or in the Standard suite, you must match it with the code (or the term) defined for it.
Apple reserves all values that consist entirely of lower-case letters and spaces. You can generally avoid conflicts with Apple-defined codes by including at least one upper-case letter when choosing your own codes.
You should always use a given code with the same term, and vice versa. While it is possible to use a term-code pair for different items (for example, to have a property with the same name as a class), this won't work for all elements, and you may want to avoid such reuse. Your codes do not have to be unique with respect to those used in other applications; in fact, as noted above, it is recommended that you use Apple-defined values for standard items.
Features Common to Many Scripting Definition File Elements
Except for the dictionary element (described below), most XML elements in an sdef have a name, a code (or pair of codes), and a description. They may also include documentation and implementation information. XML elements with the cocoa tag (described in “Cocoa Elements”) contain a particular kind of implementation information for Cocoa scripting. Some elements can be marked as hidden, meaning they won’t be displayed when the dictionary is viewed in Script Editor or Xcode, although they will be implemented. Elements can also include synonyms, which define an alternate term or code for the main element.
An XML element in an sdef may refer to any other element in the sdef, regardless of whether they are defined in the same suite element. For example, the word class defined in the Text suite can be referred to in any other XML elements in any other suites in the same sdef file.
High-level XML Elements
All sdef files used to supply Cocoa scriptability information contain the high-level XML elements described in the following sections.
XML Version and Document Type Definition
The first two lines of an sdef file, shown in the following listing, specify the XML version and DTD (document type definition) file for the sdef format. You don't change these lines.
Listing 4-1 Version and document type in an sdef file
<?xml version="1.0" encoding="UTF-8"?> |
<!DOCTYPE dictionary SYSTEM "file://localhost/System/Library/DTDs/sdef.dtd"> |
Dictionary Element
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.
The following listing shows the format for a dictionary element.
Listing 4-2 A dictionary element from an sdef file
<dictionary title="Sketch Terminology"> |
<!-- |
Contains one or more suite XML elements. |
--> |
</dictionary> |
Suite Elements
A suite is a collection of related scriptability information. For example, Cocoa's Standard suite contains default commands, enumerations, and other information, along with Cocoa scriptability information used to implement support for the standard AppleScript commands. Cocoa also implements a Text suite.
Your application supplies its own scriptability information in one or more suite XML elements. For example, if your application provides scripting support for graphics-related features and database-related features, you can provide separate graphics and database suites.
For most applications, the sdef should also include a suite element for the Standard suite and possibly the Text suite as well. You can copy these suites from Sketch's sdef file, then delete the XML definitions for commands, classes, and other items not supported by your application so they won't be displayed in your dictionary. For example, if your application does not support printing, you should delete the elements for the print command and the print settings record-type. Otherwise, users will see those terms when they view your application terminology and will expect the application to support them.
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. For example, in Mac OS X v10.5, an sdef for Cocoa’s Standard suite is provided in the file CocoaStandard.sdef in the location /System/Library/ScriptingDefinitions, and you can use an xinclude statement to include that file into your application’s sdef file.
A suite element contains one or more of the following elements: class, command, enumeration, record-type, and value-type. These elements are described in “Add Information to the Scripting Definition File.”
The following listing (from Sketch's sdef file) shows the XML format for a suite element.
Listing 4-3 A suite element for the Sketch suite
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 |