Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 9 - Recording Apple Events / What to Record

Identifying Objects

The way a recordable application identifies objects can involve assumptions about the user's criteria for selecting those objects. In general, such assumptions should be avoided. Follow these guidelines for identifying objects:

• If you aren't absolutely certain of the user's criteria for selecting an object, identify the object by name.
• If the object doesn't have a name, identify it by index.
• Determine the index based on the order in which a user would see the objects when reading a document.
• Identify windows and open documents on which actions are taken as the frontmost window or document.

The rest of this section provides examples of how to apply these guidelines.

Suppose a user is working with an electronic mail application that permits a variety of sorting methods for messages received. If the user is currently looking at messages sorted by date and then deletes the second message in the list, that message should be identified by name rather than by date. Use an object's name in any situation where it is not completely clear which identifying criteria the user had in mind.

Suppose a user has used the application's Find command to locate all messages created on a certain date. In this case it might be appropriate to identify "every message whose creation date . . ." in the corresponding Apple event. However, if the user did not ask for all messages created on that date, you can't be sure whether the user really wanted every message or only a particular one. For instance, perhaps the user couldn't remember the name, but only an approximate date. In this case a recordable application should identify the message by name.

Just as names are more specific and usually more desirable than whose tests, names are usually more specific and more readable than identifiers or indices. However, some objects may not have a name, only some other identifier or an index. Even though an identifier is more specific than an index, a logically defined index of position is more readable and is therefore recommended. For example, if a document contains unnamed illustrations, the user is more likely to identify a figure by index (order from the beginning of the file) than identifier (such as order created).

Suppose a document contains two figures that appear at first glance to be side by side, except that the right one is slightly taller and therefore begins higher on the page than the left one. In cases such as this, your application should determine the index based on the order in which the user would see the objects when reading a document. For Roman script systems, this means reading from left to right and from top to bottom. In the example just described, the leftmost, shorter figure would have a lower figure number than the rightmost, taller one.

When your application needs to refer to a window or a document, it should identify the object with an object specifier record that corresponds to the first, or front, window:

Keyword	Descriptor type	Data
keyDirectObject	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cWindow
keyAEContainer	typeNull	No data
keyAEKeyForm	typeEnumerated	formAbsolutePosition
keyAEKeyData	typeLongInteger	1

This strategy allows users to record scripts that will work on any window, regardless of its name. Similarly, events that act on an open document should identify it as "document 1."

It is usually possible to describe objects in several different ways. If an object has a unique name, use that. For example, instead of an object specifier record that describes "column number 7," use one that describes "the column named 'March'":

Keyword	Descriptor type	Data
keyDirectObject	typeObjectSpecifier	(see indented record)
keyAEDesiredClass	typeType	cColumn
keyAEContainer	typeNull	No data
keyAEKeyForm	typeEnumerated	formName
keyAEKeyData	typeLongInteger	"March"

It may be that such an object could also be described in a more complex manner, such as picture 1 of paragraph 302 of chapter 2. But complex descriptions like this should be used only as a last resort if no simpler name is available.

In general, be as specific as possible when you identify a selection in a recordable event. The user can generalize as necessary by editing the recorded script.