TweetFollow Us on Twitter

Script App Example
Volume Number:9
Issue Number:8
Column Tag:Scripting

Related Info: Apple Event Mgr

AppleScript Script Applications

An example of an AppleScript application

By Jens Alfke, Apple Computer, Inc.

Note: Source code files and sample scripts accompanying this article are located on MacTech CD-ROM or source code disks.

About the author

Jens Alfke is a member of the AppleScript engineering team at Apple Computer, where he works on the script editor, the script application framework, and the OSA component API. He would like to thank a lot of obscure, alienated British musicians whose guitar noise made his accomplishments possible and bearable.

Figure 1: Two script applications; one droppable, one not

Introduction

The Script Editor that comes with AppleScript™ allows you to save scripts as tiny applications. By “tiny” I mean really tiny: a base size of less than 2k, plus the data size of the script and its description text. A small but useful script application might weigh in at about 8k. (For the curious: the actual code that runs the applications lives as a component in the AppleScript extension. Each script app just has a stub that dynamically links in the real code.)

In the simplest case, the script runs when the application is launched - whether by a double-click, Apple menu choice, or by being in the Startup Items folder - and then the application immediately quits. You can also make script applications that can have file, folder or disk icons dropped on them and then operate on those items. But much more is possible! This article describes:

• How script applications handle Apple events

• Stay-open applications

• Using quit handlers to override the Quit command

• How to write a script server that can handle many different incoming events, even over the network, and how to call it from another application or script

• How to use script properties to store persistent data

• Periodic actions and script agents (sorry, no bow-ties yet)

Theory of Operation

All Apple® Events sent to a script application are funneled through its script. Every “on ” handler in the script intercepts a particular Apple event and its parameters, and can do anything it wants to in response to that event.

The most basic use of this is to intercept the events that the System 7 Finder® sends to an application when it’s launched. These events are “run” and “open”. (Their internal codes are 'oapp' and 'odoc'.) These are described in the next two sections

“on run” Handlers

The run event is sent to an application when it is launched without any items to open. This happens when the application is not already running, and:

• You double-click the application;

• The application is in the Apple Menu Items folder, and you choose it from the Apple menu;

• The application is in the Startup Items folder, and you restart your Macintosh;

• or some third-party application or launcher utility (such as Magnet™ or OnCue™) launches the script application.

(If the script application was already running when one of these actions occurs, it will be brought to the front, but no events will be sent to it.)

If the script in the script application has an “on run” handler, the handler will intercept the event, and the commands in that handler will run when the application is launched. (If the script has statements that are not part of any handler - not enclosed between “on ” and “end ”, in other words - those statements are an implicit run handler. Thus a script with no handlers at all is really an “on run” handler.)

There is actually one thing that happens first: if the application is supposed to display a startup screen (if “Never Show Startup Screen” was not checked when the application was created, and the user has not disabled the startup screen) then the startup screen will be displayed first. The user must then press the Run button or the Return key before the script’s run handler will be called. This is done so the user has a chance to read the description of the script and decide whether to proceed before running the script.

“on open” Handlers

The open event is sent to an application when Finder icons (whether documents, folders or disks) are dragged onto the application’s icon and dropped there. Unlike the run event, the open event is sent even if the application was already running.

If the script in the script application has an “on open” handler, the commands in that handler will run when items are dropped on the application’s icon. The open handler takes a single parameter; when the handler is called, the value of that parameter is a list of all the items that were dropped. (Each item of the list is an alias; you can convert it to a path name by using “as string”.)

The files, folders or disks are not moved, copied or affected in any way by being dragged onto the application. The Finder just makes a list of their identities and sends that list to the script. Of course, your script could easily use the finderLib script library to tell the Finder to move, copy or otherwise affect the items. That's up to you.

Stay-Open Script Applications

By default, a script application processes one event and then quits. This allows it to perform a single task and then get out of your way. On the other hand, a stay-open script application (one that was saved with the “Stay Open” box checked in the Script Editor save dialog) will stay open once it’s launched and not quit until told to. This has several major uses:

• It's faster for the application to stay around than it is for it to launch and quit every time you drop something on it. If you have a “drop box” that you use very frequently, you might want to make it stay-open.

• Other applications or scripts can send it events other than “run” and “open”, and the script can include handlers that will be triggered by those events. This makes the application into a script server.

• The script can perform periodic actions, even in the background, as long as the application is running.

On the other hand, if your script performs its main function in a run handler (i.e., when the application is launched) it won’t make much sense for the app to stay open, since subsequent double-clicks won’t invoke the run handler.

Script Servers

A script can include any number of handlers for any number of events, as described in the AppleScript Language Reference Manual. Any handler in a script application’s script can be called by another script or another application that can send Apple events.

For example, let’s make a simple script:

/* 1 */

on foobar( message )
 display dialog "Foobar received: " & message
end foobar

We’ll save this as a script application under the name of “Foobar App”, making sure to check “Stay Open” and “Never Show Startup Screen” in the Save As dialog. Now we can write a script to talk to this app:

/* 2 */

tell app "Foobar App" to foobar("Greetings!")

If you run this script (saved as an app, or directly from the script editor) it’ll send a foobar event to “Foobar App”, which will catch the event and display a dialog. (If Foobar App isn’t running the first time you run the script that calls it, AppleScript may put up a standard-file dialog asking you to locate the app.)

Since Apple events can be sent across an AppleTalk network, the client (caller) and server scripts don’t even have to be on the same computer! The remote version of the calling script might look like:

/* 3 */

tell app "Foobar App" of machine "Jens’ Mac" of zone "Scripters"
 foobar("Greetings!")
end tell

Handling Quit Events

By including an “on quit” handler in your script, you can catch the quit event (sent when the user chooses the Quit menu command or presses Command-Q) before the application itself handles it and quits. The commands in the handler could set script properties, tell another application to do something, or display a dialog. The handler can decide whether or not the application should quit by choosing whether to continue the quit. If the handler calls “continue quit”, the application's default quit behavior will be invoked and the application will in fact quit. If the quit handler returns without continuing the quit event, the application will not quit. Here's a handler that checks with the user before quitting:

/* 4 */

on quit
 display dialog "Really quit?" buttons {"No", "Quit"} default button 
"Quit"
 if the button returned of the result is "Quit" then
 continue quit
 end if
 -- If I don't continue the quit, the app will keep running.
end quit

Important: It's possible, through some bug in the quit handler, that it never continues the quit event, making it impossible to quit the application. (For instance, if the handler gets an error before it can call “continue quit”, quitting the application will just produce an error alert without quitting!) As a last resort, use the Emergency Quit command: press Command-Shift-Q, or hold down the Shift key while choosing the Quit menu command. This will immediately quit the application without calling the quit handler.

Persistent data

As described in the Language Reference Manual, AppleScript scripts can have properties. A script property is a variable that can be accessed by any handler in the script, and whose value is stored as part of the script. (By contrast, a regular local variable belongs only to the handler in which it’s declared, and its value is lost as soon as the handler finishes.) A property is declared like so:

property name : initialValue

When a script application quits, the script is saved back to disk if any of its properties were modified. (This happens even if you do an emergency quit via Cmd-Shift-Q.) This makes properties persistent. A property will retain its value until the script changes it, even if you quit the app, reboot or make copies of the script.

All this makes properties extremely useful. Every script application can store its own preferences and other persistent data inside itself, without having to create a separate preference file or contend for space in a central database. The “Folder Watcher” agent shown in the next section makes use of this to remember the modification date of a folder, so it can warn the user when the folder is next modified.

One caveat: when a script is recompiled, the values of all its properties are reset to the initial values specified in the script text.

“on idle” Handlers and Agents

A stay-open script application is sent periodic “idle” events whenever it's running but not processing an incoming event, and can catch them with an “on idle” handler. The commands in that handler will then be run periodically (every 30 seconds, by default.) For instance, if the script includes:

/* 5 */

on idle
 beep
end idle

then the script application, when run, will beep every 30 seconds. To change the rate, return the number of seconds to wait as the result of the script:

/* 6 */

-- This script will beep every 5 seconds.
on idle
 beep
 return 5
end idle

In other words, if the handler returns a positive number, that number becomes the rate (in seconds) at which the idle handler is called. If the result of the handler is a non-numeric value, or less than or equal to zero, the rate will not be changed.

Be careful! The result returned from a handler is just the result of the last statement, even if it doesn't explicitly say “return”. For instance, the following handler will (probably unintentionally) be called only every fifteen minutes:

/* 7 */

on idle
 set x to 30
 beep
 set x to x * x -- BAD! The result (900) will be returned from the handler
end idle

If you want to be sure you're not changing the idle rate, just return zero.

A Simple Agent: Folder Watcher

Here’s a very simple example of an agent: a background task that watches for an interesting situation and then does something in response. This particular agent wakes up every few seconds and checks the modification date of a particular folder (whose path you hard-code into the targetPath property.) If the mod date has changed since it last checked, which means that files have been added to or removed from the folder, it calls the folderChanged function. As shown here it just beeps, but you can add anything you like.

/* 8 */

-- Folder Watcher, a simple agent example
property targetPath : “sneJ:Shared Folders:Jens Public:Drop Box:” -- 
path to target folder

property targetFolder : 0 -- target folder alias (set at startup)
property modDate : 0 -- mod date of folder when last checked

on run
 set targetFolder to alias targetPath -- get alias to the folder
end run

on idle
 set newModDate to modification date of (info for targetFolder)
 if modDate = 0 or newModDate > modDate then
 set modDate to newModDate
 folderChanged(targetFolder)
 end if
 return 3 -- Idle time in seconds
end idle

on folderChanged(f)
 beep
 -- Put anything you want here, and it'll run whenever the
 -- folder is modified. See the “What's New?” sample script 
 -- for a more sophisticated example,  which figures out what 
 -- files have been added and displays their names to the 
 -- user.
end folderChanged

Edit the first line to point to the folder of your choice, save the script as a stay-open application, and run it. The script will now beep every time you drag files into or out of the folder. I find this very useful for a drop-box folder on my disk that’s being shared on the network. Whenever someone connects to it and drops files in, my agent notifies me. It’s almost an e-mail system!

This script application doesn’t cause any noticeable system slowdown. Checking the modification date of a folder is extremely fast; the idle handler in this script runs in the blink of an eye. If you’re really worried, you could slow down the idle rate to once a minute.

Script applications that are launched but not doing anything - just waiting for an event, or for their idle time to come round - take up zero CPU time. The entire process just goes to sleep until woken up by the Process Manager or Event Manager.

Some more powerful agent scripts can be found in the “Sample Scripts” folder of the AppleScript Runtime or Software Development Kit; look in the “Finder Agents” sub-folder.

Some Gotchas

Calling Non-Stay-Open Scripts

There are, unfortunately, a few subtleties having to do with sending events to non-stay-open applications. Here’s the deal:

When AppleScript launches an application as a result of a “tell application ” statement, it first sends the application a run event. (Actually, this is standard behavior for the Macintosh OS. All applications get a run event when launched, in response to which they usually open a new untitled document.) This is normally a good thing, since you can put initialization code in your run handler and be assured that it'll run whenever the application is launched.

However, this does make it difficult to run a non-stay-open script application. The natural way to do it would be:

/* 9 */

tell application "non stay open" to run

Here's what goes wrong: The tell command launches the script application and sends it an implicit run event. The application handles that run event. AppleScript then gets to the explicit run statement in the calling script, and tries to send another run event to the script application. Unfortunately, the application has already handled its one event and quits without responding to the second run. The calling script will wait in vain until it times out, and then get an error.

The culprit in this sad history is the implicit run event sent by the tell statement when it launched the application. AppleScript has to send this event to remain compatible with applications that expect to get this event when they're launched, but we did provide a way around it for special purposes like calling non-stay-open script applications. There is a launch command that explicitly launches an application without sending it a run event. (If the application was already running, the launch command does nothing.)

So the proper way to run a non-stay-open script application is:

/* 10 */

launch application "non stay open" -- Launches, but sends no event
run application "non stay open" -- sends the run event then quits

The launch command launches the application without sending it an event. The run command then sends the run event, and the application will process the event, send back its reply, and quit.

Re-Entrancy Issues

A script application handles incoming events even if it is already running a handler in response to a previous event. This means that execution of a handler can be interrupted while another handler is run, a state known as re-entrancy. However, script applications are not multi-tasking, so two things will never be happening at the same time. The first flow of control halts until the second one finishes.

This can cause problems if both flows of control modify the same script property, or both send commands to an application to modify its data. AppleScript 1.0 does not have multi-tasking facilities (like semaphores or critical-sections) to deal with these issues, so be careful. You might try declaring a “busy” property in your script and setting it to true during critical operations as a crude form of semaphore.

Conclusion

AppleScript script applications offer a lot more than just “a script that runs when you double-click it.” While a real interface builder is still needed (don’t worry, it’s in the works) you can easily build some pretty powerful gizmos - network-visible servers and services, user agents - with the current framework. Go for it!

 
AAPL
$95.60
Apple Inc.
-2.55
MSFT
$43.16
Microsoft Corpora
-0.42
GOOG
$571.60
Google Inc.
-15.82

MacTech Search:
Community Search:

Software Updates via MacUpdate

OneNote 15.2 - Free digital notebook fro...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that’s too important to forget. Whether you’re at... Read more
iStat Menus 4.22 - Monitor your system r...
iStat Menus lets you monitor your system right from the menubar. Included are 8 menu extras that let you monitor every aspect of your system. Some features: CPU -- Monitor cpu usage. 7 display... Read more
Ember 1.8 - Versatile digital scrapbook....
Ember (formerly LittleSnapper) is your digital scrapbook of things that inspire you: websites, photos, apps or other things. Just drag in images that you want to keep, organize them into relevant... Read more
OmniPlan 2.3.6 - Robust project manageme...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Command-C 1.1.1 - Clipboard sharing tool...
Command-C is a revolutionary app which makes easy to share your clipboard between iOS and OS X using your local WiFi network, even if the app is not currently opened. Copy anything (text, pictures,... Read more
Knock 1.1.7 - Unlock your Mac by knockin...
Knock is a faster, safer way to sign in. You keep your iPhone with you all the time. Now you can use it as a password. You never have to open the app -- just knock on your phone twice, even when it's... Read more
Mellel 3.3.6 - Powerful word processor w...
Mellel is the leading word processor for OS X and has been widely considered the industry standard since its inception. Mellel focuses on writers and scholars for technical writing and multilingual... Read more
LibreOffice 4.3.0.4 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
Freeway Pro 7.0 - Drag-and-drop Web desi...
Freeway Pro lets you build websites with speed and precision... without writing a line of code! With it's user-oriented drag-and-drop interface, Freeway Pro helps you piece together the website of... Read more
Drive Genius 3.2.4 - Powerful system uti...
Drive Genius is an OS X utility designed to provide unsurpassed storage management. Featuring an easy-to-use interface, Drive Genius is packed with powerful tools such as a drive optimizer, a... Read more

Latest Forum Discussions

See All

Dawn of the Immortals Review
Dawn of the Immortals Review By Jennifer Allen on July 31st, 2014 Our Rating: :: RESPECTABLE EXPLORATIONUniversal App - Designed for iPhone and iPad Dawn of the Immortals might not re-invent the wheel, but it does tweak it a little... | Read more »
80 Days Review
80 Days Review By Jennifer Allen on July 31st, 2014 Our Rating: :: EPIC ADVENTUREUniversal App - Designed for iPhone and iPad A fantastic and fascinating re-envisioning of the classic novel by Jules Verne, 80 Days is a delightful... | Read more »
Battleheart Legacy Guide
The world of Battleheart Legacy is fun and deep; full of wizards, warriors, and witches. Here are some tips and tactics to help you get the most enjoyment out of this great game. | Read more »
Puzzle Roo Review
Puzzle Roo Review By Jennifer Allen on July 31st, 2014 Our Rating: :: PUZZLE-BASED TWISTUniversal App - Designed for iPhone and iPad A different take on the usual block dropping puzzle game, Puzzle Roo is quite pleasant.   | Read more »
Super Crossfire Re-Release Super Crossfi...
Super Crossfire Re-Release Super Crossfighter Coming Soon, Other Radiangames Titles Go 50% Off Posted by Ellis Spice on July 31st, 2014 [ | Read more »
Hexiled Review
Hexiled Review By Rob Thomas on July 31st, 2014 Our Rating: :: HEX SELLSUniversal App - Designed for iPhone and iPad In space, no one can hear you… spell? Hexiled is a neat concept for a word scramble puzzle, but it doesn’t go too... | Read more »
Summoners War: Sky Arena Passes 10 Milli...
Summoners War: Sky Arena Passes 10 Million Installs! Posted by Jessica Fisher on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Deep Loot Review
Deep Loot Review By Jennifer Allen on July 31st, 2014 Our Rating: :: DIVE DEEPUniversal App - Designed for iPhone and iPad Dive deep in this fun explore-em-up that’s a little grind heavy but ultimately quite entertaining.   | Read more »
Despicable Me: Minion Rush is One Year O...
Despicable Me: Minion Rush is One Year Old, Gets its Biggest Update Yet Posted by Jennifer Allen on July 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Fish & Shark Review
Fish & Shark Review By Jordan Minor on July 31st, 2014 Our Rating: :: FLAPPY FISHUniversal App - Designed for iPhone and iPad Fish & Shark’s beauty is only scale deep.   | Read more »

Price Scanner via MacPrices.net

All Over For Tablets Or Just A Maturing, Evol...
CNN’s David Goldman weighs in on tablet sector doom and gloom, asking rhetorically: “Is this the beginning of the end for the tablet?” Answering that, he contends that hysteria and panic are... Read more
Letterspace 1.0.1 – New Free iOS Text Editor...
Bangkok, Thailand based independent developer Sittipon Simasanti has released Letterspace, a new text editor for iPhone, iPad, and iPod touch devices. Letterspace is a note taking app with an... Read more
Save up to $130 on an iPad mini with Apple re...
The Apple Store has Certified Refurbished 2nd generation iPad minis with Retina Displays available for up to $130 off the cost of new models, starting at $339. Apple’s one-year warranty is included... Read more
iPad Cannibalization Threat “Overblown”
Seeking Alpha’s Kevin Greenhalgh observes that while many commentators think Apple’s forthcoming 5.5-inch panel iPhone 6 will cannibalize iPad sales, in his estimation, these concerns are being... Read more
Primate Labs Releases July 2014 MacBook Pro P...
Primate Labs’ John Poole has posted Geekbench 3 results for most of the new MacBook Pro models that Apple released on Tuesday. Poole observes that overall performance improvements for the new MacBook... Read more
Apple Re-Releases Bugfixed MacBook Air EFI Fi...
Apple has posted a bugfixed version EFI Firmware Update 2.9 a for MacBook Air (Mid 2011) models. The update addresses an issue where systems may take longer to wake from sleep than expected, and... Read more
Save $50 on the 2.5GHz Mac mini, plus free sh...
B&H Photo has the 2.5GHz Mac mini on sale for $549.99 including free shipping. That’s $50 off MSRP, and B&H will also include a free copy of Parallels Desktop software. NY sales tax only. Read more
Save up to $140 on an iPad Air with Apple ref...
Apple is offering Certified Refurbished iPad Airs for up to $140 off MSRP. Apple’s one-year warranty is included with each model, and shipping is free. Stock tends to come and go with some of these... Read more
$250 price drop on leftover 15-inch Retina Ma...
B&H Photo has dropped prices on 2013 15″ Retina MacBook Pros by $250 off original MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.3GHz Retina MacBook Pro: $2249, $250 off... Read more
More iPad Upgrade Musings – The ‘Book Mystiqu...
Much discussed recently, what with Apple reporting iPad sales shrinkage over two consecutive quarters, is that it had apparently been widely assumed that tablet users would follow a two-year hardware... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
Sr. Product Leader, *Apple* Store Apps - Ap...
**Job Summary** Imagine what you could do here. At Apple , great ideas have a way of becoming great products, services, and customer experiences very quickly. Bring Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
Sr Software Lead Engineer, *Apple* Online S...
Sr Software Lead Engineer, Apple Online Store Publishing Systems Keywords: Company: Apple Job Code: E3PCAK8MgYYkw Location (City or ZIP): Santa Clara Status: Full Read more
*Apple* Solutions Consultant (ASC) - Apple (...
**Job Summary** The ASC is an Apple employee who serves as an Apple brand ambassador and influencer in a Reseller's store. The ASC's role is to grow Apple Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.