Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 3 - Introduction to Apple Events / Working With Object Specifier Records

Data Structures Within an Object Specifier Record

The organization of the data for an object specifier record is nearly identical to that of the data for an AE record. An object specifier record is a structure of data type AEDesc whose data handle usually refers to four keyword-specified descriptor records describing one or more Apple event objects. An AE record is a structure of data type AERecord whose data handle refers to one or more Apple event parameters.

The four keyword-specified descriptor records for an object specifier record provide information about the requested Apple event object or objects.

Keyword	Description of data
keyAEDesiredClass	Four-character code indicating the object class ID
keyAEContainer	A description of the container for the requested object, usually in the form of another object specifier record
keyAEKeyForm	Four-character code for the key form, which indicates how to interpret the key data
keyAEKeyData	Key data, used to distinguish the desired Apple event object from other objects of the same object class in the same container

For example, the data for an object specifier record identifying a table named "Summary of Sales" in a document named "Sales Report" consists of four keyword-specified descriptor records that provide the following information:

• the object class ID for a table
• another object specifier record identifying the document "Sales Report" as the container for the table
• a key form constant indicating that the key data contains a name
• key data that consists of the string "Summary of Sales"

The object class ID specifies the Apple event object class to which the object belongs. An Apple event object class is a category for Apple event objects that share specific characteristics (see "Apple Events and Apple Event Objects" on page 3-5). The characteristics of each object class are listed in the Apple Event Registry: Standard Suites. For example, the Core suite defines object classes for documents, paragraphs, words, windows, and floating windows. The first keyword-specified descriptor record in an object specifier record uses a four-character code or a constant to specify the object class ID. The object class for words, for example, can be identified by either the object class ID 'cwor' or the constant cWord.

Note

The object class ID identifies the object class of an Apple event object described in an object specifier record, whereas the event class and event ID identify an Apple event.

The container for an Apple event object is usually another Apple event object. For example, the container for a document might be a window, and the container for characters, delimited items, or a word might be another word, a paragraph, or a document. The container is identified by the second keyword-specified descriptor record in an object specifier record; usually this is another object specifier record. The container can also be specified by a null descriptor record, which indicates a default container or a container already known to the Apple Event Manager.

The descriptor record in an object specifier record that identifies an Apple event object's container can in turn use another object specifier record to identify the container's container, and so on until the Apple event object is fully specified. For example, an object specifier record identifying a paragraph might specify the paragraph's container with another object specifier record that identifies a page. That object specifier record might in turn specify the page's container with another object specifier record identifying a document. The ability to nest one object specifier record within another in this way makes it possible to identify elements such as "the first row in the table named 'Summary of Sales' in the document named 'Sales Report.'"

The key form and key data distinguish the desired Apple event object from other Apple event objects of the same object class. The key form describes the form the key data takes. The third keyword-specified descriptor record in an object specifier record usually specifies the key form with one of seven standard constants:

Key form	Value	Corresponding key data
formPropertyID	'prop'	Property ID for an element's property
formName	'name'	Element's name
formUniqueID	'ID '	A value that uniquely identifies an object within its container or across an application
formAbsolutePosition	'indx'	An integer or other constant indicating the position of one or more elements in relation to the beginning or end of their container
formRelativePosition	'rele'	A constant that specifies the element just before or after the container
formTest	'test'	Descriptor records that specify a test
formRange	'rang'	Descriptor records that specify a group of elements between two other elements

A key form of formPropertyID indicates key data that specifies a property. A property of an Apple event object is a specific characteristic of that object that can be identified by a constant. The properties associated with the object class for documents include the name of the document and a flag indicating whether the document has been modified since the last save. The properties associated with the object class for words include color, font, point size, and style.

Figure 3-13 shows the structure of a typical object specifier record: four keyword-specified descriptor records that specify the class ID, the container, the key form, and the key data. These four keyword-specified descriptor records are the data for a descriptor record (AEDesc) of descriptor type typeObjectSpecifier. Note the similarities between the object specifier record shown in Figure 3-13 and the Apple event record shown in Figure 3-9 on page 3-16. Like an Apple event record or an AE record, an object specifier record consists of a list of keyword-specified descriptor records.

Figure 3-13 shows the structure of a simple object specifier record that specifies the key form formPropertyID, formName, or formAbsolutePosition. For detailed information about the structure of object specifier records that specify the other key forms, see the chapter "Resolving and Creating Object Specifier Records" in this book.

Figure 3-13 Data structures within a simple object specifier record

Figure 3-14 shows the object specifier record for the Get Data event previously illustrated in Figure 3-4 on page 3-10. The object class ID tells the SurfWriter application that the requested data is an element of class cTable. The container for the table is the document "Sales Report." The key form is formName, which tells the server application that the key data identifies the Apple event object by name. The key data is the name of the table.

Figure 3-14 An object specifier record in a Get Data event

To add an object specifier record to an Apple event as one of its parameters, your application must first create the object specifier record. "Creating Object Specifier Records," which begins on page 6-55, describes the Apple Event Manager routines for creating object specifier records.

To respond to Apple events that include object specifier records, your application should use the standard classification system for Apple event objects and provide functions that can locate those objects within your application or its documents. The next section summarizes the classification of Apple event objects as defined in the Apple Event Registry: Standard Suites.