Object Hierarchy

The object hierarchy determines which objects are related to each other within a particular class of objects. The following table shows 16 object classes (the first column) and their corresponding elements (the second column). Within an object class, elements are grouped together by their valid reference forms (the third column). In other words, from an object in the first column, you can use a reference form in the third column to refer to an element in the second column.

An object that is the element of another object class may appear as its own object class later in the table. In some cases, an object can be an element of its own class; for example, a paragraph object is an element of the paragraph object class. In other cases, an object may appear as an element of an object class that would at first seem too small to contain the specified element; for example, because, technically, a word can be one character long, the word object is an element of the character object class.

Word supports the following reference forms:

• Property
• Index
• Relative
• Name
• Middle/Arbitrary/Every Element
• Range
• Filter

Word does not support the ID reference form. For complete descriptions of these reference forms, refer to your AppleScript documentation.

The following paragraphs suggest some techniques you can use for handling and referencing objects in Word. These techniques will help you get the best performance out of your script applications.

Index through bigger objects

Word does not maintain internal indices to all text objects. To find the AppleScript object word 200, Word must scan through all the words in the document until it finds the two-hundredth word. Scanning through bigger objects is quicker, so scripts that reference larger objects first will execute more rapidly. For example, assuming the 1000th word is also the third word in the fifth paragraph of the third section, the reference word 1000 will execute much more slowly than the reference word 3 of paragraph 5 of section 3, even though each references the same word.

Use the filter reference form sparingly

To support the wide variety of filter reference cases supported by AppleScript, Word uses a set of operating system utilities that perform much of the bookkeeping involved with complex filter expressions. With this implementation, the operating system repeatedly asks for individual objects from Word during the processing of a filter reference. Then tests are performed on the objects to see if they meet the given filter criteria. This back-and-forth process of getting objects and then performing tests can be slow.

If you must use the filter reference form, use it in conjunction with a index reference qualifier (for example, the first word where character 1 is "w") to speed up the script. Avoid the qualifier "every"; it forces Word to filter all the text within a parent object.

Use bookmarks

As noted previously, using the index reference form can be slow. But even more problematic, as documents change, the indices of specific words or paragraphs will also change. If the document being accessed by a script is subject to change, the script cannot rely on fixed indices to locate particular text objects. The filter reference form can be used to find particular objects, but this method can be slow.

The best way to maintain persistent references to text and table objects in Word is to use bookmarks. Bookmarks are names that you can assign to any selected text. Even if the document is changed, the bookmark still refers to the original selection. For example, if a bookmark named "xref" is created for the third word of a document, and then a new word is inserted at the beginning of the document, the bookmark "xref" will refer to the fourth word.

Bookmarks are exposed to AppleScript through the Text Flow object, which is only accessible by name from a document. For example, the following reference refers to the text associated with the bookmark "xref":

set selection to text flow "xref"

Any valid text event can be performed on a Text Flow object. Text Flow objects can also reference Range objects if the bookmark for the range is contained in a Word table.