AppleScript Tutorial 7 - Specifying an Object

2000.10.25 

 

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

Description

 

Scripts need to refer to objects in applications in order to affect them. To correctly specify an object, you need to describe the layers of properties and elements that contain it.

AppleScript
Tutorial

 

Browse the index of this AppleScript tutorial series. You should complete the previous tutorials before starting this one.

     

Objectives
This tutorial answers these questions:
    1. What’s the difference between a property and an element?
    2. How do I specify a particular object?

Element vs Property
So far, we’ve seen that an object can have elements and properties. The concepts of element and property are similar and can be confusing, so remember these differences:

    1. In the application’s dictionary, an object’s properties are listed under the “Properties” heading, while elements are listed under “Elements”.
    2. The class of an element is the same as its name, but the class of a property is specified in the dictionary. For instance, a “drawing area” has “graphic object” elements, so the class of those graphic objects is “graphic object”. Graphic object has the property “pen color”, which is specified in the dictionary as being the class “RGB Color”.
    3. Each property of an object must have one (and only one) value at a time. For example, the pen color of a graphic object can be blue or green, but cannot be blue and green, or no color at all. The pen color must have some value (even black or white). By contrast, a container may contain any number of elements. For example, a drawing area can contain several graphic objects or none at all.
    4. Because a container can contain multiple elements, your script must refer to a specific element in the container. You can refer to the element by name, number (for example, “graphic object 3 in drawing area”) or with any other acceptable reference form. However, since each property of an object can only have one value, you don’t include a specific number or name.
Here is a summary of these differences (Figure 1) and an example of how an element and property are described in the dictionary (Figure 2).

           
    Element Property  
  Where is it listed in the dictionary? Under the heading “Elements” Under the heading “Properties”  
  What is its class? Same as its name Specified by the dictionary  
  How many can there be at once? zero, one or more one only  
  Reference form by name, by numeric index etc None needed
(since there is only one)
 
           
 

Figure 1: Difference between Elements and Properties

 



     
 

 

 
     
 

Figure 2: Field Element and Visible Property of Record

 



To write a script that affects an object, you must know whether the item you want to change (often called the target) is an element or property. This will tell you:

    1. Where to find it in the application’s dictionary.
    2. The class of the element (same as the name of the element) or property (specified in the dictionary).
    3. If there is one (and only one) property value, or any number of elements.
    4. If a reference form (eg a number or name) must be specified.

Remember this simple rule: “A property must have one and only one value”.

Exercise 1: Current Record – Element or Property?
A scripter (that’s you now) will often want to get or change the information in a current database record. But is the “current record” an element in the database or a property of the database? Using the simple “one and only” rule, it is clear that a database can have only one current record. (Several records can be selected or visible, but only one record at a time can be active. That is the current record.) Let’s verify this conclusion.

    1. Open the AppleWorks dictionary in the script editor.
    2. Select the “database layer” class (in the left panel, in the “AppleWorks Database Suite”). (For AppleWorks 5 selected the “database” class”.)
    3. Look for “current record” in the description (the right panel). It should be listed under “properties”, as in Figure 3. So “current record” is listed as a property, confirming our conclusion. We would expect a database to always have a single “current record” value.

           
           
           
       

      Figure 3: Current Record is a Property of a Database

       



Specifying an Object
Since properties and elements can have their own properties and elements, the complete specification of an object includes several layers. The process of identifying each layer is fundamental to understanding how to write a script. Perhaps most of the “newbie” questions on forums discussing AppleScript would be answered by a better understanding of this process.
The ultimate container of any object is its application, such as AppleWorks or the Finder. You need to write all references to application objects within a “tell application” block, such as shown in Figure 5. Tell statements will be explained in greater detail later.

Exercise 2: Specifying a Field
Consider the database shown in Figure 4. If you are familiar with AppleWorks databases, you can easily create this document, but that is not necessary for this exercise. Let’s examine the dictionary to understand the object model of this document, and specifically the location of the text “Hope St”. The purpose of this exercise is to completing the script and understand the object within it, not to actually run the script.

     
 

 

 
     
 

Figure 4: Value of Field in Database of Document

 



    1. Create a new script in the script editor.
    2. In this case, the application is AppleWorks. Enter the script shown in Figure 5.

           
        tell application "AppleWorks 6"

      end tell
       
           
       

      Figure 5: Script to Set the Pen Width of a Graphic Object

       



    3. Within application AppleWorks, the outer object in Figure 4 is the document “Street Number and Name”. Is this an element or a property? Since there can be more than one document and each needs to be referred to by number or (in this case) name, document is an element in the application. Open the AppleWorks dictionary (in the script editor) and select the “application” class, as shown in Figure 6.

           
       

       

       
           
       

      Figure 6: Application and Document Class

       



    4. In the description (right pane), you should see the elements and properties of the application (see Figure 7). Locate the “document” element.

           
        Class application: An application program
      Plural form:
         applications
      Elements:
         document by numeric index, by name, as a range of elements, satisfying a test
         window by numeric index, by name, as a range of elements, satisfying a test
      Properties:
         frontmost boolean [r/o] -- Is this the frontmost application?
         name international text [r/o] -- the name
         selection text range/cell range/graphic object/graphic group/record range/field range -- the selection visible to the user
         version version [r/o] -- the version of the application
       
           
       

      Figure 7: Some Elements and Properties of Document

       



    5. The dictionary (Figure 7) says that document may be specified “by name”. So modify the script as shown in Figure 8. The name is case sensitive.

           
        tell application "AppleWorks 6"
         document "Street number and name"
      end tell
       
           
       

      Figure 8: Specifying Document Element in Application

       



    6. Since “document” is an element, its class is also “document”. So look in the AppleWorks dictionary list of terms (see Figure 6) for the class “document” and select it. The description of the document class should appear, as shown in Figure 9.

           
        Class document: an open document
      Plural form:
         documents
      Elements:
         window by numeric index, by name, as a range of elements, satisfying a test
      Properties:
         text body text [r/o] -- the document’s text (if text document)
         drawing area drawing layer [r/o] -- the document’s drawing area
         painting painting layer [r/o] -- the document’s painting (if painting document)
         spreadsheet spreadsheet layer [r/o] -- the document’s spreadsheet (if spreadsheet document)
         database database layer [r/o] -- the document’s database (if database document)
         preferences document preferences -- document preferences
       
           
       

      Figure 9: Some Elements and Properties of Document

       



    7. Within the document (in Figure 4), you can see (in no particular order) fields, words, a database, records and text. But which of these is a property or element of document, so we know the next layer for our script? See if you can find any of these in the dictionary’s description of “document”. You should conclude that the “database” property is the next choice.
    8. Since “database” is a property, there is only one database per document, so you don’t need to use a name or number reference form (eg “database 1”). You just need to write “database of document...”. Modify the script as shown in Figure 10.

           
        tell application "AppleWorks 6"
         database of document "Street number and name"
      end tell
       
           
       

      Figure 10: Specifying Database Property of Document

       



    9. The database of a document is a property, so the dictionary specifies its class. Figure 9 lists database as the class “database layer”. So, locate and select the class “database layer” in the list of dictionary terms. It is listed in the AppleWorks Database Suite, as shown in Figure 3. Examine the properties and elements of the class “database layer”.
    10. We need to specify the second record in the database, so the obvious choice is the element “record”. As an element, we need to specify the record “by numeric index”, so modify your script as shown in Figure 11. (Note that we could use “of” instead of “in”, but these tutorials use “in” for elements and “of” for properties to clarify the difference.)

           
        tell application "AppleWorks 6"
         record 2 in database of document "Street number and name"
      end tell
       
           
       

      Figure 11: Specifying Record Element in Database

       



    11. Since “record” is an element, its class is also “record”. Select the class “record” in the list of terms, immediately below the previously selected “database layer” class. Examine the description, as shown in Figure 12.

           
        Class record: a database record
      Plural form:
         records
      Elements:
         field by name, by numeric index
      Properties:
         visible boolean [r/o] -- is the record visible?
         index integer [r/o] -- the record number
         id integer [r/o] -- the record id number (unique within a database)
         creation date date [r/o] -- the date/time the record was created
         modification date date [r/o] -- the date/time the record was last modified
         object specifier reference [r/o] -- specifier designating the object
       
           
       

      Figure 12: Elements and Properties of Record

       



    12. We need to specify is the desired field. Figure 12 shows that we can refer to a field “by name”, so modify your script to match Figure 13.

           
        tell application "AppleWorks 6"
         field "street" in record 2 in database of document "Street number and name"
      end tell
       
           
       

      Figure 13: Specifying Field Element in Record

       



    13. Select “field” in the list of terms (the next one down). One of its properties is “value”. Complete the script as shown in Figure 14.

           
        tell application "AppleWorks 6"
         value of field "street" in record 2 in database of document "Street number and name"
      end tell
       
           
       

      Figure 14: Specifying Value Property of Field

       



Supplementary Exercises
Try these supplementary tasks:
    1. Create the “Street number and name” database document (with exactly to same name and lower/upper case) used in Exercise 2. Run the final script. The script editor should display the result “Hope St” in its result window. (If you are using AppleWorks 5, you need to change the middle line to “street in record 2 in database of document "Street number and name"” for it to actually work.)
    2. Create a word processing document and type a sentence. By examining the dictionary, build a script to specify word 3.
    3. Create a drawing document containing a text frame, containing some words. Build a script to refer to word 2 in the text frame.

Conclusion
Knowing how to step through the object model in the dictionary is crucial for you to describe objects in your scripts. Next we will look at some tools that can simplify the process.

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