Moving from Microsoft Office VBA to AppleScript:
MacTech's Guide to Making the Transition

Page Prev and Page Next buttons at bottom of the page.

April, 2007
Page 4

[times integer] : The number of actions to be undone.

→ boolean

The first indented line after the definition shows the command followed by the data type of its direct object (if any: it‘s document in the example above), and then the lower lines, indented another level, specify any parameters (arguments) that the command may have. Parameters in [square brackets] are optional parameters, such as [times] in the example. The parameter is followed by the data type that it takes, or a full enumeration with enumerated values separated by slashes, if the enumeration is not a class itself. (For example, the file path type parameter of get default file path mentioned earlier is

get default file path v : Returns the default folders for items such as documents, templates, and graphics.

get default file path

file path type documents path/pictures path/user templates path/workgroup templates path/user options path/auto recover path/tools path/tutorial path/startup path/program path/graphics filters path/text converters path/proofing tools path/temp file path/current folder path/style gallery path/trash path/office path/type libraries path/border art path : Which path should be returned.

—>Unicode text : The specified default path.       

The final line of the definition, if the —> arrow is present, shows the data type and description (if needed) of the result returned. (Script Debugger uses the word 'Result' rather than an arrow.)

More About Dictionaries

You may have already noticed, if you opened an application dictionary in Script Editor, that the various terms are listed in like-minded Suites. This is something of an archaic, legacy, inheritance from the beginnings of AppleScript, but dictionaries are still put together this way. The groupings into suites can sometimes seem a bit of an anomaly, especially in the Office applications. For example, in Word, everything to do with Ranges (called text range in Word AppleScript) is found in the Text Suite, everything to do with tables in the Table Suite, everything to do with Word Art in the Drawing Suite, and most of the rest in the Microsoft Word Suite.

This seems logical enough, when you know that Text, Table and Drawing Suites are already defined for AppleScript and exist in many applications, although they can each implement particular terms in their own ways. But it also means that since selection object class is in the Microsoft Word Suite while text range is in the Text Suite, very similar commands such as extend (that applies to selection properties) and move end of range (that applies to text object properties and other ranges) are likewise found in the two different Suites rather than close together.

It is quite easy to forget this and to look fruitlessly for a command or class in the Microsoft Word Suite to no avail, forgetting to look in the Text Suite or Table Suite. Fortunately, in the modern Script Editor, you can enter a term such as 'move end' (which you might guess at from recalling the MoveEnd Method of VBA) in the search box, and the dictionary will produce all occurrences of 'move end' – including the one you‘re looking for – wherever it may occur in the dictionary. If you splurge for Script Debugger, you have the added feature that all Classes and Commands can also be seen all listed together alphabetically as well as by Suite, so you can just ignore the whole Suite issue completely if you wish and look up a term directly. (Script Editor allows you to view by Containment – and, supposedly, Inheritance – rather than Suites, but that doesn't help to find a term if you don't know where it occurs in the object model hierarchy.)

You will also see that, within each Suite, Commands and Classes are listed separately, each list alphabetically, with the commands listed above the classes. In Script Editor 2, the lists have no "Commands" and "Classes" headings – they just run on from one to the other – but you will note a difference in the icons used: a light blue circle with a "C" for Commands, and a purple square with a "C" for Classes.

Script Debugger has better organization, where there are separate lists in a column browser for Commands, Classes Enumerations and AppleScript Types. This is somewhat akin to how Objects and Methods can be thought of as separate groups within VBA. (Unlike many programming languages, especially rigorous Object Oriented languages, AppleScript commands do not "belong" to classes in the way that Methods belong to classes in OO languages, although they act only upon such classes as they are restricted to.)

A major difference in how AppleScript application dictionaries are structured compared to VBA Help is that Properties are not separated off into their own subsection, not even for browsing. There are Classes (like VBA Objects) and Commands (like VBA Methods), and that‘s it. (In Script Debugger dictionary presentations, you can also find lists of Enumerations – something like those wdConstants and xlConstants listings in the VBA Object Browser, and AppleScript Types – like integer, string, etc. These are not shown in Script Editor.)

Properties of each class are listed separately for each class, as are its Elements. It often happens, especially in Office applications, derived as they are from the same Object Model as VBA, that properties of the same name occur in several different classes. For example, in Excel, both range and row have a row height property. Many, many classes have a value property. But you won‘t see generic definitions in the Excel dictionary for row height or value, as you might in VBA Help. Instead you‘ll find row height listed under properties in both range and row classes, and value listed under properties in listbox, range, cell and many other classes.

In AppleScript, unlike VBA, there is a distinction between the two different kinds of attributes classes can have: properties and elements. Properties are one-to-one: every instance (object) of a particular class must have one, and only one, instance of each property the class lists in the dictionary. There is a nice advantage to this, which we will see later, in that there is a pre-defined default value for every property if you don‘t bother to specify another value when you create a new object.

Elements are many-to-one: objects may have 0 or more (any number of) elements, which generally have to be made if you are creating a new object. Elements are themselves application objects whose type is specified in the dictionary. (Properties may also be application objects, or may be basic AppleScript types such as Unicode text, or integer or boolean, or may be enumerated values.)

We will see many examples later. One confusing thing about the current Script Editor is that it also lists under elements the classes that contain the defined class (as we saw above in the footnote example, where it lists a whole slew of classes "contained by" footnote) rather than just the classes (types) of elements which the defined class "contains" (none in the case of footnote). This was not true of the old pre-OS 10.2 Script Editor which didn‘t list these at all, and it is not true of Script Debugger which quite properly lists these "contained by" classes under a different where used heading. In my opinion, it‘s a bug to list them under elements as Script Editor does, although very useful to know about them. Just be sure you note the difference between real elements (that the defined class "contains") and these "contained by" classes.