Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 6 - Resolving and Creating Object Specifier Records / Descriptor Records Used in Object Specifier Records

Key Data

The nature of the information provided by the key data depends both on the specified key form and on the descriptor type of the descriptor record for the key data. Table 6-1 summarizes these relationships for the standard key forms.

Standard descriptor types used with keyAEKeyData

Key form	Descriptor type	Data
formPropertyID	typeType	Property ID for an element's property
formName	typeChar or other text type	Element's name
formUniqueID	Any appropriate type	A value that uniquely identifies an object within its container or across an application
formAbsolutePosition	typeLongInteger	Offset from beginning (positive) or end (negative) of container
	typeAbsoluteOrdinal	kAEFirst kAEMiddle kAELast kAEAny kAEAll
formRelativePosition	typeEnumerated	kAENext kAEPrevious
formTest	typeCompDescriptor	(see Table 6-2 on page 6-19)
	typeLogicalDescriptor	(see Table 6-3 on page 6-22)
formRange	typeRangeDescriptor	(see Table 6-4 on page 6-26)
formWhose	typeWhoseDescriptor	(see Table 6-5 on page 6-50)

Most applications that resolve object specifier records need to support only the key forms formPropertyID, formName, formUniqueID, formAbsolutePosition, formRelativePosition, and formRange explicitly. You do not need to support these key forms for all object classes; for example, words usually do not have names, so most applications should return errAEEventNotHandled if they receive a request for a word by name.

If your application provides an object-counting function and an object-comparison function in addition to the appropriate object accessor functions, the Apple Event Manager can handle formTest automatically.

The Apple Event Manager uses the key form formWhose internally to optimize resolution of object specifier records that specify formTest. Applications that translate tests into their own query languages need to support formWhose explicitly. "Handling Whose Tests," which begins on page 6-47, describes formWhose in detail.

You can define custom key forms and the format for corresponding data for use by your own application if necessary. If you think you need to do this, check with the Apple Event Registrar first to find out whether existing key forms or others still under development can be adapted to the needs of your application.

One simple kind of key form involves identifying an object on the basis of a specified property. For example, the corresponding data for key form formUniqueID (defined in the Apple Event Registry: Standard Suites) always consists of a unique ID for the requested object. This ID is stored as a property identified by the constant pID. The four-character code that corresponds to both formUniqueID and pID is 'ID '.

If you discover that you do need to define a custom key form based on a property, use the same four-character code for both the key form and the associated property.

The rest of this section describes how the key data for the other key forms shown in Table 6-1 identifies Apple event objects.

Key Data for a Property ID

The key data for formPropertyID is specified by a descriptor record of descriptor type typeType. The Apple Event Registry: Standard Suites defines constants for the standard property IDs.

An object specifier record for a property specifies cProperty as the object class ID, an object specifier record for the object that contains the property as the container, formPropertyID as the key form, and a constant such as pFont as the key data. For example, if you were sending a Set Data event to change the font of a word to Palatino\xC6, you could specify the data for the object specifier record in the direct parameter as follows:

Keyword	Descriptor type	Data
keyAEDesiredClass	typeType	cProperty
keyAEContainer	typeObjectSpecifier	Object specifier record for word to which property belongs
keyAEKeyForm	typeEnumerated	formPropertyID
keyAEKeyData	typeType	pFont

In this example, the Set Data Apple event parameter identified by the keyword keyAETheData would specify Palatino as the value to which to set the specified property. The reply Apple event for a subsequent Get Data event that included an object specifier record for the same property would return Palatino in the parameter identified by the keyword keyAEResult.

Key Data for an Object's Name

The key data for formName is specified by a descriptor record whose data consists of text, with a descriptor type such as typeChar or typeIntlText.

Figure 6-2 on page 6-9 includes two object specifier records that specify formName.