Inside Macintosh: Interapplication Communication /

Chapter 8 - Apple Event Terminology Resources

Handling the Get AETE Event

A scripting component sends the Get AETE event to an application when it needs information about the user terminology specified by the application. For example, the AppleScript component sends the Get AETE event when it first attempts to compile a tell statement that specifies a particular application. If your application does not handle the Get AETE event, the scripting component reads the terminology information it needs directly from your application's 'aete' resource. Applications that support additional plug-in modules, each with its own 'aete' resource, must provide an 'scsz' resource and a handler for the Get AETE event that collects the 'aete' resources from the modules that are currently running.

If your application does provide separate plug-in modules, the Get AETE event allows it to gather information from the 'aete' resources for the modules that are currently running and return the terminology information along with your application's built-in terminology information to the scripting component in the reply event.

Here is a summary of the structure of a Get AETE event:

Get AETE--Get an application's 'aete' resource
Event class		kASAppleScriptClass
Event ID		kGetAETE
Required parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeInteger
	Data:	Language code
Required reply parameter
	Keyword:	keyDirectObject
	Descriptor type:	typeAEList or typeAETE
	Data:	The application's terminologies
Description		Sent by a scripting component to an application when the scripting component needs information about the application's user terminology

Your application can't handle the Get AETE event unless it is running. If your application doesn't provide a handler for the Get AETE event, the scripting component can obtain terminology information directly from your application's 'aete' resource even if your application is not running.

If your application handles the Get AETE event, it must also provide a scripting size resource. A scripting size resource is a resource of type 'scsz' that provides information about an application's capabilities for use by scripting components. It allows your application to declare whether it needs the Get AETE event and to specify preferences for the sizes of the portion of your application's heap used by a scripting component. For information about the 'scsz' resource, see "The Scripting Size Resource" on page 8-45.

A handler for the Get AETE event should perform the following tasks:

• Obtain the language code specified by the event.
• Create a descriptor list to hold the 'aete' resources.
• Collect the 'aete' resources from all the application's plug-in modules that are currently running, including the application itself, and add them to the list.
• Add the list to the reply Apple event.

Listing 8-4 provides an example of a handler for the Get AETE event.

Listing 8-4 A handler for the Get AETE event

FUNCTION MyGetAETE (theAE: AppleEvent; theReply: AppleEvent; 
                     refCon: LongInt): OSErr;
VAR
   theList:       AEDescList;
   returnedType:  DescType;
   actualSize:    Size;
   languageCode:  Integer;
   myErr:         OSErr;
BEGIN
   MyGetAETE := errAEEventNotHandled;
   languageCode := 0;
   {if a reply was not requested, then don't handle}
   IF theReply.dataHandle = NIL THEN
      Exit(MyGetAETE);
   {get the language code that AppleScript is requesting so that }
   { this function can return the aete of a specified language}
   myErr := AEGetParamPtr(theAE, keyDirectObject, 
                           typeLongInteger, returnedType, 
                           @languageCode, sizeOf(LongInt), 
                           actualSize);
   IF myErr <> noErr THEN
      Exit(MyGetAETE);
   {create a list}
   myErr := AECreateList(NIL, 0, FALSE, theList);
   IF myErr <> noErr THEN
      Exit(MyGetAETE);
   {get the requested 'aete' resources and put in the list--the }
   { MyGrabAETE application-defined function does this}
   {your code should iterate all of your installed code }
   { extensions and add the aete for each that matches the }
   { language code requested}
   myErr := MyGrabAETE(languageCode, theList);
   IF myErr <> noErr THEN
   BEGIN
      myErr := AEDisposeDesc(theList);
      Exit(MyGetAETE);
   END;
   {add list to reply Apple event}
   myErr := AEPutParamDesc(theReply, keyDirectObject, theList);
   myErr := AEDisposeDesc(theList);
   myGetAETE := myErr;
END;

The MyGetAETE handler in Listing 8-4 begins by setting the function result to errAEEventNotHandled. The function is set to this result if for any reason the handler doesn't successfully handle the event, so that a system handler provided by the scripting component can at least read the terminology information directly from the application's own 'aete' resource. The handler in Listing 8-4 then checks the language code specified by the event. After checking to make sure the reply exists, the handler creates a list and uses the application-defined function MyGrabAETE to collect all the appropriate terminology information and append it to the list. The MyGetAETE handler then adds the list to the reply event.