Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 8 - Apple Event Terminology Resources / Reference to Apple Event Terminology Resources

Suite Data for an Apple Event Terminology Resource

Object Class Data

Each item in the array of object classes for a suite includes information about the class and arrays that specify the properties and elements for that class. Figure 8-6 shows the format of the object class data in an 'aeut' or 'aete' resource.

Figure 8-6 Structure of object class data in an 'aeut' or 'aete' resource

The data for each object class consists of the following items:

• The human-language name of the object class. This is a Pascal string that can include any characters, including uppercase and lowercase letters and spaces. When the resource description is compiled, the resource compiler pads the string and aligns the next field on a word boundary.

  If the 'aete' resource specifies the name of an object class as an empty string, the scripting component looks up, in its 'aeut' resource, the class name and other object class data that correspond to the specified class ID. If the 'aete' resource specifies a name other than the name provided by the 'aeut' resource for the same class ID, the scripting component uses the new name with the same object class data from the 'aeut' resource. You should specify an empty string for the name of any standard object class that you list explicitly in an 'aete' resource.

• The four-character class ID for the object class. If the 'aete' resource specifies a standard object class name and a class ID other than the class ID for the equivalent standard object class, the scripting component uses the new class ID with the standard object class data for the specified name. You should specify the standard class ID for any standard object class that you list explicitly in an 'aete' resource.
• A human-language description of the class. This is a Pascal string that can include any characters. When the resource description is compiled, the resource compiler pads the string and aligns the next field on a word boundary.
• A count of the properties described for this class and an array of property definitions.
• A count of the element classes described for this class and an array of element class definitions.

To define characteristics of an object class (for instance, whether an object of that class is a single item or a list of items, whether it is singular or plural, and so on), your application's 'aete' resource must define a special property of property ID kAESpecialClassProperties as the first property in the array of properties. Because object class data does not include flag bits, the flag bits of this property are used to specify attributes for the class to which the property belongs. The next section describes how this property is defined and used.

Property Data

Each item in the array of properties for an object class includes information about a single property. Figure 8-7 shows the format of the property data in an 'aeut' or 'aete' resource.

Figure 8-7 Structure of property data in an 'aeut' or 'aete' resource

The data for each property consists of the following items:

• The human-language name of the property. This is a Pascal string that can include any characters, including uppercase and lowercase letters and spaces. When the resource description is compiled, the resource compiler pads the string and aligns the next field on a word boundary.

  If the 'aete' resource specifies the name of a property as an empty string, the scripting component looks up, in its 'aeut' resource, the property name and other property data that correspond to the specified property ID. If the 'aete' resource specifies a name other than the name provided by the 'aeut' resource for the same property ID, the scripting component uses the new name with the same property data from the 'aeut' resource. You should specify an empty string for the name of any standard property that you list explicitly in an 'aete' resource.

• The four-character property ID for the property. If the 'aete' resource specifies a standard property name and a property ID other than the property ID for the equivalent standard property, the scripting component uses the new property ID with the standard property data for the specified name. You should specify the standard property ID for any standard property that you list explicitly in an 'aete' resource.
• A four-character class ID for the object class to which the property belongs. The meaning of this field varies according to the values of two of the flags that follow. One flag specifies whether the property is a list (singleItem or listOfItems), and the other specifies whether the values for the parameter are enumerated (enumerated or notEnumerated):
  • If the property is not a list and its values are not enumerated, this value is the class ID for the property.
  • If the property is a list and its values are not enumerated, this value is the class ID for each of the items in the list. (If not all the items in the list are of the same descriptor type, the flag specifying whether the value is a list must have the value singleItem, and the value of this field must be cAEList.)
  • If the property is not a list and its values are enumerated, this value is the four-character code for the enumeration defined in either the 'aete' or 'aeut' resource that contains the allowable values for the property. (If the values are enumerated but the enumeration is not defined in either the 'aete' or 'aeut' resource, the flag specifying whether the property's values are enumerated must have the value notEnumerated, and the value of this field must be typeEnumerated.)
  • If the parameter is a list and its values are enumerated, this value is the four-character code for the enumeration defined in the same resource that contains the allowable values for all of the items in the list. The values of the items in the list must all be one of these enumerated values.

• A human-language description of the property. This is a Pascal string that can include any characters. When the resource description is compiled, the resource compiler pads the string and aligns the next field on a word boundary.
• Flags that specify the following as Boolean values:
  • The first bit is reserved for future use. Its value must be set to reserved.
  • Whether the property is a single item (singleItem) or a list of items (listOfItems). (See the earlier description of the property's four-character class ID for information about how this value changes the meaning of the class ID.)
  • Whether named constants, called enumerators, are specified as the only valid values for the property (enumerated or notEnumerated). (See the earlier description of the property's four-character class ID for information about how this value changes the meaning of the class ID.) For information about specifying enumerators, see "Enumeration and Enumerator Data" on page 8-43.
  • Whether the property's value can (readWrite) or cannot (readOnly) be set by the Set Data Apple event.
  • Following 4 bits are reserved for future use.
  • Following 5 bits are reserved for future use as dialect-specific flags.
  • Whether the human-language name of the property is feminine (feminine) or not (notFeminine). This bit is used by dialects such as the AppleScript French dialect that make this distinction. For all other dialects, set the value of this bit to reserved.
  • Whether the human-language name of the property is masculine (masculine) or not (notMasculine). This bit is used by dialects such as AppleScript French that make this distinction. For all other dialects, set the value of this bit to reserved.
  • Whether the human-language name of the property is singular (singular) or plural (plural). This bit is used by dialects such as AppleScript French that make this distinction. If you set this bit to reserved, the scripting component will assign it the value singular.

"Extending the Standard Suites," which begins on page 8-21, includes sample Rez input for an 'aete' resource that adds a new property to a standard object class.

The array of properties in an 'aeut' resource begins with a definition of a special property that describes characteristics of the class as a whole using the flags in the definition of that property. A property used in this way to define characteristics of a class must be defined first in the array of properties for that class and must specify kAESpecialClassProperties ('c@#!') as the property ID, cType as the property class, and an empty string for the property name and property description. If you don't define such a property for a class in your application's 'aete' resource, the scripting component will assign that class the default values specified by the first constant for each flag bit in the Rez declaration for the 'aeut' resource. (See Listing 8-1, which begins on page 8-14, for the 'aeut' resource type declaration.)

Element Class Data

Each item in the array of elements for an object class includes information about a single element class and an array of key forms for that element class. Figure 8-8 shows the format of the object class data in an 'aeut' or 'aete' resource.

Figure 8-8 Structure of element class data in an 'aeut' or 'aete' resource

The following statements are included for each element class in the array of element classes for an object class:

• The four-character class ID for the element's object class.
• A count of key forms that apply to elements of this class within objects of the class for which these element classes are defined, followed by an array of key forms. Each item in the array must be a value from a special 'kfrm' enumeration. (The 'aeut' resource includes enumerators for the standard key forms defined in the Apple Event Registry: Standard Suites; an 'aete' resource can contain 'kfrm' enumerators for additional key forms that are specific to an application. For information about defining enumerators and enumerations, see "Enumeration and Enumerator Data" on page 8-43.) The enumerators for a 'kfrm' enumeration can include 'indx' (for the key form formAbsolutePosition), 'name' (for the key form formName), 'ID ' (for the key form formUniqueID), 'prop' (for the key form formPropertyID), 'rang' (for the key form formRange), 'rele' (for the key form formRelativePosition), and 'test' (for the key form formTest).

No names or descriptions are provided for element classes, because elements are specified by their object classes, and the declaration of each object class includes the name and description of the class.