< Previous PageNext Page > Hide TOC

Terminology Fundamentals

The terminology described in this document gives AppleScript Studio applications the ability to work with Cocoa user interface objects in scripts. This chapter provides key information for working with AppleScript Studio’s scripting terminology. It contains the following sections:

• “Version Information”

• “Building AppleScript Studio Applications ”

• “Sources of AppleScript Studio Terminology ”

• “Script Suites, aetes, and Sdefs”

• “How Suite Information Is Organized”

• “Terminology Supplied by the Cocoa Application Framework”

• “Terminology Supplied by AppleScript Studio ”

• “Standard Key Forms”

• “Naming Conventions for Methods and Handlers ”

• “Accessing Properties and Elements”

• “Event Handler Parameters”

• “Connecting Key and Mouse Event Handlers ”

• “Scripting Error Messages”

• “Using the Sample Scripts”

• “Panels Versus Dialogs and Windows”

• “A Word on Unicode Text”

Version Information

To build AppleScript Studio applications, you must install a version of the Mac OS X Developer Tools that includes AppleScript Studio. To run an AppleScript Studio application, the target machine must have the AppleScript Studio runtime required for the application. An AppleScript Studio runtime is available if AppleScriptKit.framework is present in /System/Library/Frameworks.

AppleScript Studio attempts to maintain the following:

• An application created and built with an older version of AppleScript Studio can run with a newer runtime.

• An application created and built with a newer version of AppleScript Studio can run with an older runtime, if it doesn’t use any features introduced after that runtime.

For example, an application built with AppleScript Studio version 1.1 that uses features added in version 1.1 requires the 1.1 runtime. However, a similar application that doesn’t use any features from AppleScript Studio 1.1 can run with the 1.0 runtime. And an application built with AppleScript Studio version 1.0 can run with any runtime, through version 1.4.

Table 1-1 lists AppleScript Studio versions, the development environment they are part of, and the system software the corresponding runtime is installed with.

For an example of how your application can determine whether the required version of AppleScript Studio is present, see the Examples section for the will finish launching event handler.

Starting with the version of Interface Builder released with Mac OS X version 10.2, there is a Nib File Compatibility preference on the General pane of the Interface Builder Preferences window. You should select a nib-file preference that suits your compatibility goals, from the following choices (and restart Interface Builder for the changes to take affect):

• Pre-10.2 format: applications will run with earlier versions of Mac OS X, but will not have access to new features (such as the circular progress indicator or the brushed-metal, textured window appearance)

• 10.2 and later format: provides access to all new features, but is not guaranteed to run in previous versions of Mac OS X

• Both Formats: provides access to new features but will also run in previous versions of Mac OS X (though without the new features)

Building AppleScript Studio Applications

You use Xcode, distributed with the Mac OS X Developer Tools, to create and build AppleScript Studio application projects, using one of the following three templates:

• AppleScript Application: used for applications that don’t need to store data in documents

• AppleScript Document-based Application: used for applications that create and manage multiple documents

• AppleScript Droplet: used for creating droplets—script applications that launch when you drag a file or folder icon in the Finder and “drop” it on the droplet’s icon

You use Interface Builder, also distributed with the Mac OS X Developer Tools, to create application interfaces for AppleScript Studio applications. Interface Builder provides active support for the Apple human interface guidelines, including feedback lines that show when an object is properly placed. Throughout this document, you will find illustrations of the available Cocoa user interface objects and information on where to find them in Interface builder.

You can also find illustrations of windows, menus, controls, and many other user interface elements, as well as guidelines for when to use them and how to position them, in Apple Human Interface Guidelines. Please use these guidelines to help create applications that take full advantage of the Aqua interface. “See Also” describes how to access this document, as well as documentation for Xcode and Interface Builder.

All AppleScript Studio applications are Cocoa applications, built on the Cocoa application framework. As such, they are a mix of Cocoa code and AppleScript scripts, though you can write robust applications that require no additional Cocoa code on your part.

Some Cocoa capabilities are not currently available to AppleScript Studio classes. Where this is true, you have several options:

• You can use the call method command to call methods of Cocoa classes directly.

• You can write your own Cocoa code as part of your application, and access it through the call method command. In fact, your application can access C, C++, Objective-C, Objective-C++, and Java (both directly and through the Mac OS X Java bridge), as demonstrated in the Multi-Language sample application available at <Xcode>/Examples/AppleScript Studio.

• In some cases, the feature may become available in a future version of AppleScript Studio.

Sources of AppleScript Studio Terminology

AppleScript allows you to write scripts that control multiple applications, including many parts of the Mac OS itself. There are a number of tools for writing scripts, including the Script Editor application (distributed with the Mac OS) and various third party products. Most of the power in your scripts comes from the scripting terminology provided by applications and the operating system, not from the relatively small number of terms that are native to AppleScript itself. To take full advantage of the capabilities available, you need to know what terminology you can use in your AppleScript Studio application scripts.

Scripts in AppleScript Studio applications have access to the basic terminology that is available to all scripts, including:

• terminology provided by AppleScript

• terminology from scriptable parts of the Mac OS

• terminology from any available Apple and third party scripting additions (a scripting addition is code, stored in a SystemAdditions folder in any of the System, Library, User, or Network domains, that makes additional commands or coercions available to scripts on the same computer)

• terminology from any available scriptable applications (whether Carbon or Cocoa applications)

An AppleScript Studio application also has access to:

• terminology that is available to it as a Cocoa application (all Cocoa applications that turn on scripting support gain access to a certain default terminology; this terminology is described in more detail in “Script Suites, aetes, and Sdefs”)

• terminology defined by AppleScript Studio itself in the AppleScriptKit framework (a framework is a type of bundle, or directory in the file system, that packages software with the resources the software requires); this terminology makes it possible to script a wide variety of user interface classes from the Cocoa application framework

• terminology from the script suites (described in “Script Suites, aetes, and Sdefs”) of any scriptable frameworks the application uses, and any scriptable bundles it loads

Script Suites, aetes, and Sdefs

The Cocoa framework provides scripting information in the form of script suites, which are available to any application using the framework. Applications can also define additional suites. A script suite consists of at least one suite definition and one suite terminology, contained in external files. A suite definition describes scriptable objects in terms of their attributes, relationships, and supported commands. This information is stored as key-value pairs in a property list. A property list is a structured, textual representation of data, commonly stored in Extensible Markup Language (XML) format.

A suite terminology provides corresponding AppleScript terminology—the English-like words and phrases you can use in a script—for the class and command descriptions in a suite definition. Suite terminologies are also stored as property lists. Frameworks and applications typically place terminology files in a localized resource directory named English.lproj. (English is currently the only supported dialect in AppleScript.)

Carbon applications originally stored their terminology information in a different format—as an 'aete' (Apple event terminology) resource. While this format is still supported, a new scripting definition, called the sdef format, was added in Mac OS X version 10.2, though not fully supported until Mac OS X version 10.4. The scripting definition provides a mechanism for defining scripting terminology that can be used by both Carbon and Cocoa applications.

For more information on how Cocoa applications define scripting terminology in different versions of Mac OS X, see Cocoa Scripting Guide.

How Suite Information Is Organized

Wherever possible, this document provides connecting links between class, command, event, property, element, and constant definitions. For each AppleScript Studio suite, it provides the following information.

• a brief suite overview

• the terminology for each class

  • plural form, parent class, and Cocoa class the class is based on

    Note: Classes that start with “NS” (such as NSButton) are defined in the Cocoa application framework, and include links to Cocoa documentation for the class. Classes that start with “ASK” (such as ASKDataCell) are defined in AppleScript Studio’s own framework, the AppleScriptKit framework, and do not have Cocoa documentation.

  • properties, elements, commands supported, events supported

  • version notes (if new or changed since version 1.0)

• the terminology for each command and event (if any in the suite)

  • abstract, syntax, parameter descriptions, return value description (if any)

  • examples

  • discussion (if any)

  • version notes (if new or changed since version 1.0)

• the terminology for each enumeration (all enumerations, which are available to every suite, are described in “Enumerations” in the Application suite)

  • a description of the enumeration

  • a description of each constant in the enumeration

  • version notes (if new or changed since version 1.0)

Terminology Supplied by the Cocoa Application Framework

AppleScript Studio applications can take advantage of the built-in Cocoa terminology found in two default suites:

• The Standard suite

  • defines basic classes, including application and window (though AppleScript Studio defines its own version of these classes in its Application suite).

  • defines terminology for basic events, including get, set, count, delete, print, quit, and others. In Cocoa applications that activate scripting support, objects can support certain important commands, such as get and set, with little or no special code by the developer. For detailed information, see Cocoa Scripting Guide.

• The Text suite defines classes for working with text, including the character, paragraph, word, and text classes. For more information on working with text, see the Examples section for the text view class.

To examine the terminology in Cocoa’s default suites, use Script Editor or Xcode to open the dictionary for any scriptable Cocoa application, such as the Sketch sample application distributed with the Xcode developer tools. For more information on examining terminologies, see Support for Scriptable Applications in AppleScript Overview.

Terminology Supplied by AppleScript Studio

AppleScript Studio defines its own script suites, which add to the scripting terminology defined by Cocoa. These suites provide additional terminology you can use to script objects based on many classes from the Cocoa application framework. This terminology is defined in several suite definition and suite terminology files in AppleScript Studio’s own framework, the AppleScriptKit framework. Each suite can include class definitions (which include elements and properties), command and event definitions (which have an associated syntax), and enumerations (or predefined constants).

There are several ways to display the terminology for AppleScript Studio:

• Use the File > Open Dictionary menu choice in Xcode or Script Editor to open the dictionary for any AppleScript Studio application. The list of applications for which you can display the dictionary may contain AppleScript Studio applications as well as scriptable Carbon and Cocoa applications. (This command is no longer available in more recent versions of Xcode, but you can still open a dictionary by double-clicking the file.)

• Open an AppleScript Studio project in Xcode (such as a project you have created or any of the sample applications located in <Xcode>/Examples/AppleScript Studio):

  • In projects created with AppleScript Studio version 1.4 (and Xcode 2.0), you will see (in the Resources group) a file named AppleScriptKit.sdef. Double-click that file to display AppleScript Studio terminology.

    Important:  In some cases, the class for an AppleScript Studio term that should be “Unicode text” is shown as “text” with a link to a text class. Opening the dictionary for a built AppleScript Studio application, either in Xcode or in Script Editor, displays the correct class (Unicode text).

  • In projects created with AppleScript Studio version 1.3 (and Xcode 1.5 or earlier), you will see (in the Resources group) a file named AppleScriptKit.asdictionary. Double-click that file to display AppleScript Studio terminology.

    Note: You cannot display an sdef file in Xcode versions prior to 2.0 (except as xml), nor can you display a .asdictionary file in Xcode 2.0 or later. Similarly, you cannot display an sdef file in Script Editor versions prior to 2.1 , nor can you display a .asdictionary file in Script Editor 2.1 or later.

    Important:  To move an AppleScript Studio project from version 1.3 to 1.4, you will have to replace the .asdictionary file with an sdef file, as described in AppleScript Studio 1.4 Release Notes.

Each of the following chapters describes the terminology for one AppleScript Studio script suite. Enumerations (a form of constant) are available to all suites, and are described in “Enumerations” in the Application suite:

• “Application Suite”

• “Container View Suite”

• “Control View Suite”

• “Data View Suite”

• “Document Suite”

• “Drag and Drop Suite”

• “Menu Suite”

• “Panel Suite”

• “Plugin Suite”

• “Text View Suite”

Standard Key Forms

To access a property or element of an object, a script can specify the property or element by any key form it supports. Key forms simply indicate how data should be interpreted. For example, if a property supports the absolute position key form, a script can use a statement like the following:

set myWindow to the third window

Objects in AppleScript Studio applications are based on Cocoa class definitions, and AppleScript Studio’s scripting support allows most classes to conveniently support a broad range of key forms. As a result, most objects you work with in AppleScript Studio applications support the following key forms:

• name

  tell drawer "mydrawer" to open drawer on top edge

• absolute position (numeric index)

  text field 1 of window 1

• relative position (before/after)

  window in front of window 3

• range (as a range of elements)

  name of windows 1 through 3

• satisfying a test

  the first window whose name is "mainwindow"

• unique ID

  set windowID to id of window 1

See also “Accessing Properties and Elements.”

Naming Conventions for Methods and Handlers

The Cocoa application framework follows a naming convention that helps explain when certain methods are called. This convention, which is reflected in the terminology for AppleScript Studio’s event handlers, inserts should, will, and did in method names. Table 1-2 describes the meaning of these terms. Note that to indicate a completed operation, AppleScript Studio uses the past tense, rather than the term did.

So, for example, you can add a should close handler to a window object. When the handler is called, it can determine whether the user has performed some essential task—if not, it can return false and refuse to allow the window to close. A will close handler cannot cancel the close operation, but it can perform any necessary tasks to prepare for closing. Finally, a closed handler can perform any tasks required after closing.

At application startup time, handlers connected to the application object are called in this order:

1. will finish launching

2. awake from nib

   Important:  If you are working with the version of Interface Builder distributed with Mac OS X version 10.2, see “Version Information” for information on setting a Nib File Compatibility preference.

3. launched

4. will become active

5. activated

6. idle

Accessing Properties and Elements

While elements typically have a singular name, such as document, window, and pasteboard for certain elements of the application class, you use the plural form to access these elements in scripts. For example, you could use the following script in Script Editor to get a list of windows from an AppleScript Studio application (and you can use similar terminology within the application, where you won’t need the tell application block):

tell application "MyApp"

    set windowList to windows

end

A class may list properties that you cannot access in a particular application or at a particular time. For example, the application class lists a key window property that identifies the window that is the current target for keystrokes. But if an application has no windows open, it will not have a key window, and attempting to access the key window property will result in a nil value. (For more information on the key window, see the key and main property descriptions for the window class.)

Starting with AppleScript Studio 1.2, you can use the properties property to access the properties of most AppleScript Studio objects. This feature relies on changes present in the version of Cocoa distributed with Mac OS X version 10.2. The following Script Editor script shows how to display the properties of a button in an AppleScript Studio application:

tell application "simple"

    properties of button 1 of window 1

end tell

The results of this script might be something like the following, where missing value indicates a value couldn’t be obtained for a certain property:

{visible:true, content:false, double value:0.0, ignores multiple clicks:false, title:"Button", image:missing value, name:missing value, bordered:true, enabled:true, window:window id 1 of application "TestingControls", allows mixed state:false, float value:0.0, image position:no image, string value:"0", id:2, flipped:true, roll over:false, opaque:false, alternate image:missing value, bounds:{47, 45, 131, 77}, bounds rotation:0.0, tag:0, class:button, alignment:center text alignment, enclosing scroll view:missing value, can draw:true, menu:missing value, target:missing value, bezel style:rounded bezel, alternate title:"", needs display:false, current cell:item id 3 of application "TestingControls", auto resizes:false, key equivalent modifier:0, position:{47, 45}, formatter:missing value, continuous:false, size:{84, 32}, cell:item id 3 of application "TestingControls", state:0, button type:momentary push in button, font:item id 4 of application "TestingControls", sound:missing value, integer value:0, tool tip:missing value, super view:content view of window id 1 of application "TestingControls", key equivalent:"", current editor:missing value, transparent:false, visible rect:{0, 0, 84, 32}, contents:false}

If your application accesses a property that may not have a current value, you should enclose statements that use the property in a try, on error block. For an example of such a block, see the Examples section for the path for command.

Similarly, an object may have zero or more of each kind of element listed for its class. If you attempt to access an element of a type for which an object currently has no instances, you will get back an empty list. You won’t need a try, on error block, but depending on the logic in your script, you may need to verify that the list is not empty.

Event Handler Parameters

In an AppleScript Studio application, you use Interface Builder to connect application objects to event handlers in application scripts. For example, if you connect a clicked handler to a button, when a user clicks the button, the handler is called in your application script.

When you first connect a handler in Interface Builder, it installs a template in your script file. Listing 1-1 shows the template for a clicked handler. The template matches the full syntax for the event handler, which in this case has just one parameter, theObject. Nearly every event handler template includes the theObject parameter (which is almost always a reference to the object for which the handler is called), though some contain additional parameters as well.

Listing 1-1  A new clicked handler

on clicked theObject

    (* Add your script here. *)

end clicked

The syntax table for each event handler shows the complete syntax that is used for constructing a template. Once a template has been inserted into your application script, you are free to change the names of the parameters and to delete (or ignore) any parameters that are marked as optional in the syntax table.

One way to help document your scripts is, where possible, to change the name of the theObject parameter to reflect knowledge of the object it refers to. For example, if a clicked handler is only called in response to a click on a Search button, you might change the event handler declaration to on clicked searchButton. Changing a parameter name has no effect on how the handler operates.

If the handler may be called for one of several objects (say a series of buttons on one pane of a tab view), you can both change the parameter name and add a comment to clarify its usage:

on clicked importButton

    (* This handler handles buttons on the Import pane. *)

    -- Your script statements here

end clicked

Connecting Key and Mouse Event Handlers

AppleScript Studio provides a number of key and mouse event handlers, such as keyboard down, keyboard up, mouse down, mouse up, mouse dragged, and so on. For objects of certain types, particularly for application objects, key and mouse event handlers that you connect may never get called because they are handled by other objects before they get to the application object. If your application really needs to deal with these events, consider connecting them to objects in the user interface that inherit from the control class, such as button, slider, stepper, or text field objects.

Scripting Error Messages

AppleScript Studio applications are Cocoa applications, and when your application gets a script-related error message, that message is generated by Cocoa’s scripting support. The following table lists scripting errors, through Mac OS X version 10.2. The table includes the current error number. (For a brief description of some related AppleScript terminology, see Glossary of AppleScript Terms in Cocoa Scripting Guide.)

These messages may not always provide the detail you’d like for debugging your application, but other options are available. Among the most useful are using Xcode’s debugging support to set breakpoints, examine variables, and single-step through scripts; and using AppleScript Studio’s log command to output values and messages from your running application.

Using the Sample Scripts

This document contains many sample scripts and event handlers, both complete and partial. In some cases, long statements in the samples contain hard carriage returns to make them easier to read. If you cut and paste samples from this document into AppleScript Studio application scripts, or into scripts you use with Script Editor or another script-editing application, you may have to remove the hard carriage returns to compile the sample.

Panels Versus Dialogs and Windows

You’ll have to get used to a bit of naming inconsistency regarding the use of panels, dialogs, and windows. For historical reasons, the Cocoa application framework uses “panel” in many cases where Apple Human Interface Guidelines, the final arbiter on Mac OS interface issues, would call for “dialog” or “window”. The use of “panel” is even embedded in Cocoa class names, such as NSPanel, NSFontPanel, NSOpenPanel, and so on. AppleScript Studio terminology, which is based closely on Cocoa user interface classes, generally adopts similar names, so that it provides the “Panel Suite,” which includes the color-panel, font-panel, open-panel, and related classes.

Given that history, it isn’t possible for this document to be completely consistent when using these terms. However, the following list shows how some usages of “panel” correspond to terms used by the Apple human interface guidelines. See “See Also” for information on where you can obtain Apple Human Interface Guidelines.

• A panel (based on the NSPanel class) is a special kind of window that typically serves an auxiliary function in an application, such as providing status to the user. The Apple human interface guidelines refer to these kinds of windows as “dialogs” or “utility windows.”

• A color-panel (based on the NSColorPanel class) provides a standard user interface for selecting color in an application. The Apple human interface guidelines would call this a “Colors window.”

• A font-panel (based on the NSFontPanel class) displays a list of available fonts, allowing for preview and selection of the text display font. The Apple guidelines call this a “Fonts window.”

• An open-panel (based on the NSOpenPanel class) provides a standard mechanism to query a user for the name of a file to open. The Apple guidelines call this an “Open dialog.”

• A save-panel (based on the NSSavePanel class) allows users to specify the directory and name under which a file is saved. The Apple guidelines call this a “Save dialog.”

A dialog can be displayed as a sheet (attached to a window), in which case it is document modal, and a user can work with other windows in the application before dismissing the sheet. For example, you can use the optional attached to parameter of the display command to display the open-panel dialog as a sheet.

A Word on Unicode Text

When you get text back from AppleScript Studio, it will almost always be supplied as Unicode text. In some cases you may need to convert from Unicode text to plain text. For a discussion and example of how to convert Unicode text to plain text, see the Discussion section for the default entry class.

In some cases, when you supply text to AppleScript Studio, such as for use with the localized string command, you should ensure that you are working with Unicode text. See the Examples section for localized string for information on how to specify UTF-8 format for a file in your application project.

< Previous PageNext Page > Hide TOC