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?
   
   

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 Properties:    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

   
   

   
   

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.

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

   
   

   
   

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

   
   

   
   

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.
   
   

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

   
   

   
   

Conclusion

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.