Inside Macintosh: Programmer's Guide to MacApp / Part 1 - MacApp Theory and Architecture

Chapter 6 - Scripting

Attaching Scripts

MacApp provides true attachability through its Apple event dispatching mechanism and its MScriptableObject class--that is, a script can be attached to an object, and any Apple events specifying that object will first be dispatched to the attached script. The attached script may perform an action and pass the event on to the specified object, it may perform an action and return, or it may ignore the event and pass it on to the specified object.

To enable attachability in your application, you must build the application with the qAttachable flag set to TRUE. If you never attach scripts, you can omit MacApp's attachability code. "Common Command-Line Options," beginning on page 678, describes how to build your application with and without attachability code when using MPW's MABuild system.

Attaching a Script to an Object

To have an attached script, an object's class must mix in the MScriptableObject class. You attach a script to an object that mixes in MScriptableObject by calling the SetObjectProperty method and passing two values: a CAEDesc value that describes the script and a DescType value that specifies the pScript property. The MScriptableObject class has a field fOSAScript of type COSAScriptCntPtr. The SetObjectProperty method calls the SetOSAScript method, which sets the fOSAScript field.

In setting the fOSAScript field, the SetOSAScript method notifies the global TOSADispatcher object that there is an object with a script attached. When the first script is attached, the dispatcher object calls its InstallPreDispatchHandler method (page 152) to set up MacApp's mechanism for predispatching Apple events to attached scripts.

When you remove an attached script, the MScriptableObject::FreeOSAScript method calls the global dispatcher object's ScriptDetached method, which removes the predispatch handler if there are no more scripts attached (the fAttachedScripts count is equal to 0).

"Recipe--Attaching a Script to Objects in Your Application," beginning on page 365, provides a simple script and shows how you can attach it to every window in your application. MacApp even saves the script with the document, as described in the following section.

Saving an Attached Script With a Document

The TFileBasedDocument class contains methods to read and write an attached script. Reading and writing are controlled by a field of the TDocument class, fSaveAttachedScript, which specifies whether an attached script should be saved when the document is written to a file (or read in when the document is read from a file). By default, fSaveAttachedScript is set to TRUE.

If the fSaveAttachedScript field has the value TRUE when you write a document object based on TFileBasedDocument, the DoWrite method calls the DoWriteScript method. If there is an attached script, the DoWriteScript method calls the WriteOSAScript method, a method of MScriptableObject, which writes the attached script to the file stream.

As a result of this implementation, if you attach a script to a window in your application, the script will automatically be saved with the window's document. When you open the document, the script will be read in and enabled.

Note

When you attach a script to a window by setting the pScript property, the window defers to its document, so the script is actually attached to the document.