Using high-level events, an application can instruct another application to perform a specific action, such as adding a row to a spreadsheet or changing the font size of a paragraph. An application can also request information from another application; for example, it might request a dictionary application to return the definition of a particular word.

Fig 1 shows the general event-handling mechanism. In Fig 1, three different applications are communicating with each other by sending and receiving high-level events. Note that high-level events are placed in a separate queue maintained by the operating system and that a high-level event queue is maintained for each application that has announced itself as capable of receiving high-level events.

For effective communication between applications, an application must define the set of high-level events it responds to and let other applications know the events it accepts. For a high-level event sent by one application to be understood by another application, the sender and receiver must agree on a protocol, that is, on the way the event is to be interpreted.

Apple Events

Communication between two applications which support Apple events is initiated by a client application, which sends an Apple event to request a service or information. The application providing the service or information is called a server application. Fig 2 shows a common Apple event, called the Open Documents event. The Finder (which is, itself, an application) is the client; it requests that the application My Application open the documents named Document A and Document B. My Application responds by opening windows for the specified documents.

An application can also send Apple events to itself, thus acting as both client and server.

To identify Apple events and respond appropriately, every application can rely on a vocabulary of standard Apple events which developers and Apple have established for all applications to use. These events are defined in the Apple Event Registry: Standard Suites. The standard suites (groups of Apple events that are usually implemented together) include:

• The required suite, which consists of five Apple events that the Finder sends to applications. The required Apple events are:

  • Open Application.

  • Re-open Application.

  • Open Documents.

  • Print Documents.

  • Quit Application.

• The core suite, which consists of the basic Apple events, including Get Data, Set Data, Move, Delete and Save, that nearly all applications use to communicate.

• The functional-area suite, which consists of a group of Apple events which support a related functional area, and which include the Text suite and the Database suite.

• The appearance suite, which consists of four Apple events used to advise all foreground applications when one of the following changes has been made in the Fonts tab of the Appearance control panel:

  • Appearance.

  • Large system font.

  • Small system font.

  • Views font.

The Finder uses the required Apple events as part of the mechanism for launching and terminating applications. Your application must support the required Apple events.

This chapter is primarily concerned with the required Apple events and the Appearance Manager Apple events, exploring the subject of Apple events only to the extent necessary to gain an understanding of the measures involved in supporting the required and appearance suites.

Apple Event Attributes and Parameters

• The required Apple events have the value 'aevt' in the message field of their event structures. 'aevt' is represented by the constant kCoreEventClass.

• The Appearance Manager Apple events have the value 'appr' in the message field of their event structures. 'appr' is represented by the constant kAppearanceEventClass.

Event ID

The following are the event IDs for the five required Apple events and the four Appearance Manager Apple events. (Those introduced with Mac OS 8.5 appear in dark blue.)

Target Application

There are various kinds of Apple event parameters, including direct parameters and additional parameters.

Direct Parameters

To process this event, your application would use the AEProcessAppleEvent function, which uses the event class and event ID attributes to dispatch the event to My Application's Open Documents handler. In response, the Open Documents handler opens the documents specified in the direct parameter.

Data Structures Within Apple Events

     struct AEDesc
     {
       DescType descriptorType;  // Type of data.
       Handle   dataHandle;      // Handle to data.
     };
     typedef struct AEDesc AEDesc;

The following illustrates the logical arrangement of a descriptor structure with a descriptor of type typeChar, which specifies that the data handle refers to an unterminated string:

The following illustrates the logical arrangement of a descriptor structure with a descriptor type of typeType, which specifies that the data handle refers to a four-character code (in this case the constant kCoreEventClass, whose value is 'aevt'):

Address Descriptor Structure

     typedef AEDesc AEAddressDesc;  // An AEDesc which contains addressing data.

Like several other data structures defined by the Apple Event Manager for use in Apple event attributes and Apple event parameters, an address descriptor structure is identical to a descriptor structure of data type AEDesc; the only difference is that the data for an address descriptor structure must always consist of an application's address.

Keyword-Specified Descriptor Structures

typedef FourCharCode AEKeyword; Constants are typically used to represent keywords. Keywords for Attributes. The following is a partial list of keyword constants for Apple event attributes:

Keywords for Parameters. The following is a list of keyword constants for commonly used Apple event parameters:

The Apple Event Manager associates keywords with specific descriptor structures by means of a keyword-specified descriptor structure, a data structure of type AEKeyDesc that consists of a keyword and a descriptor structure:

     struct AEKeyDesc 
     {
       AEKeyword descKey;  // Keyword.
       AEDesc    descContent;  // Descriptor structure.
     };
     typedef struct AEKeyDesc AEKeyDesc;

Descriptor Lists, AE Structures, and AppleEvent Structures

A descriptor list is a data structure of type AEDescList defined by the data type AEDesc. That is, a descriptor list is a descriptor structure whose handle refers to a list of other descriptor structures (unless it is an empty list):

     typedef AEDesc AEDescList;  // List of descriptor structures.

This descriptor list provides the data for a keyword-specified descriptor structure.

AE Structure

     typedef AEDescList AERecord;  // List of keyword-specified descriptor structures.

     typedef AERecord AppleEvent;  // List of attributes and parameters for Apple event.

Handling Apple Events

As a first step in supporting Apple events, and as previously stated, your application should support the required Apple events sent by the Finder. To support the required Apple events, you must:

• Set the isHighLevelEventAware flag in the 'SIZE' resource of your application.

• Test for high-level events in your application's event loop. An Apple event (like all high-level events) is identified by a message class of kHighLevelEvent in the what field of the event structure. Your application should therefore test the what field of the event structure to determine whether it contains the value represented by kHighLevelEvent.

• Use AEProcessAppleEvent to process the Apple events. AEProcessAppleEvent first identifies the Apple event by examining the data in the event class and event ID attributes. It then uses that data to call the appropriate Apple event handler provided by your application.

• Provide handlers for the required Apple events in your application. Your Apple event handlers must extract the pertinent data from the Apple event, perform the requested action, and return a result.

• Use AEInstallEventHandler to install your Apple event handlers. This function installs handlers in an Apple event dispatch table for your application. The Apple Event Manager uses this table to map Apple events to handlers in your application When your application calls AEProcessAppleEvent, the Apple Event Manager checks the dispatch table and, if your application has installed a handler for the event, calls the handler. Each entry in the Apple event dispatch table should specify:

  • The event class.

  • The event ID.

  • A universal procedure pointer to the Apple event handler.

  • A reference constant.

    The reference constant is passed to your handler by the Apple Event Manager each time your handler is called. Your application can use this reference constant for any purpose. If your application does not use the reference constant, specify 0.

  Accordingly, the parameters for the call to AEInstallEventHandler are the event class, the event ID, a pointer to the event handler, a reference constant, and false.

  false causes the handler to be installed in the application's Apple event dispatch table. true causes the handler to be installed in the system's Apple event dispatch table. The system Apple event dispatch table is a table in the system heap containing handlers that are available to all applications and processes running on the same computer. The handlers in your application's Apple events dispatch table are available only to your application. If AEProcessAppleEvent cannot find a handler for the Apple event in your application's Apple event dispatch table, it looks in the system Apple event dispatch table for a handler. If it does not find a handler in the system table, it returns the errAEEventNotHandled result code.

     OSErr  theEventHandler(AppleEvent *appleEvent,
                                 AppleEvent *reply,
                                 long handlerRefcon);

Apple event handlers must generally perform the following tasks:

• Extract the parameters and attributes from the Apple event.

• Check that all required parameters have been extracted.

• Perform the action requested by the Apple event.

• Dispose of any copies of the descriptor structures that have been created.

• Add information to the reply Apple event if requested.

Data Type Coercion. You can specify the descriptor type in the resulting data from these functions. If this type is different from the descriptor type of the attribute or parameter, the Apple Event Manager attempts to coerce it to the specified type. In the direct parameter of the Open Documents event, for example, each descriptor structure in the descriptor list is an alias structure and each alias structure specifies a document to be opened. All your application usually needs to open a document is a file system specification structure (FSSpec) of the document. When you extract the descriptor structure from the descriptor list, you can request that the Apple Event Manager return the data to your application as a file system specification structure instead of an alias structure.

Checking That All Required Parameters Have Been Retrieved. After extracting all known Apple event parameters, your handler should check that it has retrieved all the parameters that the source application considered to be required. To do this, determine whether the keyMissedKeywordAttr attribute exists. If this attribute does exist, your handler has not retrieved all the required parameters, and it should return an error.

Interacting With the User

• First, the client application must set flags in the sendMode parameter of the AESend function to indicate that user interaction is allowed.

• Second, the server application must either:

  • Set flags to the AESetInterActionAllowed function indicating that user interaction is allowed. (These flags relate to permitting interaction where the client and server are the same application, the client application is on the same computer as the server, or the client is on any computer.)

  • Set no user interaction preferences (that is, make no call to AESetInterActionAllowed ), in which case AEInteractWithUser (the function used to initiate interaction with the user when your application is a server responding to an Apple event) assumes that only interaction with a client on the local computer is allowed.

Your Apple event handler should always set its function result to either noErr, if it successfully handles the Apple event, or to a non-zero result code if an error occurs. If your handler returns a non-zero result code, the Apple Event Manager adds a keyErrorNumber parameter to the reply Apple event. This parameter contains the result code that your handler returns.

Disposing of Copies of Descriptor Structures

• If your application is not open and the user elects to open it from the Finder without opening or printing any documents (either by double clicking the application's icon or by selecting the icon and choosing Open from the Finder's File menu), the Finder launches your application (using the Process Manager) and sends it an Open Application event.

• If your application is already open and the user attempts to "open" it from the Finder (either by double clicking the application's icon or by selecting the icon and choosing Open from the Finder's File menu), the Finder sends your application a Re-open Application event.

  The Re-open Application event was introduced with MAC OS 8 to cater for a situation which could confuse inexperienced users. The specific situation is where the application is open but has no open windows. Because of the absence of a window, the user does not realise that the application is running, attempts to "open" it from the Finder, and then fails to notice the menu bar change. The intention of the Re-open Application event in such circumstances is to cause the application to open a window, providing more obvious visible evidence to the user that the application is, in fact, open.

• If your application is not open and the user elects to open one of your application's documents from the Finder, the Finder launches your application (using the Process Manager) and sends it an Open Documents event.

• If your application is not open and the user elects to print one of your application's documents from the Finder, the Finder launches your application (using the Process Manager) and sends it the Print Documents event. Your application should print the selected documents and remain open until it receives a Quit Application event from the Finder.

• If your application is open and the user elects to open or print any of your application's documents from the Finder, the Finder sends your application the Open Documents or Print Documents event.

• If your application is open and the user chooses Restart or Shut Down from the Finder's Special menu, the Finder sends your application the Quit Application event.

Your application needs to recognise two descriptor types to handle the required Apple events: descriptor lists and alias structures.

As previously stated, in the event of an Open Documents or Print Documents event, you can retrieve the data which specifies the document as an alias structure, or you can request that the Apple Event Manager coerce the alias structure to a file system specification structure. The file system specification provides a standard method of identifying files.

Main Apple Event Manager and Appearance Manager Constants, Data Types, and Functions Relevant to Required Apple Events and Appearance Manager Apple events

kHighLevelEvent = 23

kCoreEventClass       = FOUR_CHAR_CODE('aevt')  // Event class - required Apple events.
KAppearanceEventClass = FOUR_CHAR_CODE('appr')  // Event Class - Appearance Manager 
                                                // Apple events.

kAEOpenApplication   = FOUR_CHAR_CODE('oapp')  // Event ID for Open Application event.
kAEReopenApplication = FOUR_CHAR_CODE('rapp')  // Event ID for Re-open Application Event.
kAEOpenDocuments     = FOUR_CHAR_CODE('odoc')  // Event ID for Open Documents event.
kAEPrintDocuments    = FOUR_CHAR_CODE('pdoc')  // Event ID for Print Documents event.
kAEQuitApplication   = FOUR_CHAR_CODE('quit')  // Event ID for Quit Application event.

kAEAppearanceChanged      = FOUR_CHAR_CODE('thme')  // Appearance changed.
kAESystemFontChanged      = FOUR_CHAR_CODE('sysf')  // System font changed.
KAESmallSystemFontChanged = FOUR_CHAR_CODE('ssfn')  // Small system font changed.
kAEViewsFontChanged       = FOUR_CHAR_CODE('vfnt')  // Views font changed.

keyMissedKeywordAttr = FOUR_CHAR_CODE('miss')  // First required parameter remaining
                                               // in an Apple event.

keyDirectObject = FOUR_CHAR_CODE('----')  // Direct parameter

typeAEList    = FOUR_CHAR_CODE('list')  // List of descriptor structures.
typeWildCard  = FOUR_CHAR_CODE('****')  // Matches any type.
typeFSS       = FOUR_CHAR_CODE('fss ')  // File system specification.

errAEDescNotFound = -1701  // Descriptor structure was not found.
errAEParamMissed  = -1715  // Handler cannot understand a parameter the 
                           // client considers is required.

KThemeSystemFont                 = 0
KThemeSmallSystemFont            = 1
KThemeSmallEmphasizedSystemFont  = 2
KThemeViewsFont                  = 3

typedef FourCharCode  AEEventClass; // Event class for a high level event.
typedef FourCharCode  AEEventID;    // Event ID for a high level event.
typedef FourCharCode  AEKeyword;    // Keyword for a descriptor structure.
typedef ResType       DescType;     // Descriptor type.

typedef AEDesc        AEDescList;   // List of descriptor structures.
typedef AEDescList    AERecord;     // List af keyword-specified descriptor structures.
typedef AERecord      AppleEvent    // List of attributes and parameters for Apple event.

struct AEDesc
{
  DescType descriptorType;  // Type of data being passed.
  Handle   dataHandle;      // Handle to data being passed.
};
typedef struct AEDesc AEDesc;

struct AEKeyDesc	
{
  AEKeyword deskKey;      // Keyword.
  AEDesc    descContent;  // Descriptor structure.
};
typedef struct AEKeyDesc AEKeyDesc;

OSErr  AEInstallEventHandler(AEEventClass theAEEventClass,AEEventID theAEEventID,
       AEEventHandlerUPP handler,long handlerRefcon,Boolean isSysHandler);

OSErr  AEProcessAppleEvent(const EventRecord *theEventRecord);

OSErr  AEGetParamDesc(const AppleEvent *theAppleEvent,AEKeyword theAEKeyword,
       DescType desiredType,AEDesc *result);
OSErr  AEGetAttributePtr(const AppleEvent *theAppleEvent,AEKeyword theAEKeyword,
       DescType desiredType,DescType *typeCode,Ptr dataPtr,Size maximumSize,
       Size *actualSize);

OSErr  AECountItems(const AEDescList *theAEDescList,long *theCount);

OSErr  AEGetNthPtr(const AEDescList *theAEDescList,long index,DescType desiredType,
       AEKeyword *theAEKeyword,DescType *typeCode,Ptr dataPtr,Size maximumSize,
       Size *actualSize);

OSErr  AEDisposeDesc(AEDesc *theAEDesc);

OSStatus  GetThemeFont(ThemeFontID inFontID,ScriptCode inScript,
          StringPtr outFontName,SInt16 *outFontSize, Style *outStyle);
OSStatus  UseThemeFont(ThemeFontID inFontID,ScriptCode inScript);