Handlers that you define freely in code are user handlers. But there are also handlers whose definition comes from the dictionary of some scripting addition or application. These are event handlers (a command defined in a dictionary is technically called an event, because it is actually an Apple event, as discussed in Chapter 3).
An event handler 's parameter syntax is a little different from that of a user handler :
The handler takes no parentheses.
The first parameter (the direct object) simply follows the handler name directly, without parentheses.
Subsequent parameters are labeled. Labeled parameters are the same as prepositional parameters, but the labels are not limited to the list in Table 9-1; basically, the dictionary can define any labels it likes.
Also, the name of the command, and any of the labels, can consist of multiple words .
An event handler is often used in connection with an automatic location (Chapter 2). Some application is going to send a message to your script, and it has defined what that message will be. To receive the message, your script must contain an event handler with a matching definition. The event handler is an entry point to your script.
Take, for example, folder actions (Chapter 26). You can attach a script to a folder as a folder action, so your script is called (by the System Events application) when certain things happen in the Finder. Let's say you want your script to be called when files are put into that folder. Then your script must contain an event handler with this structure:
on adding folder items to ff after receiving L
-- code goes here
end adding folder items toThe event here is called adding folder items to. It takes two parameters: the direct object, and a parameter whose label is after receiving. I've called the direct object ff and the second parameter L, but these handler variable names are up to you.
Similarly, in AppleScript Studio, let's say you want your script to be notified when the user clicks a button in the interface. Then your script will contain an event handler with this structure:
on clicked theObject
-- code goes here
end clickedThat's an event called clicked taking one parameter, the direct object. The name of the direct object in the handler definition, theObject, is up to you.
The syntax of event handlers
is possible because the script is compiled in the presence of a dictionary
that defines the event. The adding folder items to event is defined in the StandardAdditions scripting addition, and a scripting addition's dictionary is always visible. The clicked event is defined in the AppleScriptKit dictionary
; this dictionary is not always visible, but it is visible when you're editing and compiling AppleScript Studio code.
Interestingly, your code can call an event handler. This is legal (but silly):
on adding folder items to ff after receiving L
display dialog ff & space & L
end adding folder items to
adding folder items to "howdy" after receiving "there"Most applications that want an entry point to your script do not use event handlers. The reason is that they have no way to make a dictionary visible at the time you're editing and compiling your script. Apple Computer installs the StandardAdditions scripting addition by default on every machine, so it can use this scripting addition to define events used by the System Events application as entry points for folder actions. And AppleScript Studio works in a special way, where the AppleScriptKit dictionary is automatically visible while you're editing your code. But third-party scriptable applications can't make their dictionary automatically visible, and they can't usually expect you to install a scripting addition just in order to be able to use their event handler terminology. Typically they resort to a user handler instead. (See Chapter 26 for examples.)
By the way, built-in AppleScript commands are visible at all times, so you can write event handlers for them. That is how the explicit run handler
works (see the next section); for another example, see "Handler Calls, Commands, and Script Objects" in Chapter 8. (The commands get, copy, and set work differently; you can't write handlers for them—the compiler will stop you if you so much as try it.)