Inside Macintosh: Interapplication Communication /

Chapter 8 - Apple Event Terminology Resources

Defining Terminology for Use by the AppleScript Component

You should keep two principles in mind when you are defining the Apple event object hierarchy and corresponding terminology for your application:

• Avoid defining new Apple events unless absolutely necessary. For example, instead of defining a custom Find event, use the Get Data event with whose tests. (For more information about whose tests, see the chapter "Resolving and Creating Object Specifier Records" in this book.)
• Use existing object classes, or if you must define your own, define them in a general fashion.

This section describes how the terms you specify in your application's 'aete' resource are used in AppleScript statements that control your application. Before you implement the Apple event object hierarchy for your application, try out your proposed user terminology in AppleScript statements that use the standard syntax forms described here. This will help you discover some of the advantages and disadvantages of both your proposed object hierarchy and the human-language terminology you are planning to use.

Some AppleScript commands, such as if, repeat, and tell, are executed directly by the AppleScript component and do not correspond to Apple events. Other commands trigger Apple events when the AppleScript component evaluates them.

AppleScript command	Corresponding Apple event
open	Open
close	Close
save	Save
move	Move
delete	Delete
set	Set Data

The AppleScript component interprets the terms used in scripts according to rules defined by the AppleScript language. For example, the open command must be followed by an argument that specifies the objects to open, and the save command must be followed by an argument that specifies the objects to save. The AppleScript component uses the information in an application's 'aete' resource to map the human-language terms used in these arguments to specific Apple event keywords and codes, so that it can construct object specifier records that describe the objects on which the Open and Save events act.

In general, the syntax for AppleScript commands that trigger Apple events follows this pattern:

event name expression parameter name expression . . . parameter name expression

The underlined terms are supplied by the AppleScript component's 'aeut' resource, by the application's 'aete' resource, or by the 'aeut' resource available on the current computer. The argument that follows event name corresponds to the direct parameter for the event, if there is one. Each subsequent argument corresponds to an additional parameter.

An argument that corresponds to a direct parameter can use any of the syntax forms shown in Table 8-1. These forms correspond to the key forms that can be used to identify the key data in an object specifier record.

Table 8-1 Syntax for AppleScript arguments that correspond to direct parameters

Syntax of argument	AppleScript example	Key form
property name	the font	formPropertyID
class name expression	table "Fred" table 4	formName formAbsolutePosition
class name before | after expression	word after table 2	formRelativePosition
class name expression thru expression	words 1 thru 30	formRange
every class name whose expression	every word whose\xA8 font = "Palatino"	formWhose
expression of expression	first row of\xA8 table "Fred"	Any key form; sets container for elements or properties

If the Apple event object hierarchy for your application requires you to specify terms in your 'aete' resource that are not included in the 'aeut' resource, make sure those terms read naturally when they appear in AppleScript statements that use the syntax shown in Table 8-1. Any of the underlined terms in the table may be supplied by your application's 'aete' resource.

For example, in the AppleScript statement

copy name to expression

the argument name corresponds to a direct parameter that can use any of the syntax variations shown in Table 8-1. The word to and the expression that follows it correspond to an additional parameter that describes the location to which to copy the objects described by the direct parameter.

Many AppleScript commands, including the copy command, take additional arguments that correspond to insertion location descriptor records, which are descriptor records of type typeInsertionLoc defined as part of the Core suite. An insertion location descriptor record is a coerced AE record that consists of two keyword-specified descriptor records with the following keywords:

Keyword	Description
keyAEObject	An object specifier record that identifies a single container
keyAEPosition	A constant that specifies where to put the Apple event object described in an Apple event's direct parameter in relation to the container specified in the descriptor record with the keyword keyAEObject

You can specify one of these constants for the data in a descriptor record identified by the keyword keyAEPosition:

Constant	Meaning
kAEBefore	Before the container
kAEAfter	After the container
kAEBeginning	In the container and before all other elements of the same class as the object being inserted
kAEEnd	In the container and after all other objects of the same class as the object being inserted
kAEReplace	Replace the container

The syntax that corresponds to an insertion descriptor record can take any of the forms shown in Table 8-2.

Table 8-2 Syntax for AppleScript arguments that correspond to insertion location descriptor records

Syntax of argument	AppleScript example	keyAEPosition constant
before | after expression	before Figure 1	kAEBefore | kAEAfter
beginning of | end of expression	end of window 2	kAEBeginning | kAEEnd
expression	Figure 1	kAEReplace

For example, in the AppleScript statement

copy Chart 1 of document "Sales Chart" to before Figure 1

the term copy corresponds to a Clone event, and Chart 1 of document "Sales Chart" corresponds to the direct parameter for the Clone event. The term to is the human-language name specified by the 'aeut' resource for the additional parameter identified by the keyword kAEInsertHere, which always consists of an insertion location descriptor record. The term before corresponds to the constant kAEBefore in the descriptor record identified by the keyword keyAEPosition, and Figure 1 corresponds to the object specifier record identified by the keyword keyAEObject.

The AppleScript component handles statements that describe the replacement of one object with another differently from statements that specify an insertion location before, after, at the beginning of, or at the end of an object.

For example, in the statement

copy Chart 1 of document "Sales Chart" to Figure 1

the term to is the human-language name for the additional parameter identified by the keyword kAEInsertHere. When to is followed immediately by an element expression like Figure 1, the Clone Apple event sent by the AppleScript component includes an additional parameter that consists of an object specifier record for Figure 1. When your application requests the parameter as an insertion location descriptor record, a system coercion handler installed by the AppleScript component converts the object specifier record to an insertion location descriptor record that specifies kAEReplace in the descriptor record identified by the keyword keyAEPosition.

If your application defines any extensions to the standard Apple events or object classes that require the use of insertion locations, use standard insertion location descriptor records to specify them, and make sure your Apple event object hierarchy and the corresponding human terminology in your 'aete' resource allow the AppleScript component to translate insertion location descriptor records into meaningful statements in an AppleScript dialect.

Unlike most other AppleScript commands, the copy command causes the AppleScript component to send different Apple events under different circumstances. In the examples just discussed, the copy command corresponds to a Clone event. However, after evaluating the statements

tell application "SurfWriter"
      copy table "Summary of Sales" of document\xA8
         "Sales Report" to Totals
end tell

the AppleScript component sends a Get Data event and sets the variable Sales91 to the value of the returned data; and the statements

tell application "SurfCharter"
      copy Totals to Chart 1 of document "Sales Chart"
end tell

cause the AppleScript component to send a Set Data event that sets the data in the specified chart to the value of the variable Totals.

All scriptable applications should support the Get Data, Set Data, and Clone events for all Apple event objects that a user might want to manipulate from a script with the copy command. Scriptable applications should also support the other core events and any appropriate functional-area events.

If you find it difficult to come up with meaningful AppleScript statements based on your proposed implementation of Apple events, you may need to rethink your implementation.