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!

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Apple iOS 10.2.1 - The latest version of...
iOS 10 is the biggest release of iOS ever. A massive update to Messages brings the power of the App Store to your conversations and makes messaging more personal than ever. Find your route with... Read more
Apple Security Update 2016-003 Supplemen...
Apple Security Update is recommended for all users and improves the security of OS X. For detailed information about the security content of this update, please visit: http://support.apple.com/kb/... Read more
Apple macOS Sierra 10.12.3 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
BetterTouchTool 1.992 - Customize Multi-...
BetterTouchTool adds many new, fully customizable gestures to the Magic Mouse, Multi-Touch MacBook trackpad, and Magic Trackpad. These gestures are customizable: Magic Mouse: Pinch in / out (zoom... Read more
Viber 6.5.5 - Send messages and make cal...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Opera 42.0.2393.137 - High-performance W...
Opera is a fast and secure browser trusted by millions of users. With the intuitive interface, Speed Dial and visual bookmarks for organizing favorite sites, news feature with fresh, relevant content... Read more
iClock Pro 3.4.7 - Customize your menuba...
iClock Pro is a menu bar replacement clock for Apple's default clock. iClock Pro is an update, total rewrite and improvement to the popular iClock. Have the day, date and time in different fonts and... Read more
PhotoDesk 4.1.5 - Instagram client for p...
PhotoDesk lets you view, like, comment, and download Instagram pictures/videos. (NO Uploads! / Image Posting! Instagram forbids that! AND you need an existing Instagram account). But you can do so... Read more
Capo 3.5.1 - Slow down and learn to play...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
HandBrake 1.0.2 - Versatile video encode...
HandBrake is a tool for converting video from nearly any format to a selection of modern, widely supported codecs. Features Supported Sources VIDEO_TS folder, DVD image or real DVD (unencrypted... Read more

Collect pets and sling arrows in Arcane...
Mobile gaming is a crowded market, but regular updates are a good way to keep us attention-short players keen. The brand new content in Arcane Online is a prime example. Published by Japanese developer Gala, Arcane Online is a fantasy MMO that... | Read more »
Super Mario Run dashes onto Android in M...
Super Mario Run was one of the biggest mobile launches in 2016 before it was met with a lukewarm response by many. While the game itself plays a treat, it's pretty hard to swallow the steep price for the full game. With that said, Android users... | Read more »
WarFriends Beginner's Guide: How to...
Chillingo's new game, WarFriends, is finally available world wide, and so far it's a refreshing change from common mobile game trends. The game's a mix of tower defense, third person shooter, and collectible card game. There's a lot to unpack here... | Read more »
Super Gridland (Entertainment)
Super Gridland 1.0 Device: iOS Universal Category: Entertainment Price: $1.99, Version: 1.0 (iTunes) Description: Match. Build. Survive. "exquisitely tuned" - Rock Paper Shotgun No in-app purches, and no ads! | Read more »
Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »

Price Scanner via MacPrices.net

Deal alert! 13-inch 2.0GHz MacBook Pros for $...
B&H Photo has the new 2016 13″ 2.0GHz non-Touch Bar MacBook Pros in stock today and on sale for $225 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.0GHz MacBook Pro... Read more
Free LibreOffice Portable 5.2.4 Complete Offi...
PortableApps.com and The Document Foundation have announce the release of LibreOffice Portable 5.2.4. LibreOffice Portable is an Open Source full-featured office suite — including a word processor,... Read more
Apple Planning Three New Tablets For 2017 – D...
Digitimes’ Rebecca Kuo and Joseph Tsai say that unnamed insider sources report Apple having three new tablets in the pipeline for 2017 release: a 9.7-inch model with a friendly price range, a new mid... Read more
Roundup of 15-inch Touch Bar MacBook Pro sale...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Apple refurbished iPad Pros available for up...
Apple has Certified Refurbished 9″ and 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 9″... Read more
16GB iPad Air 2, Apple refurbished, available...
Apple has Certified Refurbished 16GB iPad Air 2s available for $319 including free shipping. A standard Apple one-year is included. Their price is $60 off original MSRP for this model. Read more
Apple iMacs on sale for up to $120 off MSRP
B&H Photo has 21″ and 27″ Apple iMacs on sale for up to $120 off MSRP, each including free shipping plus NY sales tax only: - 27″ 3.3GHz iMac 5K: $2199 $100 off MSRP - 27″ 3.2GHz/1TB Fusion iMac... Read more
Apple refurbished Apple TVs available for up...
Apple has Certified Refurbished 32GB and 64GB Apple TVs available for up to $30 off the cost of new models. Apple’s standard one-year warranty is included with each model, and shipping is free: -... Read more
Save up to $350 with Apple Certified Refurbis...
Apple has Certified Refurbished 2015 21″ & 27″ iMacs available for up to $350 off MSRP. Apple’s one-year warranty is standard, and shipping is free. The following models are available: - 21″ 3.... Read more
2015 12-inch Retina MacBooks, Apple refurbish...
Apple has Certified Refurbished 2015 12″ Retina MacBooks available for up to $410 off original MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The... Read more

Jobs Board

*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Stamford, CT We have immediate job openings for several Desktop Support Technicians with one of our most well-known Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Site Security Manager - Apple (Unite...
# Apple Site Security Manager Job Number: 54692472 Culver City, California, United States Posted: Jan. 19, 2017 Weekly Hours: 40.00 **Job Summary** The Apple Read more
*Apple* macOS Systems Integration Administra...
…most exceptional support available in the industry. SCI is seeking an Junior Apple macOS systems integration administrator that will be responsible for providing Read more
*Apple* Retail - Multiple Positions- Deer Pa...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.