This tutorial provides answers to:

1. What is an event? What is a parameter?
   
2. What commands can I give to an application?
   
3. How can I modify the behavior of an event?
   
4. Which parameters are optional and which are required?
   
5. If there doesn’t appear to be an event to change what I need, how can I script it?
   
   

For AppleScript to “do” anything, it must send an event. An event is also known as a method, verb, message, instruction or action. An event does something to an object. Events let you “set” a pen width, “save” a document, “make” a new oval, “cut” to the clipboard, “recalculate” a spreadsheet, and so on.

In previous tutorials, we’ve covered objects and their properties in detail. To use them, we used the “set” and “get” commands. “Set” sets the value of a property and “get” retrieves it. Typical examples looked like this:

set pen width of front graphic object to 5
get font of character 3

It is important to realize that you facilitate most changes in a script by using “set” to change properties, rather than performing some specialized event. For instance, a drawing application typically has no “rotate” event, since that can be achieved by setting the “rotation” property of a graphic object. “Newbie” scripters often search in vain for some non-existent event, forgetting that they just need to set a property.

“Set” and “get” are AppleScript keywords, which means that they can be used in any script. They are not particular to an application so don’t generally appear in an application’s dictionary. They are formatted in bold by AppleScript, rather than application events, which are plain text.

This tutorial will focus on those events which are in an application’s dictionary, using common examples found in an application’s dictionary to illustrate general concepts.

The simplest events are those that do not require or accept additional information. You simply enter the term on a line by itself in a script and AppleScript will perform that task.

Exercise 1: Cut

“Cut” is an example of an event that has no parameters. The “cut” event cuts the currently selected graphic object or text onto the clipboard. Let’s create a short script that uses “cut”, without requiring any more information. Follow these steps:

1. In AppleWorks, create a new drawing document.
   
2. Draw two rectangles and two ovals.
   
3. Select two of the objects.
   
4. Type the script from Figure 1 into a new script editor document.
   
   

   	tell application "AppleWorks 6"    cut end tell
   	Figure 1: Script to Cut the Selection to the Clipboard

   
   
   

5. Run the script.
   
6. Switch back to AppleWorks. The objects you selected should no longer appear in the document – they were cut to the clipboard. To confirm that they are on the clipboard, select “Paste” from the Edit Menu to paste the objects back into the document.
   
7. Close the AppleWorks and script editor documents without saving.
   
   

Most events accept additional information, called parameters or arguments. A parameter more precisely defines the event’s behavior. For illustration, if you tell someone to “jump”, you can also specify the “how high” parameter. If you tell an application to “save”, you must include the name or number of the document to be saved and may also specify the file in which to save it.

The dictionary tells you how to specify the parameters for an event. In Script Editor, an event is listed in the dictionary’s left pane in plain text. When selected, the event’s detail appears in the right pane. As shown in the example in Figure 2, the first line is the name of the event and a brief description, underlined. The remaining lines describe the parameters for the event. Any optional parameters appear within square brackets “[ ]”. We’ll discuss these components in more detail shortly, except the “result”, which we’ll defer to a later tutorial.

	Figure 2: Components of the Dictionary’s Description of an Event

Exercise 2: Viewing Event Descriptions

Let’s look at the parameters of the “make”, “save” and “close” events as defined in AppleWorks’ AppleScript dictionary. These three are part of the “Standard Suite” so appear in most applications.

1. Open the AppleWorks dictionary.
   
2. In the left pane, click on “make” (listed under the “Standard Suite” heading).
   
3. Hold down the key and click on “save” and “close”. The dictionary window should display all three events, as shown in Figure 3. We’ll discuss the descriptions shortly.
   
   

   		make: Make a new element    make      new type class -- the class of the new element.      at location reference -- the location at which to insert the element      [with data anything] -- the initial data for the element      [with properties record] -- the initial values for the properties of the element    Result: reference -- to the new object(s) save: Save a document    save document -- the document to save      [in alias] -- the file in which to save the document      [as file type type class] -- the type of file in which to save the document (e.g., PICT, TEXT, MW2D)      [using translator international text] -- the name of the translator to use to save the document      [template boolean] -- save the document as template? close: Close a window or a document    close reference -- the object to close      [saving yes/no/ask] -- specifies whether or not changes should be saved before closing      [saving in alias] -- the file in which to save the object      [as file type type class] -- the type of file in which to save the document      [using translator international text] -- the name of the translator to use to save the document
   	Figure 3: Make, Save and Close Events with Parameters

   
   
   

In an event’s description, each line after the heading shows the parameter label in bold, the class of the parameter in plain text and a comment in italics. For instance, in Figure 3 the “save” event lists the parameter label “using translator” (in bold), with the class “international text” (in plain text) and the comment “the name of the translator to use to save the document” (in italics).

Each parameter must be of the specified class that is acceptable to the event. For instance, in Figure 3 the “save” event requires a parameter of class “document”.

Exercise 3: Save Different Classes

Try the following experiments to confirm which classes of objects can be “saved” by the save event.

1. Create a new AppleWorks word processor document. Type at least one character in the document.
   
2. In the script editor, create a new script document. Enter the script from Figure 4.
   
   

   	tell application "AppleWorks 6"    save document 1 end tell
   	Figure 4: Script to Save Document 1

   
   
   

3. Run the script. AppleWorks should display a Save As dialog, which indicates that the script worked. Cancel the dialog. As predicted by the dictionary, AppleWorks can “save” a “document”.
   
4. Now change the script to Figure 5.
   
   

   	tell application "AppleWorks 6"    save menu 1 end tell
   	Figure 5: Script to Save Menu 1 (Fails)

   
   
   

5. Run the script. AppleWorks should display the message “Menu 1 doesn’t understand the save message”. This indicates that AppleWorks knows what a menu is, knows how to save, but cannot save a menu.
   
6. Close the AppleWorks and script editor documents without saving them.
   
   

When the dictionary defines the acceptable class as something specific like “document”, “text”, “menu item” or “graphic object”, you know exactly what is expected. However, when more than one class is acceptable for a particular parameter, the dictionary only shows the non-specific term “reference” (or “location reference”), which gives you no idea of what is allowed.

For example, the save event lists a specific class (“document”) but the close event uses the generic term “reference”. Therefore, you can only save a document, but you can close more than one class of object (such as document and window). This gives you no clue that other classes, such as “graphic object”, “text” and “menu item” are not acceptable as the first parameter of close.

At this point, some classes will probably seem foreign to you, such as “type class”, “record”, “bounding rectangle” and “alias”. Later tutorials will explain these in more detail.

Most events can have several parameters, so each needs to be uniquely identified by the word or phrase preceding it, as one of:

1. The direct parameter directly follows the event.
   
2. All other parameters are preceded by a label, so they are called labeled parameters.
   
   

For instance, “close” and “save” each have a direct parameter (of classes “reference” and “document” respectively – see Figure 3). The “make” event has no direct parameter (ie nothing follows on the same line as the word “make”). However, “make” has four parameters labeled “new”, “at”, “with data” and “with properties”.

Try these supplementary tasks:

1. Examine the other events in the AppleWorks dictionary. For each, identify the direct parameter, labeled parameters and the class of each.
   
   

“Set” is the most commonly used event, since it can set properties of objects. Other events are needed by an application to facilitate actions that can not be accomplished by changing a property. The dictionary provides a lot of detail in the parameters expected by each event.

In the next tutorial we’ll look closely at the make event and its parameters.

---