AppleScript Tutorial 3 - The Dictionary

2004-03-30 

 

http://www.barefeetware.com/applescript/tutorial/03/

Description

 

In this tutorial, you’ll learn where to find an application’s dictionary, which describes all of the terms understood by that application.

AppleScript
Tutorial

 

The index of the AppleScript tutorial series.

Tutorial 2

 

If you have not already completed tutorial 2, go back to see what makes an existing script tick, and customize it to work slightly differently.

Tutorial 4

 

After you’ve finished this tutorial chapter, go on to learn what is an “object” and a “class”.

     


Objectives
This tutorial should answer these questions for you:
    1. If AppleScript language is so “human” why doesn’t any instruction work?
    2. How do I know what commands are understood by an application?
    3. What is an AppleScript dictionary, how do I view it and how is it organized?
    4. What’s the difference between a class, command, property and parameter, and where are they in the dictionary?

Earlier tutorials in this series looked at existing scripts. Now you will start to learn the AppleScript development process so you can create your own scripts from scratch.

Natural Language, but Structured
One of the most attractive aspects of AppleScript, as a programming or scripting language, is its use of natural, almost human language. Although earlier versions of AppleScript included French and other dialects, AppleScript now only offers English like language.

A series of instructions written in AppleScript code is called an AppleScript script. They are commonly referred to as simply “AppleScripts” or scripts. I will also refer to people who write scripts as a scripter.

Here is an example of a fairly English like script that does a complex task. Imagine that you’ve created a word processing document where each topic heading uses the “heading” style. You want to build a table of contents for your report by telling AppleWorks to get every paragraph in the front document whose paragraph style is “heading” and the length is greater than zero. The script would be very close to this English description:

tell application "AppleWorks 6" to get every paragraph in the front document whose paragraph style is "heading" and the length is greater than 0

The script above actually works. It looks very English like.

This readability tends to inspire the budding scripter to launch headlong into writing scripts, which is good. But the down side of AppleScript’s natural language is that new scripters tend to assume that almost anything goes, but quickly become frustrated when few attempts succeed at writing natural language. You might have experienced this frustration yourself. Like any language, human or computer based, AppleScript has a structure that must be obeyed. This tutorial series focusses on explaining the correct structure or syntax of the AppleScript language to save you from guessing.

The Dictionary
You can tell an application what to do, if you use the appropriate verbs, nouns, adjectives and sentence structure. But how do you know what terms an application understands? Fortunately, an integral part of any scriptable application (ie an application that supports AppleScript) is its AppleScript dictionary (to which we’ll often refer to as simply the dictionary). Each application has its own dictionary that lists all the application’s scripting terms, their description and usage.

A human language dictionary (such as English, French or German), lists each noun, adjective, verb and adverb in the language. An application’s AppleScript dictionary lists similar information. It lists each class, property, command and parameter. Figure 1 gives a brief description of each, to be discussed in detail in upcoming lessons.

           
  Term Similar to English Description Examples  
  Class Noun The classification given to a particular type of object. menu, document, character, field, cell.  
  Property Adjective An attribute or quality of a class. color of oval, length of paragraph, name of document  
  Command Verb A command or instruction to do an action. make new document, select menu item, save document, delete record.  
  Parameter Adverb A value or argument that more precisely defines the event’s behavior. make new text with data "hello", save front document using translator "HTML".  
           
 

Figure 1: Terms Defined by an Application’s Dictionary

 



Like a human language dictionary, an application’s dictionary does not explain the grammar or sentence structure. We’ll cover the sentence structures and AppleScript keywords (such as set, tell, if, repeat, whose, it) briefly as we go and in detail in later tutorials.

The dictionary is the single most important source of information you need to write scripts for an application.

Opening a Dictionary in the Script Editor
To display an application’s AppleScript dictionary, you open the application file with a script editor. The most commonly used script editor is Apple’s “Script Editor,” which is included with all Macintosh operating systems from System 7.5 onward. However, you have other options including Script Debugger, Scripter, Smile and FaceSpan.

A copy of Script Editor should already be on your hard disk, in the location: Applications/ AppleScript/ Script Editor. (In Mac OS 9 and earlier, it’s probably in the startup disk, in the location: Applications: Apple Extras: AppleScript: Script Editor). Most of these tutorials assume that you have Apple's Script Editor. Where this tutorial mentions "the script editor" (in lower case), any script editor could be used, though Apple's “Script Editor” (written in title case) is your most probable choice and the one appearing in most of the screen shots here. The other editors are used occasionally in later tutorials to show their particular strengths.

It’s probably a good idea for you to locate your script editor and drag it to your application dock, for easy access throughout this tutorial.

You can open an application’s dictionary in a script editor by either selecting “Open Dictionary” in the script editor’s File menu, or by dragging the application’s icon onto the script editor icon in the Finder. An alias of either application also works.

Exercise 1: Opening AppleWorks’ Dictionary
Let’s open AppleWorks’ AppleScript dictionary.

    1. If you haven’t already, in the Finder, locate the script editor in the location: Applications/ AppleScript/ Script Editor. Click once on Script Editor to select it. Drag the Script Editor icon, so it appears in your Dock. (If you are using Mac OS 9 or earlier, you could instead make an alias of the script editor in a convenient location, such as on the desktop, or in a folder of frequently used programs.)
    2. Locate your AppleWorks application file. Drag it onto your Script Editor icon in the Dock, as shown in Figure 2.

           
           
           
       

      Figure 2: Dragging an Application onto Script Editor, to Show its Dictionary

       



    3. Script Editor should open AppleWorks’ dictionary, as shown in Figure 3. Leave this window open for the next exercise.

           
           
           
       

      Figure 3: The AppleWorks AppleScript Dictionary

       



Suites
In Script Editor, the left pane of an application’s dictionary lists all the terms understood by that application. The terms are grouped in functional suites, usually starting with the “Standard Suite”, then the application’s general suite, followed by any particular functional groupings. For instance, AppleWorks has separate suites for text, database, spreadsheet and graphics. Each suite groups together related features in the application. For example, the terms “recalculate”, “sort”, “cell” and “row” are listed in the “AppleWorks Spreadsheet Suite” since they are particular to spreadsheet operations.

Within each suite, the terms are listed in two subsections: Classes and Commands. You can expand each suite heading and each Classes/Commands heading to show the terms within that grouping. (In older script editors, all suite listings are shown in bold, are already permanently expanded and do not subsection the classes and commands, but list them together, with classes in italics and commands in plain text.) For example, within the “AppleWorks Spreadsheet Suite”, the terms “recalculate” and “sort” are in the Commands subsection, while “cell” and “row” are in the Classes subsection.

Selecting a term in the left pane displays its description in the right pane. The detail depends on whether it’s a class or command. The description of a class may include: the plural form (eg “cells” is the plural of “cell”); a list of elements (eg a range of cells may contain several rows and columns); a list of properties (eg each cell has a formula, format and lock value). The description of a command may include a list of parameters (eg “sort” can specify a reference to the “cell range”, the “orientation” and the “key cell data”), and a result. I will explain these in detail in subsequent tutorial chapters.

Exercise 2: Viewing AppleWorks’ Dictionary
Following on from the previous exercise, let’s look at some classes and commands in AppleWorks’ AppleScript dictionary.

    1. In the left pane , you should see various “suite” headings. Expand the “AppleWorks Spreadsheet Suite”. In this suite, expand the “Classes” and “Commands” sections. Click on the word “cell” (which is in the AppleWorks Spreadsheet Suite, in the Classes section), to select it. The AppleWorks Dictionary window should look like Figure 4a (or Figure 4b if you’re using an old script editor.)

           
       

       

       
           
       

      Figure 4a: Dictionary Showing the Definition of a Class

       



           
       

       

       
           
       

      Figure 4b: Dictionary Showing the Definition of a Class (Old Script Editor)

       



    2. Have a look through the properties of a cell. You should see “formula”, “format”, Lock”, “name” and so on.
    3. In the left pane, still in the “AppleWorks Spreadsheet Suite”, in the “Commands” section, click on the word “sort” to select it. The window should look like Figure 5.

           
       

       

       
           
       

      Figure 5: Dictionary Window Showing the Definition of a Command

       




Supplementary Exercises
Try these supplementary tasks:
    1. Locate the “graphic object” class in the AppleWorks dictionary.
    2. What properties does an graphic object have?
    3. In which suite is the “paragraph” class?

Conclusion
Now we’ve had a look at an application’s AppleScript dictionary. We’ve briefly viewed suites of classes and events and their descriptions, including their properties and parameters. The next few tutorials will examine each of these in detail.

Next...
Go on to Tutorial 4 to learn what is an “object”, what is a “class”, and more detail on how classes are described in the dictionary.

© 1998 - 2004 BareFeetWare
Please email us any queries about this page.