Good scripting support starts with good application design. Before you’ve written a line of code, you need to think about the ways a user might want to control your application with scripts. You should design for the user first and work out the implementation details later.

As part of your design, work to separate program actions from user interface items. A scripter wants to accomplish a result (open the document "MyFile"), not necessarily perform the user interface actions they would use in the application (open the File menu; choose Open...; navigate to the file; and so on).

The next section describes some concrete steps to help determine the Apple event objects and commands your application will work with.

Similar to the process you used for Carbon events in Chapter 6, you need to identify the Apple events your application will support (in addition to the required commands shown in Table 14.1). To do that, you’ll identify the objects and commands a scripter could use to control your application. The following steps can help with that task:

You may have to work through these steps many times before you’re satisfied with your collection of objects and commands. Again, remember that you’re designing for users, so get their input as early as you can. Once you’re satisfied, you’re ready to incorporate the information into an 'aete' resource for your application.

Every scriptable application must include an Apple event terminology extension, or 'aete', resource. The 'aete' resource is the scripting dictionary for your application. It describes the Apple events that your application supports and the user terminology that corresponds to those events. The 'aete' resource allows the AppleScript scripting component to interpret scripts correctly and send the appropriate Apple events to your application during script execution.

Apple events contain data in the form of attributes and parameters, stored as Apple event descriptors, an opaque data type. Every Apple event has at least two attributes, an event class and an event ID, which together specify the type of event. The information in an 'aete' resource associates the English language terms a scripter will understand with the event class and event ID values your application and AppleScript work with.

You can find constants for many standard event classes and event IDs, as well as for the scripting terminology used by AppleScript itself, in the header files AERegistry.r, ASRegistry.r, and AppleEvents.r. When you build your 'aete' resource, you use constant values from these header files to identify standard commands and objects. For application-specific objects and commands, you define your own event class and event ID values.

As with Carbon events and the Carbon Event Manager, scriptable applications rely on a callback mechanism that dispatches Apple events to handler functions. You’ll need to write a handler for each type of Apple event your application handles. In this section and the following section you’ll learn how to add support for one of the required Apple events described previously, the Open Documents event to the Moon Travel Planner application.

Example 14.3 shows the format for an Apple event handler.

OSErr MyAEEventHandlerCallback (
    const AppleEvent *theAppleEvent,
    AppleEvent *reply,
    UInt32 handlerRefcon);

The first parameter is a pointer to the Apple event to handle, the second parameter is a pointer to the default reply Apple event provided by the Apple Event Manager, and the third parameter is a reference constant your application can use to supply additional information to your handler. The reference constant can be a simple four-byte value, a pointer to a block of data, or it can be NULL if you don’t need it.

Example 14.4 shows how the Moon Travel Planner might implement an Open Documents event handler. The reason all well-behaved Mac OS X applications should support the Open Documents Apple event is that when a user selects one or more of an application’s documents in the Finder and double-clicks, the Finder sends the application an Apple event describing a list of files that it should open. To respond properly to this Apple event, your application extracts the file descriptions from the Apple event and opens the documents.

OSStatus MTPHandleOpenAppleEvent(const AppleEvent * appleEvt, 
        AppleEvent * reply, SInt32 refcon)
{
    AEDesc fileList = {typeNull, NULL};                                  // 1
    OSErr err;
    SInt32 itemsInList;
    FSRef fileToOpen;
    HFSUniStr255 theFileName;
    CFStringRef fileNameCFString;   
    WindowRef newWindow;
    
    err = AEGetParamDesc(appleEvt, keyDirectObject,                      // 2
                         typeAEList, &fileList);
    if (err == noErr) 
    {
        err = AECountItems(&fileList, &itemsInList);                     // 3
        if (err == noErr && itemsInList > 0) 
        {
            OSType     keyword;
            OSType     returnedType;
            Size    actualSize;
            short i;
            for (i = 1; i <= itemsInList; i++)                            // 4
            {
                err = AEGetNthPtr(&fileList, i, typeFSRef, &keyword,      // 5
                       &returnedType, &fileToOpen, 
                       sizeof(FSRef), &actualSize);
                    
                if (err == noErr) 
                {                                
                    err = FSGetCatalogInfo(&fileToOpen, kFSCatInfoNone,   // 6
                            NULL, &theFileName, NULL, NULL);
                    fileNameCFString =  CFStringCreateWithCharacters (    // 7
                                            NULL, 
                                            theFileName.unicode, 
                                            theFileName.length);
                                            
                    newWindow = MTPDoNewItinerary( fileNameCFString);     // 8
                    
                    ShowWindow(newWindow);                                // 9
                    
                    err  = MTPReadFile(&fileToOpen, newWindow);           // 10
                }                               
            }
        }
    }
    return err;
}

Here’s how the MTPHandleOpenAppleEvent function works:

Your application can implement a Print Documents event handler with much of the same code shown in Example 14.4. As with the Open Documents event, the Apple event contains a list of one or more references to files that your application should print. To do so, you extract the file references as shown here, do any preparation you might need for printing, then call the MTPDoPrint function to display the Print dialog.

When a parameter consists of an object specifier record (an Apple event descriptor that specifies an Apple event model object), your handler should call the AEResolve function to start the process of resolving the object specifier. For example, the specifier created from the statement:

third word in the second paragraph in the document "MyReport"

resolves to an Apple event descriptor that identifies the specified word.

As you do with Carbon events, your application must install its Apple event handlers. You do so by calling the function AEInstallEventHandler. Example 14.5 shows how to install the Open Documents event handler described previously.

OSErr err;
err = AEInstallEventHandler( 
            kCoreEventClass,
            kAEOpenDocuments,
            NewAEEventHandlerUPP((AEEventHandlerProcPtr) MTPHandleOpenAppleEvent), 
            NULL, 
            false);

The first two parameters specify an event class and event ID that identify the type of Apple event. The third parameter is a pointer to your event handler. You create this pointer by calling the function NewAEEventHandlerUPP. The fourth parameter has the value NULL, indicating that this event handler doesn’t need any information passed to it in its refcon parameter. And the final parameter has the value false, indicating that this handler is an application handler, not a special type of handler.

If your application uses the Carbon event model, as the Moon Travel Planner application does, and calls RunApplicationEventLoop, you won’t need to do anything special to receive Apple events. The Carbon Event Manager will automatically direct Apple events sent to your application to the Apple event handlers you have installed. Your handlers then perform the necessary operations to handle the events they receive.

In addition, applications that use the Carbon event model don’t need to write handlers for the required Run or Quit Apple events, because they’re handled automatically.

AppleScript is a mature and powerful scripting language that lets users streamline application tasks and allows applications to communicate with each other using Apple events. The Apple Event Manager allows your application to create and interpret Apple events, and you can use various third-party applications to help you to create and debug scripts. Most important commercial applications are AppleScript-savvy, so yours should be no exception.