AppleScript_ The Definitive Guide - Matt Neuburg [84]
Named Parameters
Named parameters are a way to take advantage of labeled parameters while escaping the circumscribed repertoire of built-in prepositions (Table 9-1). With named parameters, you get to make up your own labels, though of course you mustn't use a word that's already reserved by the language for something else.
You may combine named parameters with prepositional parameters; if you do, the named parameters must come after the prepositional parameters.
The syntax for defining named parameters is colon-based—the name of the parameter is followed by a colon, which is followed by the name of the handler variable:
on handlerName ... given paramName1:varName1, paramName2:varName2, ...
The first ellipsis in that syntax schema is the definition for the prepositional parameters, if there are any. The second ellipsis is for as many further named parameters as you like.
The call works just the same way: the keyword given must appear, it must appear after all prepositional parameters if there are any, and the same colon-based syntax is used. The named parameters may appear in any order:
handlerName ... given paramName1:value1, paramName2:value2, ...
As with prepositional parameters, boolean values can be passed using with or without and the parameter name, and for these there is no need to say given. Multiple with parameters or without parameters can be joined by using and. Again, AppleScript will use this syntax for you if you pass the literal value true or false.
Here are some examples of handlers with named parameters, and calls to them.
on sum given theOne:x, theOther:y
return x + y
end sum
display dialog (sum given theOther:2, theOne:3)
on scout given loyal:loyal, trustworthy:trustworthy
if loyal and trustworthy then
return "eagle"
else
return "sparrow"
end if
end scout
display dialog (scout with loyal and trustworthy)
on area of side1 beside side2 given measure:m
return ((side1 * side2) as string) & space & m
end area
area of 4 beside 5 given measure:"inches" -- "20 inches"
The first example demonstrates that the order of parameters in the call is free. The second example demonstrates the use of with, and also shows that the parameter labels can be the same as the local variable names. The third examples shows prepositional and named parameters used together.
Event Handlers
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 :
No parameters
The handler takes no parentheses.
First parameter
The first parameter (the direct object) simply follows the handler name directly, without parentheses.
Subsequent parameters
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