Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 5 - Creating and Sending Apple Events / Creating an Apple Event

Specifying Optional Parameters for an Apple Event

The parameters for a given Apple event are listed in the Apple Event Registry: Standard Suites as either required or optional. Your application does not usually have to include Apple event parameters that are listed as optional; the target application uses default values for parameters that are listed as optional if your application does not provide them. The Apple Event Registry: Standard Suites defines the default value a target application should use for each optional parameter of a specific Apple event.

The guidelines listed in the Apple Event Registry: Standard Suites for which parameters should be considered optional and which should be considered required are not enforced by the Apple Event Manager. Instead, the source application indicates which Apple event parameters it considers optional by listing the keywords for those parameters in the keyOptionalKeywordAttr attribute.

The keyOptionalKeywordAttr attribute does not contain the optional parameters; it simply lists the keywords of any parameters for the Apple event that the source application wants to identify as optional. Although the source application is responsible for providing this information in the keyOptionalKeywordAttr attribute of an Apple event, it is not required to provide this attribute.

If a keyword for an Apple event parameter is not included in the keyOptionalKeywordAttr attribute, the source application expects the target application to understand the Apple event parameter identified by that keyword. If a target application cannot understand the parameter, it should return the result code errAEParamMissed and should not attempt to handle the event.

If a keyword for an Apple event parameter is included in the keyOptionalKeywordAttr attribute, the source application does not require the target application to understand the Apple event parameter identified by that keyword. If the target application cannot understand a parameter whose keyword is included in the keyOptionalKeywordAttr attribute, it should ignore that parameter and attempt to handle the Apple event as it normally does.

A source application can choose not to list the keyword for an Apple event parameter in the keyOptionalKeywordAttr attribute even if that parameter is listed in the Apple Event Registry: Standard Suites as an optional parameter. This has the effect of forcing the target application to treat the parameter as required for a particular Apple event. If the target application supports the parameter, it should handle the Apple event as the client application expects. If the target application does not support the parameter and calls an application-defined routine such as MyGotRequiredParams to check whether it has received all the required parameters, it finds that there's another parameter that the client application considered required, and should return the result code errAEParamMissed.

If a source application wants a target application to attempt to handle an Apple event regardless of whether the target application supports a particular Apple event parameter included in that Apple event, the source application should list the keyword for that parameter in the keyOptionalKeywordAttr attribute.

It is up to the source application to decide whether to list a parameter that is described as optional in the Apple Event Registry: Standard Suites in the keyOptionalKeywordAttr attribute of an Apple event. For example, suppose a source application has extended the definition of the Print event to include an optional keyColorOrGrayscale parameter that specifies printing in color or gray scale rather than black and white. The source application might decide whether or not to list the keyword keyColorOrGrayscale in the keyOptionalKeywordAttr attribute according to the characteristics of the print request. If the source application requires the target application to print a document in color, the source application could choose not to add the keyword keyColorOrGrayscale to the keyOptionalKeywordAttr attribute; in this case, only target applications that supported the keyColorOrGrayscale parameter would attempt to handle the event. If the source application does not require the document printed in color, it could choose to add the keyword keyColorOrGrayscale to the keyOptionalKeywordAttr attribute; in this case, the target application will attempt to handle the event regardless of whether it supports the keyColorOrGrayscale parameter.

Your application can add optional parameters to an Apple event the same way it adds required parameters, using the AECreateDesc, AEPutParamPtr, and AEPutParamDesc functions as described in the previous section, "Adding Parameters to an Apple Event." If your application chooses to provide the keyOptionalKeywordAttr attribute for an Apple event, it should first create a descriptor list that specifies the keywords of the optional parameters, then add it to the Apple event as a keyOptionalKeywordAttr attribute.

Listing 5-1 shows an application-defined routine, MyCreateOptionalKeyword, that creates the keyOptionalKeywordAttr attribute for the Create Publisher event.

Listing 5-1 Creating the optional keyword for the Create Publisher event

FUNCTION MyCreateOptionalKeyword
                        (VAR createPubAppleEvent: AppleEvent)
                         : OSErr;
VAR
   optionalList:  AEDescList;
   myOptKeyword1: AEKeyword;
   myOptKeyword2: AEKeyword;
   myErr:         OSErr;
   ignoreErr:     OSErr;
BEGIN                   
   myOptKeyword1 := keyDirectObject;
   {create an empty descriptor list}
   myErr := AECreateList(NIL, 0, FALSE, optionalList);
   IF myErr = noErr THEN 
   BEGIN
      {add the keyword of the first optional parameter}
      myErr := AEPutPtr(optionalList, 1, typeKeyword, 
                        @myOptKeyword1, SizeOf(myOptKeyword1));
      IF myErr = noErr THEN 
      BEGIN
         {add the keyword of the next optional parameter}
         myOptKeyword2 := keyAEEditionFileLoc;
         myErr := AEPutPtr(optionalList, 2, typeKeyword, 
                           @myOptKeyword2, SizeOf(myOptKeyword2));
      END;
      IF myErr = noErr THEN 
         {create the keyOptionalKeywordAttr attribute and add it }
         { to the Create Publisher event}
         myErr := AEPutAttributeDesc(createPubAppleEvent,
                                     keyOptionalKeywordAttr, 
                                     optionalList);
   END;
   ignoreErr := AEDisposeDesc(optionalList);
   MyCreateOptionalKeyword := myErr;
END;

The MyCreateOptionalKeyword function shown in Listing 5-1 adds to a descriptor list the keyword of each parameter that the source application considers optional. Each keyword is added as a descriptor record with the descriptor type typeKeyword. The function specifies that the target application can handle the Create Publisher event without supporting parameters identified by the keywords keyDirectObject and keyAEEditionFileLoc. (These are the parameters that specify the Apple event object to publish and the location of the edition container; if these parameters are missing, the target application creates a publisher for the current selection using the application's default edition container.) After adding these keywords to the descriptor list, the function creates the keyOptionalKeywordAttr attribute using the AEPutAttributeDesc function.

Typically a target application does not examine the keyOptionalKeywordAttr attribute directly. Instead, a target application that supports a parameter listed as optional in the Apple Event Registry: Standard Suites attempts to extract it from the Apple event (using AEGetParamDesc, for example). If it can't extract the parameter, the target application uses the default value, if any, listed in the Apple Event Registry. A target application can use the keyMissedKeywordAttr attribute to return the first required parameter (that is, considered required by the source application), if any, that it did not retrieve from the Apple event. The keyMissedKeywordAttr attribute does not return any parameters whose keywords are listed in the keyOptionalKeywordAttr attribute of the Apple event.