TweetFollow Us on Twitter

An Introduction to Handlers

Volume Number: 21 (2005)
Issue Number: 2
Column Tag: Programming

AppleScript Essentials

by Benjamin S. Waldie

An Introduction to Handlers

In a previous article, you may remember that we discussed methods of writing AppleScripts to watch folders for incoming items to process. In each of the methods we discussed, we made use of handlers. This month, we are going to explore handlers in more depth. Since handlers are a fairly complex subject, the full scope of handlers will not be covered in this month's article. Rather, we will cover the basics of handlers. In future articles, we will discuss handlers in more detail.

What is a Handler?

A handler is a group of one or more AppleScript statements that are associated with a single command. As we will discuss, some handlers are user defined, and some are application, or system defined.

Once the command associated with a handler is invoked, the statements within that handler will execute. Handlers allow you to group your code into logical "chunks," which may be triggered, or called, over and over again within a script. By carefully constructing your handlers, you can make scripts very modular, giving you the ability to break the scripts apart and reuse the handlers again in future scripts. Many AppleScript developers store their handlers in code libraries. These libraries can then be loaded, and handlers within them can be triggered from other scripts.

Anatomy of a Handler

Let's take a look at a basic handler. The following handler may be used to display a basic dialog message.

on displayDialog()
   display dialog "This is code within a handler."
end displayDialog

Now, let's break handlers down into different parts, and examine how they are constructed.

Handler Definition

A handler definition refers to the handler itself. The following would be considered the handler definition from the previous example.

on displayDialog()
   display dialog "This is code within a handler."
end displayDialog

A handler definition always begins with the word on or to, which indicates to AppleScript that it is the beginning of a handler. In the example above, I chose to begin my handler with the word on. However, the method you choose to use is entirely at your discretion. You should use whichever word looks more acceptable to you.

The next part of the handler definition is the name of the handler, followed by any parameters to be passed to the handler by the script. For example:

displayDialog()

In many cases, you may need to pass information to a handler to be processed. To allow for this, handlers support input parameters. Handlers also have the ability to return data back to the script. For example, a handler may return a true/false value indicating whether or not it was successfully processed.

There are a couple different methods that you can use to specify input parameters, and we will discuss them shortly. In the previous example, the empty parentheses indicate that my handler does not require any parameters.

Following the first line of a handler definition are any AppleScript statements that should be executed by the handler. You may write as few or as many statements as you need, keeping in mind that they will not execute until the handler is called.

The final line of a handler definition always begins with the word end, followed by the name of the handler.

end displayDialog

To save time when writing a handler, you may write the word end, and when you compile your code, the handler name will automatically be inserted for you.

Handler Call

To call a handler from within a script, you must specify the name of the handler, followed by values for all of its parameters. The following is the call for the previous handler example:

displayDialog()

We'll look at calling handlers that use parameters shortly, as we explore parameters.

If you need to call a handler from within an application tell block, you must specify of me after the handler call, to indicate that the handler is to be addressed within the script, and not within the application. For example:

tell application "Finder"
   displayDialog() of me
end tell

Parameters

As previously mentioned, the first line of a handler contains the handler name, followed by any parameters to be passed into the handler. A parameter is a variable that is named in the handler definition, and is assigned a value when the handler is called. When calling a handler, all parameters are required, and must be specified. Handlers do not allow optional parameters.

There are two types of parameters that may follow a handler name - labeled parameters and positional parameters.

Labeled Parameters

Labeled parameters are parameters that are associated with labels in the handler definition. When the handler is called, these labels are used to determine which parameters are which. Therefore, when working with labeled parameters, you may pass the parameters through your handler call in any order you wish, so long as they correspond with the correct labels. The exception to this rule is that, in some cases, you may choose to assign a direct parameter, which is required to fall immediately after the handler name.

There are two ways that you can assign labeled parameters in a handler. The first is to assign the parameters using one of the following predefined labels: about, above, against, apart from, around, aside from, at, below, beneath, beside, between, by, for, from, instead of, into, on, onto, out of, over, since, through, thru, under. The label of may also be used, though only to define a direct parameter. If you add a direct parameter, using the label of, then you are required to have at least one or more additional parameters. The following is an example of a handler with labeled parameters:

to displayDialog of theText above theButtons aside from theIconNumber
   display dialog theText buttons theButtons with icon theIconNumber
end displayDialog

In the example above, the parameter theText is a direct parameter, as indicated by the label of. The parameter theButtons is associated with the label above, and the parameter theIconNumber is associated with the label aside from. The handler above would be called using the following line of code:

displayDialog of "Hello" above {"OK"} aside from 1

Again, since labeled parameters are associated with their labels, then you can rearrange the non-direct parameters, if desired. For example, the following handler call would function identically as the previous one:

displayDialog of "Hello" aside from 1 above {"OK"}

Another way to assign labeled parameters is to use custom labels. This is done by creating label definitions in the format labelName:parameterName, separating them by commas, and preceding them with the label given. Custom labeled parameters must follow any predefined label parameters. An example of a handler with custom labeled parameters is the following:

to displayDialog of theText given someButtons:theButtons, someIconNumber:theIconNumber
   display dialog theText buttons theButtons with icon theIconNumber
end displayDialog

In the example above, the parameter theText is a direct parameter, preceded by a predefined label. The remaining parameters are custom labeled parameters. The parameter theButtons is associated with the custom label someButtons, and the parameter theIconNumber is associated with the custom label someIconNumber. This handler can be called using the following line of code:

displayDialog of "Hello" given someButtons:{"OK"}, someIconNumber:1

Again, since this handler makes use of labeled parameters, the non-direct parameters may be rearranged, if desired:

displayDialog of "Hello" given someIconNumber:1, someButtons:{"OK"}

Positional Parameters

Another type of parameter that you can use when defining a handler is a positional parameter. Positional parameters are separated by commas, and do not contain any labels. Because they do not contain labels, they are identified by their position in the handler definition. Therefore, they must be listed in the same position when the handler is called. The following is an example of a handler that makes use of positional parameters:

on displayDialog(theText, theButtons, theIconNumber)
   display dialog theText buttons theButtons with icon theIconNumber
end displayDialog

The handler above may be called using the following line of code:

displayDialog("Hello", {"OK"}, 1)

Return Value

In some cases, a handler may return a value to the script that called it. This value may be placed into a variable for later usage. By default, a handler will return the result of the last AppleScript statement that executes within the handler, assuming that this statement produces a result. If desired, you may configure your handler to return a different value. For example, the following code returns the name of the button clicked in the dialog.

set theChoice to displayDialog()

on displayDialog()
   display dialog "Would you like to continue processing?" buttons {"Yes", "No"}
   return button returned of result
end displayDialog

Next, I could add additional code at the root level of my script to check the button that was clicked, now stored in a variable called theChoice, and take the appropriate course of action.

Within a handler, you may return a value at any time to cease further execution of that handler, or you may return no value to cease execution without returning a specific value. For example, the following handler will stop processing, returning no value, if the user clicks the "No" button.

displayDialog()

on displayDialog()
   display dialog "Would you like to continue processing?" buttons {"Yes", "No"}
   set theChoice to button returned of result
   if theChoice = "No" then return
   display dialog "Continuing..."
end displayDialog

Types of Handlers

There are two types of handlers in AppleScript - subroutine handlers and command handlers.

Subroutine Handlers

Subroutine handlers are groups of statements, which are defined by the developer, and called throughout a script, or from another script. Subroutines can be extremely useful if you need to perform the same exact task over and over throughout your script. For example, let's say that you need to display an informational dialog to the user 10 times throughout your script to let the user know what is occurring.

display dialog "Beginning next task..." buttons {"*"} 
   default button "*" with icon 1 giving up after 3

To display the above dialog 10 times, I could write out all of this code 10 times - or, I could write a handler 1 time.

on displayNextTaskMessage()
   display dialog "Beginning next task..." buttons {"*"} default 
      button "*" with icon 1 giving up after 3
end displayNextTaskMessage

Once written, this handler can be triggered from anywhere within my script. Rather than writing the entire lengthy line of display dialog code each time I need to display the dialog to the user, I can call my handler instead. The following code would call the displayNextTaskMessage handler.

displayNextTaskMessage()

In the example above, you may be wondering where the handler name "displayNewTaskMessage" came from. This is something that I defined myself when writing the handler. Remember, since subroutine handlers are defined by a developer, their names are user definable. So, I could have named this handler anything I wanted, as long as it was not the name of another existing handler in my script.

Command Handlers

A command handler is a group of statements that is triggered by a specific application or system related event.

Every AppleScript application contains an implied run handler. Any AppleScript statements at the top level of the script, excluding global variables, properties, other handlers, and script objects, fall within that run handler. If you prefer to make the run handler visible in your code, you may wrap these statements within an on run handler call. When the script is run, both methods will behave identically. For example, each of the examples below will perform the exact same function:

Example 1:

display dialog "Hello!"

Example 2:

on run
   display dialog "Hello!"
end run

As you can see, any code within the run handler of a script will be executed whenever the script is run. However, in some cases, you may want to execute code when other types of actions occur within your script.

The open handler may be used to initiate specific code when items are dragged and dropped onto a script in the Finder. For example:

on open theDroppedItems
   -- Process the items
end open

By adding an open handler into a script, and then saving that script as an application, the script will automatically accept dropped files and folders. It will also receive a new icon, indicating that it is now a drop script.

In the previous example code, the parameter theDroppedItems will contain a list of paths to any items dropped onto the script. If you want your script to only process folders, then you would need to add custom code within the open handler to determine which dropped items were folders, and process only these items.

Two other types of command handlers that may be added to an AppleScript application are the idle handler and the quit handler.

An idle handler is particularly useful when creating stay open AppleScript applications. In a stay open AppleScript application, by default, AppleScript will send the script an idle command every 30 seconds. At that time, any code within the idle handler will execute. For example, if I save the following code as a stay opened AppleScript application, and trigger it, the script will beep every 30 seconds:

on idle
   beep
end idle

Though the default time period between idle messages is 30 seconds, I can change this behavior if desired, by returning an integer value indicating how many seconds of a delay should occur before the next idle. In the following example, the script would beep every 10 seconds.

on idle
   beep
   return 10
end idle

The quit handler may be used in order to execute code when the script quits, whether manually quit by the user or not.

on quit
   display dialog "Task complete."
end quit

Example Handlers

Now that we have covered the basics of handlers, let's take a look at some example handlers, which may be useful to you as you write scripts in the future. Each of these handlers has been written generically, so that you can use it in virtually any script in the future.

The following handler will make a new folder in a specified output folder, using a specified name:

on makeNewFolder(theNewFolderName, theOutputFolder)
   tell application "Finder" to make new folder at folder theOutputFolder with properties 
      {name:theNewFolderName}
end makeNewFolder

The following handler will delete a folder of a file:

on moveItemToTrash(theItemPath)
   tell application "Finder" to delete item theItemPath
end moveItemToTrash

The following handler will mount an afp volume:

on mountVolume(theVolumeName, theServerIPAddress, theUserName, thePassword)
   mount volume "afp://" & theUserName & ":" & thePassword & "@" & theServerIPAddress 
      & "/" & theVolumeName as string
end mountVolume

In Closing

Again, handlers are a fairly complex aspect of AppleScript development for many users. Today, I use them regularly, and I try to make them as modular as possible. My theory is that if I write code to perform a specific task, such as opening a document in QuarkXPress, then I don't want to ever write that code again. Rather, I store the handler for later usage in future scripts, and the next time I need to perform the task, which could be a year down the line, I simply add the handler into my new script.

I encourage you to begin using handlers more in your scripting, as it will benefit you greatly. We'll discuss other aspects of handlers in more detail in future articles. In the meantime, for additional information about handlers, you may want to check out an AppleScript book, or browse the AppleScript Language Guide at <http://developer.apple.com/documentation/AppleScript/>.

Until next time, keep scripting!


Benjamin Waldie is president of Automated Workflows, LLC, a firm specializing in AppleScript and workflow automation consulting. In addition to his role as a consultant, Benjamin is an evangelist of AppleScript, and can frequently be seen presenting at Macintosh User Groups, Seybold Seminars, and MacWorld. For additional information about Benjamin, please visit http://www.automatedworkflows.com, or email Benjamin at applescriptguru@mac.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Minecraft 1.20.2 - Popular sandbox build...
Minecraft allows players to build constructions out of textured cubes in a 3D procedurally generated world. Other activities in the game include exploration, gathering resources, crafting, and combat... Read more
HoudahSpot 6.4.1 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot is a productivity tool. It is the hub where all the... Read more
coconutBattery 3.9.14 - Displays info ab...
With coconutBattery you're always aware of your current battery health. It shows you live information about your battery such as how often it was charged and how is the current maximum capacity in... Read more
Keynote 13.2 - Apple's presentation...
Easily create gorgeous presentations with the all-new Keynote, featuring powerful yet easy-to-use tools and dazzling effects that will make you a very hard act to follow. The Theme Chooser lets you... Read more
Apple Pages 13.2 - Apple's word pro...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more
Numbers 13.2 - Apple's spreadsheet...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Ableton Live 11.3.11 - Record music usin...
Ableton Live lets you create and record music on your Mac. Use digital instruments, pre-recorded sounds, and sampled loops to arrange, produce, and perform your music like never before. Ableton Live... Read more
Affinity Photo 2.2.0 - Digital editing f...
Affinity Photo - redefines the boundaries for professional photo editing software for the Mac. With a meticulous focus on workflow it offers sophisticated tools for enhancing, editing and retouching... Read more
SpamSieve 3.0 - Robust spam filter for m...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
WhatsApp 2.2338.12 - Desktop client for...
WhatsApp is the desktop client for WhatsApp Messenger, a cross-platform mobile messaging app which allows you to exchange messages without having to pay for SMS. WhatsApp Messenger is available for... Read more

Latest Forum Discussions

See All

‘Resident Evil 4’ Remake Pre-Orders Are...
Over the weekend, Capcom revealed the Japanese price points for both upcoming iOS and iPadOS ports of Resident Evil Village and Resident Evil 4 Remake , in addition to confirming the release date for Resident Evil Village. Since then, pre-orders... | Read more »
Square Enix commemorates one of its grea...
One of the most criminally underused properties in the Square Enix roster is undoubtedly Parasite Eve, a fantastic fusion of Resident Evil and Final Fantasy that deserved far more than two PlayStation One Games and a PSP follow-up. Now, however,... | Read more »
Resident Evil Village for iPhone 15 Pro...
During its TGS 2023 stream, Capcom showcased the Following upcoming ports revealed during the Apple iPhone 15 event. Capcom also announced pricing for the mobile (and macOS in the case of the former) ports of Resident Evil 4 Remake and Resident Evil... | Read more »
The iPhone 15 Episode – The TouchArcade...
After a 3 week hiatus The TouchArcade Show returns with another action-packed episode! Well, maybe not so much “action-packed" as it is “packed with talk about the iPhone 15 Pro". Eli, being in a time zone 3 hours ahead of me, as well as being smart... | Read more »
TouchArcade Game of the Week: ‘DERE Veng...
Developer Appsir Games have been putting out genre-defying titles on mobile (and other platforms) for a number of years now, and this week marks the release of their magnum opus DERE Vengeance which has been many years in the making. In fact, if the... | Read more »
SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 22nd, 2023. I’ve had a good night’s sleep, and though my body aches down to the last bit of sinew and meat, I’m at least thinking straight again. We’ve got a lot to look at... | Read more »
TGS 2023: Level-5 Celebrates 25 Years Wi...
Back when I first started covering the Tokyo Game Show for TouchArcade, prolific RPG producer Level-5 could always be counted on for a fairly big booth with a blend of mobile and console games on offer. At recent shows, the company’s presence has... | Read more »
TGS 2023: ‘Final Fantasy’ & ‘Dragon...
Square Enix usually has one of the bigger, more attention-grabbing booths at the Tokyo Game Show, and this year was no different in that sense. The line-ups to play pretty much anything there were among the lengthiest of the show, and there were... | Read more »
Valve Says To Not Expect a Faster Steam...
With the big 20% off discount for the Steam Deck available to celebrate Steam’s 20th anniversary, Valve had a good presence at TGS 2023 with interviews and more. | Read more »
‘Honkai Impact 3rd Part 2’ Revealed at T...
At TGS 2023, HoYoverse had a big presence with new trailers for the usual suspects, but I didn’t expect a big announcement for Honkai Impact 3rd (Free). | Read more »

Price Scanner via MacPrices.net

New low price: 13″ M2 MacBook Pro for $1049,...
Amazon has the Space Gray 13″ MacBook Pro with an Apple M2 CPU and 256GB of storage in stock and on sale today for $250 off MSRP. Their price is the lowest we’ve seen for this configuration from any... Read more
Apple AirPods 2 with USB-C now in stock and o...
Amazon has Apple’s 2023 AirPods Pro with USB-C now in stock and on sale for $199.99 including free shipping. Their price is $50 off MSRP, and it’s currently the lowest price available for new AirPods... Read more
New low prices: Apple’s 15″ M2 MacBook Airs w...
Amazon has 15″ MacBook Airs with M2 CPUs and 512GB of storage in stock and on sale for $1249 shipped. That’s $250 off Apple’s MSRP, and it’s the lowest price available for these M2-powered MacBook... Read more
New low price: Clearance 16″ Apple MacBook Pr...
B&H Photo has clearance 16″ M1 Max MacBook Pros, 10-core CPU/32-core GPU/1TB SSD/Space Gray or Silver, in stock today for $2399 including free 1-2 day delivery to most US addresses. Their price... Read more
Switch to Red Pocket Mobile and get a new iPh...
Red Pocket Mobile has new Apple iPhone 15 and 15 Pro models on sale for $300 off MSRP when you switch and open up a new line of service. Red Pocket Mobile is a nationwide service using all the major... Read more
Apple continues to offer a $350 discount on 2...
Apple has Studio Display models available in their Certified Refurbished store for up to $350 off MSRP. Each display comes with Apple’s one-year warranty, with new glass and a case, and ships free.... Read more
Apple’s 16-inch MacBook Pros with M2 Pro CPUs...
Amazon is offering a $250 discount on new Apple 16-inch M2 Pro MacBook Pros for a limited time. Their prices are currently the lowest available for these models from any Apple retailer: – 16″ MacBook... Read more
Closeout Sale: Apple Watch Ultra with Green A...
Adorama haș the Apple Watch Ultra with a Green Alpine Loop on clearance sale for $699 including free shipping. Their price is $100 off original MSRP, and it’s the lowest price we’ve seen for an Apple... Read more
Use this promo code at Verizon to take $150 o...
Verizon is offering a $150 discount on cellular-capable Apple Watch Series 9 and Ultra 2 models for a limited time. Use code WATCH150 at checkout to take advantage of this offer. The fine print: “Up... Read more
New low price: Apple’s 10th generation iPads...
B&H Photo has the 10th generation 64GB WiFi iPad (Blue and Silver colors) in stock and on sale for $379 for a limited time. B&H’s price is $70 off Apple’s MSRP, and it’s the lowest price... Read more

Jobs Board

Housekeeper, *Apple* Valley Villa - Cassia...
Apple Valley Villa, part of a 4-star senior living community, is hiring entry-level Full-Time Housekeepers to join our team! We will train you for this position and Read more
Housekeeper, *Apple* Valley Village - Cassi...
Apple Valley Village Health Care Center, a 4-star rated senior care campus, is hiring a Part-Time Housekeeper to join our team! We will train you for this position! Read more
Optometrist- *Apple* Valley, CA- Target Opt...
Optometrist- Apple Valley, CA- Target Optical Date: Sep 23, 2023 Brand: Target Optical Location: Apple Valley, CA, US, 92308 **Requisition ID:** 796045 At Target Read more
Senior *Apple* iOS CNO Developer (Onsite) -...
…Offense and Defense Experts (CODEX) is in need of smart, motivated and self-driven Apple iOS CNO Developers to join our team to solve real-time cyber challenges. Read more
*Apple* Systems Administrator - JAMF - Activ...
…**Public Trust/Other Required:** None **Job Family:** Systems Administration **Skills:** Apple Platforms,Computer Servers,Jamf Pro **Experience:** 3 + years of Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.