AppleScript Tutorial 6 - Properties




Most classes has various properties associated with them. So you can script changes to an object by setting one of its properties to a different value.



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


This tutorial should answer these questions:
    1. How do I know the class of a property?
    2. How do I know what properties I can change?
    3. What values can I give to a property?
    4. How do I change objects?

Property of a Class
Each class has various properties associated with it. A property is an attribute that must have only one value at a time. You can change most properties to affect objects. Changing properties is the most commonly scripted instruction for applications.

The class of an object determines what properties it has. Every object of a given class has the same properties and always has a value for each property.

The dictionary lists the properties of each class. Each property is listed with its name, the class of the property and a description, in this form:

property name property class -- description of property

Exercise 1: Properties of Cell, Text and Graphic Object
Let’s examine AppleWorks’ dictionary to see what properties are available for cells, text and graphic objects.

    1. Open AppleWorks’ dictionary in the script editor.
    2. Select the “cell” class and examine the properties. Among others, you should see that a cell has a formula, color (for its text) and fill color property (see Figure 1).




      Figure 1: Some Properties of Cell


    3. In a similar fashion, select the “text” class and examine the properties. Among other properties, you should see that text has font, size and color.
    4. Select the “graphic object” class and examine the properties. The properties of the graphic object class include pen width, pen color and fill color. See Figure 2.

        Class graphic object: two-dimensional objects
      Plural form:
         graphic objects
         bounds bounding rectangle -- the smallest rectangle that contains the entire graphic object
         fill color RGB color -- the fill color
         fill pattern integer -- the fill pattern
         fill gradient integer -- the fill gradient
         fill texture integer -- the fill texture
         pen color RGB color -- the pen color
         pen pattern integer -- the pen pattern
         pen width real -- the pen width
         rotation integer -- the rotation of this object in degrees from horizontal
         definition rectangle bounding rectangle -- the rectangle used to define the object; this is usually the same as the bounds except when the object is rotated
         text wrap no wrap/regular wrap/irregular wrap -- the way in which text should wrap around an object
         wrap gutter small integer -- the number of pixels to allow between an object and the text wrapping around it
         lock read only/read write -- indicates whether or not the object may be moved, deleted, or modified
         name string [r/o] -- the name of the graphic object
         index integer [r/o] -- the index of the graphic object within its container
         object specifier reference [r/o] -- specifier designating the object
         properties record -- the object's properties (record)

      Figure 2: Properties of Graphic Object


Referring to a Property
In a script, you refer to a property of an object in the form:

property of object

For example:

pen color of graphic object 3
database of front document
rotation of graphic object 2
lock of cell "A1"

AppleScript allows two other ways to refer to a property of an object. These are:

property in object
object's property

So the following statements are all equivalent:

pen width of graphic object 2
pen width in graphic object 2
graphic object 2's pen width

For clarity, however, this tutorial series only uses uses “of” for properties, leaving “in” for elements, and seldom uses the possessive “'s” suffix.

Setting a Property
In AppleScript, you usually change an object by setting its properties. For instance, you change the pen color of a graphic object by setting the pen color property of the graphic object to a new value. You use the “set” event to change a property’s value. “Set” follows this syntax:

set property of object to value

Exercise 2: Setting the Pen Width Property
Now you will write a script, using the property syntax, to change the pen width of the front graphic object in the front document. For now, only concern yourself with the script line that starts with “set”.

    1. Create a new AppleWorks drawing document.
    2. Draw a graphic object, such as a line, rectangle or oval.
    3. In the script editor, create a new script document (eg in the File menu, select “New Script”).
    4. Type the five lines from Figure 3 into the script text panel of the script window. (Just type the text as shown. The indenting and bold formatting is automatic, as you will see in the next step.)

        tell application "AppleWorks 6"
         tell drawing area of front document
           set pen width of front graphic object to 5.0
         end tell
      end tell

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


    5. Press the Enter key (not the Return key) or click on the Check Syntax button. The script editor will check the syntax of your script and format the text as shown in Figure 3. If it displays any error messages, correct your script and try again.
    6. Run the script (eg by clicking the Run button or by selecting the “Run” menu item). If the script editor displays an error dialog, check that you followed the above steps exactly.
    7. Switch to AppleWorks. The new graphic object should now have a thick (5 pixel wide) pen width, as in Figure 4.



      Figure 4: Before and After Changing the Pen Width Property of a Graphic Object


Standard Classes of Properties
The class of most properties is something fairly ordinary and universal, such as text, a number or a list of numbers. Because these classes are standard, AppleScript defines them, so they are not listed in an application’s dictionary. Some common classes of properties are listed in Figure 5. We will discuss these standard classes in greater detail in upcoming tutorials.

  Class Description Example Properties of that Class  
  text or string Series of characters with style. formula of cell
text body of document
text body of text frame
  integer Whole number less than 65536. length of text
height of row
index of record
  real Number with essentially any value including negative and decimals. size of character
pen width of graphic object
scale of window
  Boolean True or false. lock of cell
modified of document
visible of record
  list Series of any values. Depicted in {} curly braces and separated by commas. on styles of text style info
export translators of application
(points etc as below)
  point List of {x,y} coordinates. position of window
start point of line
  bounding rectangle List of {left, top, right, bottom} boundary real values defining the edges of an object. bounds of graphic object
bounds of window
  RGB Color List of {red, green, blue} color integer values. pen color of graphic object
fill color of cell
color of character

Figure 5: Some Standard Classes


Exercise 3: Setting Properties of a Graphic Object
Let’s add to your script some more property changes. All these properties are standard classes such as integer, real and RGB color.

    1. Examine the dictionary’s listing of graphic object properties (see Figure 2). What other properties of the graphic object could you change?
    2. In your existing script (Figure 3), insert some extra lines similar to and immediately following the existing “set” instruction, as shown in Figure 6. As you enter each property, place close attention to its description in the dictionary, especially comparing its class (eg “integer”) with the value used in the script (eg “3”).

        tell application "AppleWorks 6"
         tell drawing area of front document
           set pen width of front graphic object to 5.0
           set pen pattern of front graphic object to 3
           set pen color of front graphic object to {30000, 0, 0}
           set fill color of front graphic object to {0, 30000, 10000}
           set fill pattern of front graphic object to 17
           set rotation of front graphic object to 45
           set lock of front graphic object to false
           set bounds of front graphic object to {10, 20, 50, 70}
         end tell
      end tell

      Figure 6: Script to Set Various Properties of a Graphic Object


    3. Check the syntax (eg by press the Enter key or clicking the Check Syntax button).
    4. Run the script. (AppleWorks 5 fails to change many of the properties, such as fill color.)
    5. Switch to AppleWorks. The new graphic object should have changed properties, similar to Figure 7.



      Figure 7: Before and After Changing Properties of a Graphic Object


Class of a Properties Defined by the Application
Some property classes are not part of standard AppleScript or need more precise definition, so are defined by an application’s dictionary. In AppleWorks, for example, the style property of text has the class “text style info”.

The most frequently used properties in AppleWorks are the content layers of a document. Every document has a “drawing area”. In addition, each word processing document has a “text body”, each spreadsheet has a “spreadsheet”, each database document has a “database”, and so on. “Drawing area”, “text body”, “spreadsheet” and “database” are all properties of a document.

Every reference you make to an object in a document will include one of these document properties. For example, to refer to the front graphic object and cell A4 in the document “Analysis”, the script would contain:

front graphic object in drawing area of document "Analysis"
cell "A4" in spreadsheet of document "Analysis"

AppleWorks’ document content layers will be explained more in the “Tell” tutorial.

Exercise 4: Content Layers of Documents
Since the content layers of documents are the most commonly used properties in AppleWorks, let’s examine their dictionary listings.
    1. Open AppleWorks’ dictionary in the script editor.
    2. Select the “document” class.
    3. In the list of properties, locate each of “text body”, “spreadsheet”, “database”, and “drawing area”. Note the class of each property.
    4. For each property in the previous step, cross reference its class. For example, since the “spreadsheet” property is listed as having the class “spreadsheet layer”, select the “spreadsheet layer” class.
    5. Note the elements in each class. For instance, since the spreadsheet property of a document has the class “spreadsheet layer”, which has cell elements, cells are elements in a document’s spreadsheet.

Supplementary Exercises
Try these supplementary tasks:
    1. Delete your original graphic object from the AppleWorks drawing document. Draw a different kind of graphic object (eg a rectangle or text frame containing some text). Run the script (Figure 6) again.
    2. Change the values of the properties in your script to different values.
    3. Try to figure out the numeric value of each pattern in AppleWorks’ palette by changing the integer value and noting which one is matched.
    4. Create a spreadsheet document. Write a script based on Figure 8, adding more set commands to change properties of the cell.

        tell application "AppleWorks 6"
         tell spreadsheet of front document
           set formula of cell "C2" to "hello"
           set color of cell "C2" to {65535,0,0}
         end tell
      end tell

      Figure 8: Script to Change Properties of a Cell


You’ve covered probably the most important concept in scripting. Understanding that you set properties of objects is a fundamental principle in AppleScript. For example, you should not waste time looking for a “change color” command, since you know that you instead need to set the color property.

So, what’s the difference between a property and an element? Stand by.

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