This tutorial provides answers to:

1. How do I make a new document, graphic object, record or other element?
   
2. How do I specify the initial properties of a new object?
   
3. Where can I place a new object?
   
   

Most of the events in a script deal with the objects in an application. If an object does not already exist, then the script must create it using the “make” event. The “make” event creates a new object, such as a new document, folder, graphic object or database record.

Exercise 1 - Display Make in the Dictionary

1. Open the AppleWorks dictionary.
   
2. Select the “make” event, in the Standard Suite.
   
3. Examine the description, as shown in Figure 1.
   
   

   	Figure 1: Description of the Make Event

   
   

   
   

The dictionary’s “make” parameters indicate that to make a new element, you must specify the “type class” of the new object and its “location reference”. These parameters are identified by the parameter labels “new” and “at” respectively.

The “type class” tells the make event exactly what it is that you want to make. It must be one of the classes listed in the dictionary (displayed in italics in the left panel). For example, you could “make new rectangle” or “make new record” since both “rectangle” and “record” are classes in the AppleWorks dictionary. The application will, however, prohibit you from making some classes of objects, such as “menu” or “cell”, which you can’t create via the normal graphical user interface.

The “location reference” identifies the position in the container of the new object. The position is usually “front” or “end”, with “front” assumed if the position is omitted. (We will discuss these “reference forms” more in a later tutorial.) The location reference specifies the layer relative to the other objects within the same container, not the x-y coordinates.

Exercise 2: Make New Document and Graphic Objects

Let’s make a new drawing document and some new graphic objects in the drawing area of the document. You will start by confirming that “document” is an element in the class “application” and that “graphic object” is an element in the class “drawing area”. Follow these steps:

1. In the AppleWorks dictionary, select the “application” class.
   
2. Note that “document” is an element in “application” (see Figure 2). This means that we can make a new document within the application AppleWorks.
   

   		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 ...
   	Figure 2: “Document” is an Element in “Application”

   
   
   

3. Now we need to know in what container we can make graphic objects. We know that they somehow exist within a document, so select the “document” class (in the left pane, immediately after “application”). Note that the only element is “window” so “graphic objects” cannot be stored directly within the “document” class. Locate the “drawing area” property of the “document” class (in the right pane – see Figure 3). Note that the class of the drawing area property is “drawing layer” (or “drawing area” in AppleWorks 5).
   

   		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 ...        preferences document preferences -- document preferences        modified boolean [r/o] -- has the document been modified since the last save?        margins rectangle -- the document’s margins        name international text [r/o] -- the name of the document        index integer [r/o] -- the document number        document kind drawing document/text document/spreadsheet document/database document/painting document/presentation document [r/o] -- the document kind ...
   	Figure 3: Some Properties of “Document”

   
   
   

4. Select the “drawing layer” class under the “AppleWorks Graphics Suite” heading (in the left pane – see Figure 4). (For AppleWorks 5, instead select the “drawing area” class.) Confirm that “graphic object” is an element in “drawing layer”. Therefore, we can make a new graphic object in the drawing area of a document.
   

   		Class drawing layer: Container for graphics and supporting information Plural form:        drawing layers Elements:        graphic object by numeric index, by name        arc by numeric index, by name        line by numeric index, by name ...
   	Figure 4: “Drawing Area” Property of “Document”

   
   

5. Create a new script editor document (ie a new “script”).
   
6. Enter the script from Figure 5. (If you are using AppleWorks 5, you need to avoid a bug by adding the text “with properties {bounds:{72,72,144,144}}” to the end of each “make new oval” and “make new arc” line.)
   

   	tell application "AppleWorks 6"        make new document at front        make new oval at front in drawing area of front document        make new oval at front in drawing area of front document        make new arc at front in drawing area of front document end tell
   	Figure 5: Make With Required Parameters

   
   

   
   

7. Check the syntax (ie click the “Check Syntax” button or hit the “Enter” key) and correct any errors. The script editor will format your script.
   
8. Run the script.
   
9. If the window’s title bar is hidden behind AppleWorks’ button bar, you can either move the button bar or the window to see it properly.
   
10. Don’t close any documents yet. You will modify the script in a moment.
    
    

If you omit a required parameter (such as the “make” event’s “at” parameter) from your script, AppleWorks will display a “some parameter was missing” error message when you compile or run the script. In contrast, some parameters are optional so the script will work even if you do not provide them.

Optional parameters and their labels appear in the dictionary enclosed in square brackets. For example, as you can see in Figure 1, the “with data” and “with properties” parameters of “make” are optional. We will discuss the “with properties” parameter shortly, but leave “with data” for a later tutorial.

If you don’t provide the value of an optional parameter, the application (eg AppleWorks) uses a default value. For example, in the Figure 5, the first instruction “make new document at front” creates a new document. Since the instruction does not specify a document kind, AppleWorks assigned its default value of “text document” (or “WP” in AppleWorks 5) and creates a word processing document.

Note in Figure 1 that the “with properties” parameter has the class “record”. (You will learn more about the “record” class later). For our current purpose, the record will be of the form:

{property:value}

You can also specify more than one property value, by separating with commas:

{property1:value1, property2:value2, ...}

This means that when you make a new object, you can specify some of its properties. In general, you can use any property listed by the dictionary for the class of object that you are making.

Of course, another approach is to make the object without specifying any properties, then “set” some properties in subsequent instructions. The “set” method can be easier to read and is often more stable, but the “make with properties” method can be slightly faster and, most importantly, can assign many properties that are otherwise read only (ie those that the dictionary lists as “[r/o]”).

Exercise 3: Document Kind of New Document

In our script, let’s change the new document to be a drawing document instead of the default behavior of being a word processing document.

1. In AppleWorks, note that the document created by the script is a word processor document. We want to change the script to instead make a drawing document. Close the old word processing document without saving.
   
2. In the dictionary (in the script editor), select the “document” class (in the left pane – see Figure 3). Examine the “document kind” property (appearing in the right pane). The allowed values are listed, separated by slashes “/”. Note that this property is read only (“[r/o]”) so we could not use “set” to assign a value after making a document. The properties record we need for “make” is “{document kind:drawing document}”.
   
3. In your script, type the “with properties” parameter at the end of the second line of the script so it reads (for AppleWorks 5, change “drawing document” to “DR”):
   make new document at front with properties {document kind:drawing document}
   
   
4. Re-run the script. Confirm that the script creates a drawing document.
   
   

Exercise 4: Bounds of Graphic Objects

As it stands, our script creates three graphic objects (two ovals and an arc) on top of each other, since they all use the same default properties. Let’s change the properties of those objects so we can see them more clearly. We will assign the “bounds” property using make’s “with properties” parameter and set some other properties using “set” commands.

Objects that are classed as “oval” or “arc” are also classed as “graphic object”, so you can use properties of both classes. We’ll cover this concept of “inheritance” in detail later.

1. Examine the graphic objects in the drawing document that resulted from running your script. Drag them apart to verify that there are in fact two ovals and an arc on top of each other.
   
2. Close the drawing document without saving.
   
3. We need to determine the property that assigns the size and x-y coordinates of the graphic objects. Select the “graphic object” class, under the “AppleWorks Graphic Suite” heading (in the left pane of the script editor’s dictionary – see Figure 6).
   

   		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 ...
   	Figure 6: “Drawing Area” Property of “Document”

   
   

4. Note that the “bounds” property is listed as having the class “bounding rectangle”, which defines the position and size of the graphic object. Tutorial 6 introduced this bounding rectangle as a list of four numbers, measured in pixels from the top left corner of the drawing area, in the format “{left, top, right, bottom}”.
   
5. Change your script to include the “with properties” parameters shown in Figure 7. (Coincidentally, AppleWorks 5 has a bug that prevents it making new graphic objects unless the “with properties” parameter is specified, and only the “bounds” property works here.)
   

   	tell application "AppleWorks 6"        make new document at front with properties {document kind:drawing document}        make new oval at front in drawing area of front document with properties {bounds:{50, 50, 100, 100}}        make new oval at front in drawing area of front document with properties {bounds:{150, 50, 200, 100}}        make new arc at front in drawing area of front document with properties {bounds:{50, 150, 200, 200}} end tell
   	Figure 7: Make with Bounds Property

   
   

   
   

6. Compile the script and fix any errors. Then run the script.
   
7. Switch to AppleWorks. It should display a new document like Figure 8.
   

   	Figure 8: Graphic Objects with Bounds

   
   

   
   

8. Close the new AppleWorks document, but keep the script window open.
   
9. Let’s use the set event to improve the face in Figure 8. Add the three “set” lines to your script so it matches Figure 9. Check the dictionary’s entry for each property of the “arc” class used in the script.
   

   	tell application "AppleWorks 6"        make new document at front with properties {document kind:drawing document}        make new oval at front in drawing area of front document with properties {bounds:{50, 50, 100, 100}}        make new oval at front in drawing area of front document with properties {bounds:{150, 50, 200, 100}}        make new arc at front in drawing area of front document with properties {bounds:{50, 150, 200, 200}}        set start angle of front arc in drawing area of front document to 90        set arc angle of front arc in drawing area of front document to 180 end tell
   	Figure 9: Setting Other Properties

   
   

   
   

10. Run the script. It should create a new document containing a more recognizable face.
    
11. When you are done, you can close the AppleWorks documents without saving.
    
    

Try these supplementary tasks:

1. Write a script to make a new spreadsheet document.
   
2. Write a script to make a new word processing document and to make a new character at the front in its text body.
   
   

Make is an often crucial application event because it creates new objects. At the instant of creation, it can also establish properties, some of which cannot otherwise be set.

The lines in the script in Figure 9 are quite long. Stay tuned to find out how to reduce redundancy and improve readability in your scripts.

---