Legacy Document

Inside Macintosh: Interapplication Communication /

Chapter 10 - Scripting Components / Using Scripting Component Routines

Using a Script Context to Handle an Apple Event

The preceding sections describe how you can load, compile, modify, and execute scripts under circumstances determined by your application. Your application can use these techniques to associate a script with an Apple event object or application object and execute the script when the user manipulates the object in some way.

Another way to execute a script is to use a script context (called a script object in AppleScript) to handle an Apple event. To do this, your application passes both the event and the script context to OSAExecuteEvent or OSADoEvent. You can also associate script contexts with Apple event objects--that is, objects in your application that can be identified by object specifier records. If an Apple event acts on an object with which a script context is associated, your application attempts to use the script context to handle the Apple event.

For example, Figure 7-7 on page 7-22 shows how you can use a general Apple event handler to provide initial processing for all Apple events received by your application. Listing 10-7 shows an example of such a handler.

You install a general Apple event handler like the one in Listing 10-7 in your application's special handler dispatch table using the constant keyPreDispatch:

myErr := AEInstallSpecialHandler(keyPreDispatch,
                               @MyGeneralAppleEventHandler, 
                               FALSE);

When it receives an Apple event, the MyGeneralAppleEventHandler function in Listing 10-7 first extracts the event's direct parameter. It then calls another application-defined function, MyGetAttachedScript, which checks whether the direct parameter contains an object specifier record, calls AEResolve to locate the corresponding Apple event object, and returns a script ID for any script context attached to that object.

If a script context is associated with the object, MyGeneralAppleEventHandler passes the script context's script ID and the Apple event to the OSADoEvent function. Otherwise, MyGeneralAppleEventHandler returns errAEEventNotHandled, which causes the Apple Event Manager to look for an appropriate handler in the application's Apple event dispatch table or elsewhere using standard Apple event dispatching.

The OSADoEvent function in Listing 10-7 takes a component instance that identifies a connection with the generic scripting component. (If it has not already done so, the generic scripting component in turn opens a connection with the scripting component that created the script context.) In addition to the component instance, the Apple event, and the script ID for the script context, OSADoEvent takes a parameter that indicates no mode flags are set and a VAR parameter that contains any reply Apple event returned as a result of handling the event.

If the scripting component determines that a script context can't handle the specified event (for example, if an AppleScript script context doesn't include statements that handle the event), OSADoEvent returns errAEEventNotHandled. If OSADoEvent attempts to use the script context to handle the event, the function returns a reply event that contains either the resulting script value or, if an error occurred, information about the error.

The script context shown in Figure 7-7 contains an AppleScript handler for the Move event. Such handlers exist only as AppleScript statements in a script context and do not have corresponding entries in an application's Apple event dispatch table. However, a handler in a script context can modify or override the actions performed by an application's standard Apple event handlers installed in its Apple event dispatch table. The next section, "Supplying a Resume Dispatch Function," describes how this works.

Listing 10-7 A general Apple event handler that uses the OSADoEvent function

FUNCTION MyGeneralAppleEventHandler (event: AppleEvent; 
                                     reply: AppleEvent;
                                     refcon: LongInt): OSErr;
VAR
   dp, resultDesc:   AEDesc;
   scriptID:         OSAID;
   myErr, ignoreErr: OSErr;
   myOSAErr:         OSAError;
BEGIN
   {get the direct parameter}
   myErr := AEGetParamDesc(event, keyDirectObject, typeWildCard, 
                           dp);
   {get script ID for script context attached to object }
   { specified in direct parameter}
   IF MyGetAttachedScript(dp, scriptID) THEN 
      {execute the handler in the script context handler and, if }
      { necessary, the default Apple event handler}
      myOSAErr := OSADoEvent(gScriptingComponent, event, 
                              scriptID, kOSAModeNull, reply)
   ELSE
      myOSAErr := errAEEventNotHandled;
   ignoreErr := AEDisposeDesc(dp);
   MyGeneralAppleEventHandler := OSErr(myOSAErr);
END; 

For more information about OSADoEvent, OSAExecuteEvent, and other routines related to the use of script contexts to handle Apple events, see page 10-70.