UPDATE: The information on this page has been made public here.
Enhanced Applets
The FancyDroplet project has been integrated into Script Debugger 7 and is known as an Enhanced Applet shell. Creating an Enhanced Applet is as easy as using Script Debugger’s Save As or Export As Run-Only commands.
Why Use Enhanced Applets?
The standard applet shell provided by Apple has been with us since AppleScript’s inception. It is a minimal means of deploying a script as a stand alone application. Our objective with the Enhanced Applet shell is to provide additional functionality for scripters and to improve the user experience, especially when developing droplets (scripts that open files).
Switch to the Enhanced Applet shell when you want any of the following:
- you want your script application to appear to be a modern Cocoa application.
- you want your script to respond when the user stops or quits your script application.
- you want to offer a enhanced droplet UI including a drop window and Spotlight document searching.
- you want to be able to offer updates to your script using the Sparkle framework.
- you want to be able to filter the dropped files your script will accept using AppleScript, in addition to UTIs and file extensions.
System Requirements
Scripts saved using the Enhanced Applet shell require macOS Yosemite (10.10) or later to operate.
Creating an Enhanced Applet
Create your script as you normally would in Script Debugger. When it comes time to save, you can choose Application (Enhanced) from the Format popup menu:
You can also choose the Application (Enhanced) option from the Format popup menu using Script Debugger’s Export Run-Only command to create a Run-Only Enhanced Applet.
At any time, you can revert to the standard Apple applet shell re-saving your script with the Application (Apple) item in the Format popup menu.
Handling Stop & Quit
The standard Apple applet shell offers a Done button and responds to Command-.. When you press done or quit the application, the script simply stops. In an Enhanced Applet you can respond to this action in your script.
Enhanced Applets generate a user cancelled exception (-128) when the user presses the done button or quits the applet. You can place an AppleScript try/on error/end try block around your run handler code to catch this exception and act appropriately.
Additionally, Enhanced Applets provide a boolean appletIsQuitting property so that you can determine if the user is quitting the application or simply stopping your script.
Here’s an example:
use AppleScript version "2.4" -- Yosemite (10.10) or later
use scripting additions
global appletIsQuitting -- let the AppleScript compiler know about this runtime defined property
on open theFiles
try
repeat with aFile in theFiles
-- process aFile in some way...
end repeat
on error number -128 -- userCancelledErr
if appletIsQuitting then
set alertResult to display alert "Quitting!" message "This script has been interrupted because the applet has been quit." buttons {"Stop", "Quit"} default button "Quit"
if button returned of alertResult is "Stop" then
error number 0 -- clear the userCancelledErr to prevent the applet from quitting
end if
else
display alert "Stopped!" message "This script has been interrupted because the Stop button has been pressed." buttons "Stop" default button "Stop"
end if
end try
end open
If you do not provide an on error number -128 block to catch this exception, Enhanced Applet shell will stop your script immediately just as the standard AppleScript droplet shell does.
NOTE: The Enhanced Applet shell will receive the user cancelled exception (-128) when the script finishes unless you generate another exception. You’ll notice the error number 0 statement in my example which has the effect of preventing FancyApplet from quitting.
NOTE: The appletIsQuitting identifier must be defined using a global or property statement. Failure to do this will cause AppleScript to fail to see this identifier and throw an error when you try and get the value of appletIsQuitting.
Standard Additions
The standard AppleScript droplet shell displays alerts and file selection panels as application-modal windows which block the application. The Enhanced Applet shell displays panels generated with the following commands as sheets:
display alertdisplay dialogchoose filechoose folderchoose file namechoose from list
For example, this statement:
display alert "Alert Message" message "Alert Description" buttons {"Button 1", "Button 2", "Button 3"} default button "Button 2"
Produces this panel in the standard AppleScript droplet shell:
And appears like this in the Enhanced Applet shell:
Displaying Progress Information
The Enhanced Applet shell fully supports AppleScript’s progress properties and displays progress information according to the values your script assigns to these properties.
For example, this code:
set progress description to "Progress Description"
set progress additional description to "Progress Additional Description"
set progress total steps to 100
set progress completed steps to 75
Is displayed like this:
Droplet File Filtering
Use the Droplet Behavior section of Script Debugger 7’s improved bundle editor to specify a list of acceptable filename extension and/or Uniform Type Identifiers your script accepts.
Use Uniform Type Identifiers when you want to specify a class of type types. For instance, public.plain-text specifies all text file types, and public.image specifies all image file types). Use filename extensions when there is no suitable Uniform Type Identifiers or when you only want to receive a specific type of file.
Apple provides a list of system-defined Uniform Type Identifiers.
Advanced File Filtering
There may be times when Uniform Type Identifiers and filename extensions are insufficient for identifying the types of files your script can process. The Enhanced Applet shell allows you to filter the files in AppleScript be defining a on appletFileIsAcceptable(theFile) handler:
on appletFileIsAcceptable(theFile)
return true
end appletFileIsAcceptable
This handler is called after files have been filtered by their Uniform Type Identifier. We strongly recommend using Uniform Type Identifiers to filter files in combination with the appletFileIsAcceptable handler to minimize performance issues. The appletFileIsAcceptable handler must be FAST as it is used frequently to validate file drops and spotlight search results.
Note For AppleScript Objective-C Users
Enhanced Applets run all scripts on a background thread. If you are using AppleScript Objective-C to present any kind of UI or are using any other main-thread only APIs, please ensure that you invoke AppleScript handlers on the main thread to accomplish this.
Please keep main-thread AppleScript execution to a minimum as it will block the UI.
Customizing The Droplet Window
The Enhanced Applet shell provides some opportunities to customize the droplet window.
Drop Target Text & Icon
-- Properties configuring the droplet shell
property appletDropImage : "CSVDocumentIcon"
property appletDropName : "Drop your CSV files here"
The appletDropImage property should contain the name (without filename extension) of a image file located within the droplet bundle’s Resources folder. If you don’t want icons for the drop image, specify missing value.
Spotlight Text & Icon
-- Properties configuring the droplet shell
property appletSearchName : "Find CSV files"
property appletSearchImage : "CSVBadge"
The appletSearchImage property should contain the name (without filename extension) of a image file located within the droplet bundle’s Resources folder. If you don’t want icons for the drop image, specify missing value.
The dimensions of the search image should be 35 x 16 pixels. You can include a @2x version of this image for Retina displays.
Sparkle Software Updates
The Sparkle framework provides a means of delivering automated updates for your script applications to your customers. While a full explanation of how Sparkle works is outside the scope of this document, here are the details of how to integrate Sparkle into an Enhanced Applet.
T.B.D.