This tutorial shows you:

1. I can format an object manually. How can I write a script to apply the same formatting?
   
2. How can I write a script to affect the selected graphic object or text?
   
3. How do I get the specification of the selected object?
   
4. Can I see a list of current objects and their properties?
   
   

So far, we’ve set properties of various objects. To do so, we’ve had to know the object model and the class of value expected for a particular class. Once you’re familiar with the object model of a particular application, this method becomes second nature. As the beginner, however, you will often find it helpful for AppleScript to provide the information for you.

We use the AppleScript command get to get or evaluate a value from an application. The general syntax is:

get expression

Technically, the word “get” is optional, so a command has the same result with or without it. Since the inclusion of the word get makes the instruction more readable, we’ll use it in these exercises.

The get command simply returns a result to the script editor’s “Result” window. It does not change the application or really do anything other than show you, the scripter, the result value. So you can use a programs GUI tools to manually create and change objects (such as drawing), then get AppleScript to give you information about your creation, to help you write a script to do the same.

Let’s start with properties. To get the property of a particular object, you write a command in the form:

get property of object

Getting a property of a manually created object is especially useful for the less intuitive and more technical classes of values, such as color. Color is made up of a list of three numbers, representing the red, green and blue shades, each between 0 and 65535. We’ll discuss color in detail in a later tutorial.

Exercise 1: Get, Color, Width and Arrow

Let’s examine the values of some AppleWorks properties that are set by using palettes. Each time that a result is displayed, note the property (eg “pen width” and its value (eg 6.0) for use in a subsequent exercise.

1. In AppleWorks, create a new drawing document.
   
2. Draw a line.
   
3. Use the Accents palette (or pop up menus in Appleworks 5), to set the pen color, line width and arrows, similar (though not necessary identical) to Figure 1.
   
   

   	Figure 1: Line with Properties: Pen Color, Line Width and Arrow

   
   
   

4. Open the AppleWorks dictionary and examine the properties of the “graphic object” class. Note the “pen color” and “pen width” properties. (These properties also apply to lines, due to inheritance, which will be explained in another tutorial.) Also examine the “arrow style” property of the “line” class.
   
   
5. In the script editor, create a new script and enter the code shown in Figure 2.
   
   

   	tell application "AppleWorks 6"    get pen width of line 1 in drawing area of front document end tell
   	Figure 2: Script to Get the Pen Width of a Graphic Object

   
   
   

6. Run the script. The script editor should display a “Result” window containing a number (such as 6.0 for the example line in Figure 1). If the Result window is not displayed, select “Show Result” in the “Controls” menu.
   
   
7. In the script, change “pen width” to “pen color” and run the script again. The script editor should display the result as a list of three numbers, in a format like {39321, 0, 26214}.
   
   
8. Change “pen color” to “arrow style” and run the script again. Depending on which way you drew the line and added the arrow, the result should appear as “arrow at start” or “arrow at end”.
   
   

As shown in Figure 2, it can be cumbersome to refer to an object by its full hierarchy, merely for the purpose of getting some information about it. Thankfully, most scriptable applications include the selection property of the application itself, so you can simply select the interesting object and refer to it in a script as “selection”.

A script can also set properties of the selection, rather than an object specified by its hierarchy. As the script writer, you should set properties of the selection only if the script is intended to alter the object selected by the user. Otherwise, it is generally good AppleScript practice to address a specific object rather than making the script first select it and then alter the properties of the selection.

Exercise 2: Properties of Selection

Let’s simply the previous script using the application’s “selection” property.

1. In the AppleWorks dictionary, locate the class “application” (near the top). Locate the application property (in Script Editor’s right panel) called “selection” (see Figure 3).
   
   

   		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
   	Figure 3: Selection Property

   
   
   

2. In AppleWorks, select the line by clicking on it (if it is not already selected).
   
   
3. Change your script to match Figure 4.
   
   

   	tell application "AppleWorks 6"    get pen width of selection end tell
   	Figure 4: Script to Get the Pen Width of the Selection

   
   
   

4. Run the script and confirm that it gives the expected result.
   
   
5. As you did in the previous exercise, change the property to “pen color” and “arrow style”, running the script after each change.
   
   

Exercise 3: Setting Properties to Match Results

So far, you gathered property values from a manually created object. Now lets use those values to automatically format another object the same way.

1. In AppleWorks, draw a second line in the drawing document without reformatting it. Ensure that the new line is selected.
   
   
2. Create a new script (in the script editor), as shown in Figure 5. Use the values that you gathered in the previous exercise to customize the script (eg change the “6.0” to the pen width result given for your line).
   
   

   	tell application "AppleWorks 6"    set pen width of selection to 6.0    set pen color of selection to {39321, 0, 26214}    set arrow style of selection to arrow at start end tell
   	Figure 5: Set Pen Width, Pen Color and Arrow Style

   
   
   

3. Run the script. It should format the new line to have the same pen width, pen color and arrow style as the first line that you manually formatted.
   
   

As previously discussed, the dictionary lays out the structure of elements within containers, which gives you the object model to refer to any specific object. Sometimes, however, it would be convenient for us to select an object and have AppleScript give us the code necessary to refer to it. Fortunately, many applications provide a special property of most objects, called the object specifier. The object specifier gives the exact location of an object within its application’s object model (ie its hierarchy of elements in containers).

So, you can use the object specifier of the selection to effectively write the script code necessary to refer to the selected object. Simply by giving this instruction:

get object specifier of selection

the script editor will write the code in the result window, in a form such as:

element of container of application

The object specifier syntax returned by the above script will accurately refer to the selected object, but has limited usefulness as is for referring other objects. You can copy and paste the syntax into your own script, but you will normally need to alter it for the following reasons:

1. It includes the full hierarchy, including the application itself. You usually remove this trailing “of application...” since your own script already refers to the application in the opening “tell application” line
   
2. There may be several possible ways to refer to an object, but the object specifier result will only provide one of them. For instance, word 3 in a paragraph 4 may instead be written as text 56 thru 62 (we’ll cover “thru” and text ranges later).
   
3. It will refer to an element by name, but you want it to refer to it by index. For instance, it will give document “untitled 2”, but you want to more generally refer to the “front document” or “document 1”, so you can run your script on any document.
   
4. It may omit a level in the object model hierarchy. For instance,
   
5. It uses the term “of” for properties and elements. Remember that the terms “of” and “in” are interchangeable, but this tutorial series uses “of” for properties and “in” for elements.
   
   

Therefore, you usually need to tweak the syntax returned by “object specifier”, but it will give you a good basis, especially for unfamiliar complex structures.

Exercise 4: Object Specifier of a Selected Word

Let’s use the object specifier property to make AppleScript write some script code for us. We’ll confirm that it works for the original situation, but fails in a similar circumstance, and modify it to be more flexible. (AppleWorks 5 does not have an “object specifier” property. If you use that version, follow the AppleWorks 5 bracketed alterations below.)

1. Examine again the dictionary’s listing of the application’s selection property (Figure 3). Note that the selection can be any one of various classes (according to what the user selects). Look up some of these classes (eg text, cell, graphic object) in the list of terms (ie the left panel in Script Editor) and confirm that they each have a property called “object specifier”.
   
   
2. In AppleWorks, create a new word processing document and type the sentence “In the beginning God created the heavens and the earth.”.
   
   
3. Select the word “beginning”.
   
   
4. Create a new script (in the script editor) containing the code shown in Figure 6. (For AppleWorks 5, instead type “get selection” for the second line.)
   
   

   	tell application "AppleWorks 6"    get object specifier of selection end tell
   	Figure 6: Get Object Specifier of Selection of AppleWorks

   
   
   

5. Run the script. The result should be something like:
   
   text 8 thru 16 of text body of document "untitled 2" of application "AppleWorks 6"
   
   
6. Select and copy all the contents of the Result window.
   
   
7. Create a new script, entering the standard “tell... end tell” lines. Start a middle line with the term “get” and paste after that (see Figure 7).
   
   

   	tell application "AppleWorks 6"    get text 8 thru 16 of text body of document "untitled 2" of application "AppleWorks 6" end tell
   	Figure 7: Get Object Specifier of Selection of AppleWorks

   
   
   

8. Run the script. The result should be “beginning”.
   
   
9. Save the word processing document as “Genesis” onto your desktop or somewhere else temporary. Note that the document now has a different name (in the window’s title bar).
   
   
10. Run the script again. It should fail with an error because the document name referred to by the script does not exist. In this situation, our script would be better written to refer to document 1, instead of by name.
    
    
11. Change the script to better match our requirements, as shown in Figure 8.
    
    

    	tell application "AppleWorks 6"    get word 3 in text body of document 1 end tell
    	Figure 8: Get Object Specifier of Selection of AppleWorks

    
    
    

12. Run the script. The result should be “beginning”.
    
    
13. In the script, replace “get” with “set size of”, and append to the end of the line “to 24”, as shown in Figure 9.
    
    

    	tell application "AppleWorks 6"    set size of word 3 in text body of document 1 to 24 end tell
    	Figure 9: Get Object Specifier of Selection of AppleWorks

    
    
    

14. Run the script. The word “beginning” should enlarge to 24 point text.
    
    

All script editors provide a “Record” button that will record most user actions in scriptable applications. Unfortunately, few scriptable applications support the recording feature (ie they are “Recordable”), so the usefulness of the Record feature is limited. For instance, the Finder is recordable, but the control panels and AppleWorks are not. The results of recording are similar to the results of the selection and object specifier.

Some script editors provide other tools to simplify access to real objects in applications. Script Debugger has an object “Explorer” that you can use to examine the current objects in any scriptable application. It shows elements within containers and properties of objects. Unfortunately, however, it does not show elements in properties, so you can’t, for instance, see the graphic objects within an AppleWorks document’s “drawing area” or a particular paragraph within its “text body”.

Exercise 5: Object Explorer

If you have the full or downloaded demo of Script Debugger, try this very brief introduction.

1. Open the AppleWorks dictionary in Script Debugger. One method of doing so is to drag and drop the AppleWorks icon onto Script Debugger’s icon.
   
   
2. Click the “Explorer” tab. Script Debugger will start listing the objects currently in AppleWorks.
   
   
3. Use the expansion triangles to explore the properties and elements of your open AppleWorks documents (see Figure 10).
   
   

   	Figure 10: Script Debugger’s Object Explorer

   
   
   

Try these supplementary tasks:

1. Use other properties of graphic object and line in the script in Figure 2 to examine the bounds, rotation, start point and other attributes of line 1.
   
2. Manually change the properties of the line (eg rotate it) and examine the new value of the associated property (eg rotation).
   
3. Create a drawing document and draw 5 graphic objects. Select one of the objects and use the object specifier script (Figure 6) to get the code required to refer to it.
   
4. Create a drawing document containing a text frame, containing some words. Select word 2 in the text frame and get the object specifier of the selection.
   
5. Enter new values for properties directly into Script Debugger’s Explorer window to change AppleWorks objects.
   
   

When you are learning an application’s object model, using “get”, “selection” and “object specifier” can make AppleScript write much of the code for you.

---