"HELP!" -- The Beatles
Using Applescript to control your applications is both fun and useful, but finding the information you need to write those scripts can be trying.  Many scripters are mystified by application dictionaries and rely instead on help from other coders or other scripts to "show them the way."  When you need a script to work quickly, waiting for a response from another scripter can seem to take forever.  There is, however, a quicker way to get the help you need - Applescript dictionaries.  Here, for your scripting pleasure, is a tutorial to help you make sense of an application's dictionary, the collected information about what an application will give you access to.

One way of opening a dictionary is to use the Open Dictionary item in the File menu of Script Editor.  When you use this item, you will get a listing of the available applications that have dictionaries.  Choose one and click the Open button or use the Browse button to navigate to an unlisted application.

Another way to open a dictionary, particularly if it is one you use frequently, is to make use of Script Editor's Library window.  It's located in the Window menu below the Result History and Event Log History menu items.  The Library window shows a list of default applications whose dictionaries you can open with a double click or by selecting it and clicking the Open Library toolbar item.  By adding items to the library window that you use frequently you can customize the list so that it helps you get to the information you need quickly.

A View To A Dictionary
One of the thing, I think, that puts people off of using dictionaries in Applescript is that the window is a bit cluttered and confusing.  But once you know what you're looking at, it makes a lot more sense.  You'll notice a couple of divider controls, one at the top is obviously separating the navigation pane from the content.  Less obvious is the second divider since it is usually closed - it's located on the edge of the left side of the content pane.  If you drag it to the right, you'll see that it also shows a navigation pane of a different sort.  If you prefer to use it, you can, but it is limited to showing you only the suite view - more on that in a minute.




As you see in the toolbar of the window below, it contains a typical back/forward control, a  text-size control, a print control, and a search box.  But nestled between the text icons and the print icon is an unfamiliar control simply labelled View.  If you park your mouse pointer over this control you will see the info text describes it as "View by Suites, Containment, or Inheritance."  Below is a discussion of the differences.




View by Suites
Each dictionary can have a number of objects and commands.  In order to simplify all this information, dictionary items are divided into groups of related items.  For example, you have the "Standard Suite," a collection common commands that are supported by most applications.  These often include commands like open, close, quit, print, make, delete, exists and count and object classes like application, document, item, and window.

If the application includes the ability to use text, you may also find the "Text Suite" in the dictionary.  Often it includes classes like word, character, paragraph, attribute run and attachment.  These are sometimes used as base classes so that the application's main suite can use them to create application classes that inherit characteristics from them.  More on inheritance in a bit.

Lastly, you will generally find an suite that is the heart of the application's dictionary.  Here you find commands and classes that are uniquely adapted to the application.  For the Address Book application you will find definitions for person, address, email, phone and commands like add and remove.




View by Containment
This view shows you what objects can contain other objects.  There are no commands shown in the containment view, only object classes.  For example, in the window above we can see that the application contains documents, groups, persons, and windows.  If you followed the "group" class you would find it can contain persons or other groups.  If you follow the person object you will see it holds addresses, email addresses, phone numbers, and other information.

The containment view is helpful when you need to know how to reference an object.  Here we see that you would reference an email address using, "email 1 of person 1 of group 1"; "of the application" is assumed.

You might also notice that in this example, "application" is listed twice in the first pane - the first class is the root application class that contains document and window classes.  The second item is the class representing the current application, which inherits those classes from the other object and adds its own items for groups and persons.




View by Inheritance
Lastly, we have the inheritance view.  If you check the content area of the window above, you'll see the definition of "AIM Handle" objects.  After the class name you see it is a noun ("n") and that the plural ("pl") is "AIM Handles."  This very similar to what you would find in a standard English dictionary.  You also get the derivation of the object, just as a regular dictionary would show you the lexical history of a word, often tracing a word back to the original Latin or Greek version of the word.

In the case of Applescript, you see that "AIM Handle" inherits from "contact info" which in turn is derived from the "item" class, and that this relationship is also shown in the navigation pane above the content area.  Finally, you also get a written description of the class, along with a notation that it can be contained by the "person" class ("people" is the plural of "person") as an element.

The "item" class is the root class in all of Applescript (Cocoa uses something similar called "NSObject").  It is the basis for every other class of objects.  If you look at the "item" class by itself, it contains two properties - "Class" and "Properties."  Since the "contact info" class inherits from item, it too, contains those properties, along with its own properties, "Id," "Label," and "Value."  And the "AIM Handle" class inherits all of the previous classes' properties, but contains none of its own properties (since the "Value" property of the "contact info" class actually holds the handle string).

Look It Up In The Dictionary
Like a language dictionary for English, Spanish, or French contains entries for nouns, verbs, and adjectives, an Applescript dictionary differentiates between different types of entries.  Any entry that is preceded by a round icon with a "C" in it is a command - that means it is a verb and the entry will show a "v" after the command name, followed by the text description of the command.  Below this information is a list of parameters, some of which are optional.  Here's the entry for "make" from the Standard Suite.




Notice that "new type class" has no brackets around it, while the other parameters do.  This means that "new" is not an optional part of the command.  After all, if you're making something you need to tell Applescript what kind of new thing to make.  The other parameters are optional and can be left out if you don't need them.  Notice also that at the end of the entry there is an arrow and the word "reference."  This means that the make command, when successful, returns a reference to the new object that you created.  This is helpful for working with the new object.  A properly formatted "make" statement would be

Applescript:

tell application "Address Book"
   set myNewGroup to make new group with properties {name:"New group"}
end tell

Items in the dictionary that have a square icon with a "C" in it are classes, which means they define objects that can be created or manipulated.  Here's another dictionary entry, this time for the "group" class in the Address Book dictionary.

Here you will see that it has only one property, "name" (besides the ones it inherits from the "entry" and "item" classes).  Under the word "Elements," you can see that it can contain either groups or people and that it, in turn, can be contained by the application, other groups, or people.  So, in a way, you can say that groups are optional in the application, in other groups, or in person entries.  At the same time, other groups or people are optional within the group. 

If this is confusing, remember that a married couple may or may not have children - in Applescript, they would be "elements" of the parents.  Likewise, the parents themselves have parents, so the parents are "elements" of their parents.  In the same fashion, each generation can have differing numbers of children. Generally, elements are created using the "make" command, unless the application defines some other command for making new objects.

Properties, on the other hand, are inherent in the class, meaning that they always exist within every object of that class.  So in the "group" entry, you learn that every group will have a "name" property.  Unlike elements, however, properties do not exist in multiples.  So while a group can have many "person" elements, it can have only one "name."  Likewise, properties can never be deleted, but elements may be.  Nor can you use "make" to create new instances of an object's properties.  Properties are almost always basic Applescript classes like string, number, or list.

Lastly, items that have a square icon with an "E" in it are elements.  Generally speaking, most classes can be elements.  After all, an element is an object, so it must be defined in the dictionary somewhere, unless the element in question is a basic Applescript class.  Elements listed in the "contained by" or "contains" section of a class are usually hyperlinked to the definition of that element's class elsewhere in the dictionary. 

"Elementary, my dear Watson!" -- Sherlock Holmes
I hope that this helps beginning scripters to better understand how Applescript dictionaries are read and used.  It takes using a dictionary for several scripts to get you used to scripting a given application.  But once you know how to read the dictionary, scripting an application becomes much easier.

Some applications don't always conform to their dictionaries.  Apple's own Mail program comes to mind here, as it has been plagued with dictionary inaccuracies and things that don't work since, I think, Panther.  So if a command or class doesn't behave as it should, check with other scripters or here at Macscripter to see if others have a work-around.

That's it for now, go crunch some code!