Determining If an Application Is Receiving Apple Events

The easiest way to determine if your application is receiving a particular event is to set a breakpoint in the event handler for that event, then send an event of that type to your application. There are several ways to send Apple events to your application:

• You can create and send events that target your application from within the application itself or from a test application. For more information, see Creating and Sending Apple Events. This approach can be useful if you’re setting up a test suite and want to thoroughly test how your application responds to a variety of events.

• You can use Script Editor to send Apple events to your application.

  For example, you can execute this one-line script to send your application a quit event:

  
  
  

  Listing 8-1  A simple script to quit an application

  tell app "MyApplication" to quit

  If your application is scriptable, you may prefer to set up a test suite of scripts to thoroughly exercise the events you support, rather than perform the same task in a test application.

  For additional information on sending Apple events with Script Editor, see Script Editor is an Apple Event Test Tool.

• You can use the Mac OS to send Apple events to your application.

  For example, you can select an application document in the Finder and double-click it to send an open documents event to the application. See Handling Apple Events Sent by the Mac OS for a list of the events the Mac OS sends to applications.

What if you’re sending events to your application, but the debugger never reaches the breakpoints you set in your Apple event code? One simple approach is to install a single Apple event handler with the event type and event class set to typeWildCard. Any Apple event your application receives will be dispatched to this handler, so a breakpoint in the handler should allow you to verify whether the application is actually receiving events.

Once you know your application is receiving events, you can take a closer look at the events using the information provided in Examining Apple Events. That information is also useful if you never hit the breakpoint in your wildcard handler. For example, you can examine the test events you are sending to see if they correctly target your application.

Script Editor is an Apple Event Test Tool

The Script Editor application, located in /Applications/AppleScript, is a useful tool for working with Apple events. If your application is scriptable, you can use Script Editor to write and execute scripts that target your application, resulting in Apple events being sent to the application.

Even if your application is not fully scriptable, you can use Script Editor to send it events such as the open application and quit events that your application usually receives from the Mac OS. Listing 8-1 shows an example of this.

In addition, you can use Script Editor to construct and send Apple events using raw format, in which you enclose actual four-character codes in special characters to specify an event. For example, Listing 8-2 shows how to use the raw format to send an open location command to the Safari application and open the specified web page.

Listing 8-2  Sending a raw event to open an URL

tell application "Safari"

    «event GURLGURL» "http://www.apple.com/"

end tell

When you compile this script, Script Editor examines Safari’s scripting dictionary and converts the second line to this:

    open location "http://www.apple.com/"

However, for an application that doesn’t have a scripting dictionary, the raw code is not replaced by an equivalent term, but the Apple event can still be sent and understood (if the application supports it).

You enter the special characters that surround the raw code (called double angle brackets or guillemets) by typing Option-\ and Option-Shift-\. For additional information, see Double Angle Brackets in Results and Scripts in AppleScript Language Guide.

Turning on Apple Event Logging shows how you can examine the Apple events Script Editor sends and receives.

Examining Apple Events

There are several available mechanisms for examining the contents of Apple events that your application sends and receives.

%setenv AEDebugSends 1; setenv AEDebugReceives 1

%export AEDebugSends=1; export AEDebugReceives=1

% /Applications/AppleScript/Script\ Editor.app/Contents/MacOS/Script\ Editor

% /System/Library/CoreServices/Finder.app/Contents/MacOS/Finder

AE2000 (968): Received an event:

------oo start of event oo------

{ 1 } 'aevt':  aevt/rapp (ppc ){

          return id: 22609967 (0x159002f)

     transaction id: 0 (0x0)

  interaction level: 112 (0x70)

     reply required: 0 (0x0)

             remote: 0 (0x0)

  target:

    { 1 } 'psn ':  8 bytes {

      { 0x0, 0x60001 } (Dock)

    }

  optional attributes:

    { 1 } 'reco':  - 1 items {

      key 'optk' -

        { 1 } 'list':  - 1 elements {

          { 1 } 'keyw':  4 bytes {

            'frnt'

          }

        }

    }

  event data:

    { 1 } 'aevt':  - 1 items {

      key 'frnt' -

        { 1 } 'bool':  1 bytes {

          false

        }

    }

}

------oo  end of event  oo------