Responding to AppleEvents

Symbolic AppleEvent Handlers

JavaScript OSA allows you to declare functions that are called in response to AppleEvents. The name of the function must match the name of the AppleEvent. AppleEvent names are taken from the host application's AppleEvent dictionary. In the case of applications that do not have their own dictionaries (the Script Editor, applets and droplets), AppleScript's system dictionary is used which defines the core AppleEvents, (open, idle, print, quit).

More documentation on this to come later. In the meantime, checkout the contents of the ":Samples:MacOS AppleEvent Handlers:" folder for examples of symbolic AppleEvent handlers.

Subroutine AppleEvent Handlers

AppleScript provides a facility for calling handlers in one running script form another. JavaScript OSA allows you to declare functions that can be called from another running AppleScript script. To do so, simply declare a function in JavaScript:

From AppleScript, you can then do the following:

It is important to note that, internally, AppleScript converts all identifiers to lowercase. If you want to invoke a JavaScript function with a mixed case name, you must use AppleScript's pipe syntax to define the handler name (e.g. |myHandler|).

Raw AppleEvent Handlers

If there is no dictionary definition available for the AppleEvent you want to handle, you can define a raw AppleEvent handler. The syntax of a raw AppleEvent handler function is as follows:

Where XXXX is the suite ID and YYYY is the event ID of the AppleEvent you want to respond to. For instance, here is a simple Open AppleEvent handler:

Note that the Params parameter is a JavaScript object containing properties corresponding to each parameter appearing in the AppleEvent. These properties are named "ae_ZZZZ" where ZZZZ is the parameter's 4-character ID.

If you wish, you may return a value from the handler, and this value will be returned to the application that sent you the AppleEvent.

Initializing AppleEvent Handlers

If the 4-character codes associated with your AppleEvent handler are non-printable, and thus cannot be used to create a valid JavaScript function name, you can use a special function called OSAInit to install your handlers.

The OSAInit function is invoked by JavaScript OSA before your script responds to an AppleEvent. You can use it to initialize your script.

To register handlers for AppleEvents, you can do the following:

Resuming AppleEvents

JavaScript OSA also allows you to resume (continue in AppleScript terms) AppleEvents. Continuing an AppleEvent allows the event you are processing to be passed on to the host application running your JavaScript script for processing. You may choose to modify the AppleEvent before passing it on for further processing.

AppleEvents are resumed using the MacOS.aeResume function.