Inside Macintosh: Interapplication Communication /

Chapter 3 - Introduction to Apple Events

Working With Object Specifier Records

Most of the standard Apple events allow the source application to refer, in an Apple event parameter, to Apple event objects within the target application or its documents. The Apple Event Manager allows applications to construct and interpret such references by means of a standard classification system for Apple event objects. This system, described in detail in the Apple Event Registry: Standard Suites, is summarized in "The Classification of Apple Event Objects," which begins on page 3-33. A description in an Apple event parameter that uses this classification system takes the form of an object specifier record.

An object specifier record is a descriptor record of descriptor type typeObjectSpecifier that describes the location of one or more Apple event objects: for example, the table "Summary of Sales" in the document "Sales Report," or the third row in that table, or the last row of the column "Totals." With the aid of application-defined functions, the Apple Event Manager can conduct a step-by-step search according to such instructions in an object specifier record, locating first the document, then the table, then other objects, and so on until the requested object has been identified. Object specifier records can specify many combinations of identifying characteristics that cannot be specified using one of the simple data types.

This section introduces object specifier records and the organization of their data. You need to read this section (a) if you plan to support the Core suite or any of the standard functional-area suites and (b) if you want to make your application scriptable--that is, capable of responding to scripts written in a scripting language.

IMPORTANT

An object specifier record identifies one or more Apple event objects among many; it contains a description of each object, not the object itself. An Apple event object described by an object specifier record exists only in the server application's document or in the server application itself.

A client application cannot retrieve an Apple event object from a server application unless the server application can accurately locate it. Thus, to locate characters of a specific color, a server application must be able to identify a single character's color; to locate a character in a cell, a server application must be able to locate both the table and the cell.

A client application can create object specifier records for use as Apple event parameters. Scripting components can also create object specifier records as Apple event parameters for the Apple events they generate in the course of executing a script. A server application that receives an Apple event containing an object specifier record should resolve the object specifier record--that is, locate the requested Apple event objects.

To respond to core and functional-area Apple events received by your application, you must first define a hierarchy of Apple event objects for your application that you want other applications or scripting languages to be able to describe. The Apple event objects for your application should be based as closely as possible on the standard object classes described by the Apple Event Registry: Standard Suites. After you have decided which of the standard Apple event objects make sense for your application, you can write functions that locate objects on the basis of information in an object specifier record. If you want your application to send specific Apple events to other applications, you must also write functions that can create object specifier records and add them to Apple events. Your application does not need to create object specifier records in order to be scriptable. However, to write functions that can help the Apple Event Manager resolve object specifier records, you need to know how they are constructed.

"Finding Apple Event Objects," which begins on page 3-38, provides an overview of the way the Apple Event Manager works with your application-defined functions to locate the Apple event objects described in an object specifier record. The chapter "Resolving and Creating Object Specifier Records" in this book describes in detail how to support object specifier records as a server or client application.

---

Subtopics

Data Structures Within an Object Specifier Record

The Classification of Apple Event Objects

Finding Apple Event Objects