Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Interapplication Communication /: Chapter 8 - Apple Event Terminology Resources / Creating an Apple Event Terminology Extension Resource

Extending the Standard Suites
If, like the 'aete' resource shown in Listing 8-2, your application's 'aete' resource indicates that you support an entire standard suite, the scripting component automatically makes use of all the terminology for that suite provided by its 'aeut' resource. For this reason, you can easily extend the definitions for a suite that your application supports in its entirety: just provide arrays in the 'aete' resource for the definitions not already included in the 'aeut' resource. For example, if you're extending the definition of an event to support a single additional parameter, you should provide an array of parameters that includes one item: the description of the new parameter. Similarly, if you're not extending the contents of a particular array, you don't need to include the array in the 'aete' resource.
Although an array of descriptions in an 'aete' resource need not include descriptions that are already provided by the 'aeut' resource, you must include information that defines the position of the array in relation to the other information in the 'aete' resource. As Table 8-3 on page 8-13 shows, you can nest the arrays in an 'aete' resource within other arrays: for example, an array of parameters is part of the description of an event, and the event description is, in turn, part of the array of event descriptions for a suite.
To add a description of a single new parameter to the definition of an Apple event in a suite that your application supports in its entirety, you need to provide

an array of parameters containing one element: the description of the new parameter
information that identifies the event definition to which you're adding the parameter
information that identifies the suite containing the event

Listing 8-3 illustrates how this works. This Rez input adds two new parameters ("number of copies" and "print quality") to the Print Documents event in the Required suite, one enumeration (three values for the "print quality" parameter of the Print Documents event) to the Required suite, and a new property ("first indent") to the cParagraph class in the Text suite. It also adds a plural synonym for the cParagraph class: the word "paragraphs."
Listing 8-3 Rez input for an 'aete' resource that extends the definitions of the Required, Core, and Text suites
#define keyMyNumberOfCopies   'numc'
#define keyMyPrintQuality     'prtq'
#define typePrintQuality      'pqen'
#define kFast                 'fast'
#define kNormal               'nrml'
#define kHighQuality          'hiql'
#define pFirstIndent          'indt'

resource 'aete' (0, "SuiteExtensions") {
   1,                                     /*major version in BCD*/
   0,                                     /*minor version in BCD*/
   english,                               /*language code*/
   roman,                                 /*script code*/
   {  /*array Suites: 3 elements*/
      /*[1]*/
      "",                              /*human-language name for suite; */
                                       /* 'aeut' supplies "Required Suite"*/
      "Events that every application should support", /*suite description*/
      kAERequiredSuite,                   /*suite code*/
      1,                                  /*suite level*/
      1,                                  /*suite version*/
      {  /*array Events: 1 element*/
         /*[1]*/
         "",                           /*human-language name for event; */
                                       /* 'aeut' supplies "Print Documents"*/
         "Print the specified list of documents",     /*event description*/
         kCoreEventClass,                 /*event class*/
         kAEPrintDocuments,               /*event ID*/
         noReply,                         /*reply type*/
         "",                              /*reply description*/
         replyOptional,                   /*reply is optional*/
         singleItem,                      /*reply must be single item*/
         notEnumerated,                   /*type is not enumerated*/
         reserved,                        /*these 13 bits are reserved*/
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         typeAlias,                       /*direct parameter type*/
         "List of documents to print",    /*direct parameter description*/
         directParamRequired,             /*direct parameter is required*/
         listOfItems,                     /*direct parameter must be list*/
         notEnumerated,                   /*type is not enumerated*/
         doesntChangeState,               /*event does not change */
                                          /* server's state*/
         reserved,                        /*these 12 bits are reserved*/
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         reserved,
         {  /*array OtherParams: these fields describe the additional */
            /* parameters Number of Copies and Print Quality to the */
            /* standard Print Documents event*/
            /*[1]*/
            "number of copies",        /*human-language name for parameter*/
            keyMyNumberOfCopies,          /*parameter keyword*/
            typeShortInteger,             /*parameter type*/
            "Number of copies to print",  /*parameter description*/
            optional,                     /*parameter is optional*/
            singleItem,                   /*parameter must be single item*/
            notEnumerated,                /*type is not enumerated*/
            reserved,                     /*these 13 bits are reserved*/
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            /*[2]*/
            "print quality",           /*human-language name for parameter*/
            keyMyPrintQuality,            /*parameter keyword*/
            typePrintQuality,             /*parameter type*/
            "The quality of the printing",/*parameter description*/
            optional,                     /*parameter is optional*/
            singleItem,                   /*parameter must be single item*/
            enumerated,                   /*type is enumerated*/
            reserved,                     /*these 13 bits are reserved*/
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved
         }
      },
      {  /*array Classes: 0 elements*/
      },
      {  /*array ComparisonOps: 0 elements*/
      },
      {  /*array Enumerations: 1 element*/
         /*these fields add the 'pqen' enumeration to the Required suite*/
         /*[1]*/
         typePrintQuality,                /*enumeration ID*/
         {  /*array Enumerators: 3 elements*/
            /*[1]*/
            "Fast",                       /*enumerator name*/
            kFast,                        /*enumerator ID*/
            "Print as quickly as possible",/*enumerator description*/
            /*[2]*/
            "Normal",                     /*enumerator name*/
            kNormal,                      /*enumerator ID*/
            "Print at normal speed",      /*enumerator description*/
            /*[3]*/
            "High-Quality",               /*enumerator name*/
            kHighQuality,                 /*enumerator ID*/
            "Print at highest quality possible" /*enumerator description*/
         }
      },
      /*[2]*/
      "",                                 /*human-language name for suite; */
                                          /* 'aeut' supplies "Core Suite"*/
      "Suite that applies to all applications",       /*suite description*/
      kAECoreSuite,                       /*suite code*/
      1,                                  /*suite level*/
      1,                                  /*suite version*/
      {  /*array Events: 0 elements*/
      },
      {  /*array Classes: 0 elements*/
      },
      {  /*array ComparisonOps: 0 elements*/
      },
      {  /*array Enumerations: 0 elements*/
      },
      /*[3]*/
      "",                                 /*human-language name for suite; */
                                          /* 'aeut' supplies "Text Suite"*/
      "A set of basic classes for text processing",   /*suite description*/
      kAETextSuite,                       /*suite code*/
      1,                                  /*suite level*/
      1,                                  /*suite version*/
      {  /*array Events: 0 elements*/
      },
      {  /*array Classes: 1 element*/
         /*[1]*/
         "paragraph",                     /*human-language name for class*/
         cParagraph,                      /*class ID*/
         "A paragraph",                   /*class description*/
         {  /*array Properties: 1 element*/
            /*[1]*/
            "first indent",            /*human-language name for property*/
            pFirstIndent,                 /*property ID*/
            cLongInteger,                 /*property class*/
            "First indent of paragraph in points",/*property description*/
            reserved,                     /*reserved*/
            singleItem,                   /*property is single item*/
            notEnumerated,                /*type is not enumerated*/
            readWrite,                    /*property can be modified*/
            reserved,                     /*these 12 bits are reserved*/
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved
         },
         {  /*array Elements: 0 elements*/
         },
         "paragraphs",                 /*human-language name for class*/
         cParagraph,                   /*class ID*/
         "Every paragraph",            /*class description*/
         {  /*array Special Properties: 1 element*/
            /*[1]*/
            "",                        /*human-language name for property*/
            kAESpecialClassProperties,    /*property ID*/
            cType,                        /*property class*/
            "",                           /*property description*/
            reserved,                     /*reserved*/
            singleItem,                   /*property is single item*/
            notEnumerated,                /*type is not enumerated*/
            readOnly,                     /*property cannot be modified*/
            reserved,                     /*these 11 bits are reserved*/
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            reserved,
            plural                        /*human-language name is */
                                          /* plural form*/
         },
         {  /*array Elements: 0 elements*/
         },
      },
      {  /*array ComparisonOps: 0 elements*/
      },
      {  /*array Enumerations: 0 elements*/ 
      }
   }
};
In Listing 8-3, the possible values for the "print quality" parameter belong to an enumeration. This is indicated by the term enumerated in the parameter description. For this reason, the parameter type field contains the ID for the enumeration--typePrintQuality.
Listing 8-3 also adds a plural synonym for "paragraph" to the array of classes: the word "paragraphs." Note that this is listed as if it were an additional class, except that it also specifies cParagraph as the class ID. The first property listed for the synonym has property ID kAESpecialClassProperties. This property describes characteristics of the class as a whole; the last flag bit for this property is set to plural, indicating that the term paragraphs is a plural term for the specified class. This property must always be the first property listed for a class. For more information about the kAESpecialClassProperties property, see "Property Data," which begins on page 8-39.
An enumeration is described only by its ID; its declaration does not include a name or description field. However, a name, value, and description must be provided for each of the enumerators in an enumeration.
You can use the method illustrated in Listing 8-3 only to add to the definitions of Apple events and Apple event object classes, not to support subsets of them. For example, to support only a subset of the parameters of an Apple event or only some of the elements or properties of an existing object class, you must list all the definitions from that suite that you do support. The next section, "Supporting Subsets of Suites," provides more information about how to do this.
Human-language names for Apple events, object classes, and so on (including extensions) can include both uppercase and lowercase letters and spaces. For comparison purposes, case doesn't matter. However, note that the human-language names defined in Listing 8-3 are all lowercase. This convention ensures that scripts in which these terms appear won't have capital letters in unexpected places.
Scripting components that get identifiers or strings from user terminology resources are free to change the identifiers or strings as necessary (eliminating spaces, converting identifiers to all uppercase or lowercase, or changing the identifiers altogether) to meet the requirements of a particular task.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.