by Kevin Bradley
Like Andy Ihnatko, I just love Applescript Studio. I think it’s one of the coolest features of OS X, and have spent the last year throwing together applications. During that time, I’ve found several ways to polish an Applescript Studio application to make it more, well, professional. And while it’s possible to find most or all of this information in the XCode documentation, it took me a year to dig up all these techniques and hopefully this article will save you from investing that amount of time.
Icon Do It!
One of the easiest ways to spruce up your program is to add an application icon. To to this, create a 128x128 tiff image with alpha channel information (for the transparent parts). If you aren’t able to afford Adobe’s Photoshop, I suggest GimpShop, a version of the open-source Gimp graphic editor that is Mac-specific and has been revised to be more “Photoshop-like.” In like manner, Inkscape is an open-source vector drawing program that has much of the functionality of Adobe’s Illustrator.
While XCode can use your tiff image ‘as is’, the Apple Developer Tools provide a method to convert your tiff into an actual icon file (type icns). The Icon Composer application is very straightforward. When you launch the program, it opens a window with four tiers, one for each static size (other sizes are interpolated). At the bottom is the largest size, 128x128, which is where you will put your tiff file. You can simply drag your tiff file into the left-hand box (or use the Import Image menu item in the File menu). If your image is larger than 128x128, you will be asked if you want to use a scaled version of the tiff.
Once the thumbnail size (128) is loaded, you can drag that image into the other sizes’ left-hand boxes and let the program scale them and compute the icon mask. If you don’t like the way the program scales them, you can create your own versions at the various sizes(16, 32, and 48) and import them. If you look carefully at some of the icons on your Mac, you’ll notice that at the smaller sizes sometimes the icon creator uses a closeup of the original graphic in order to get enough detail in the smaller icon to make it clear, rather than just scaling the original image.
If you want to see your icon gracing your completed icon file, a simple utility I found called icns2icon will take your new icon and transfer it to the file you just created. Just drag your icon file onto the icns2icon application. Now you can see your icons at a glance.
To install your application icon into your project, right click on the resources folder in XCode’s project view and select Add then Existing Files… When XCode asks if you want to copy the file into your project directory, you can choose to do so if you like, or leave it where it is now and just add a reference to it. Either way, you now need to inform your project that this icon is to be used for the application.
To do this, select the Edit Active Target ‘yourappname’ item from the Project menu. Go to the Properties tab and put the name of your icon into the supplied form, where it says “Icon File.”
Now when you build your project, you’ll have your own custom icon!
Somebody Help Me!
Help pages are one of the most overlooked items in Applescript Studio applications, and there’s little reason for it. Making a “help book” is actually very easy and installing it into your app requires little from you, the programmer. Most of the help functionality comes from Cocoa anyway, you just need to create the items needed and “plug them in.”
Help books are just HTML files contained in their own folder… Yep, just like a website! You create an index page that will be the “landing zone” when one of your users selects the help menu item in your application. You can add as many or as few pages as you need to explain your application. If you need or want images, just create an images folder in your help book’s folder and in your pages use relative URL’s to reference them. So for a graphic, you would use href=“images/yourgraphic.jpg” rather than a full URL.
In order to convince the Help Viewer that your help book is legit, you must include the following meta tag in the section of your index page:
There are other tags for setting the default font, default search font, chapter order and icon (to be used in the list of available help books). But the AppleTitle tag is the only one that must be present.
To provide your users the ability to search your help, you need to index your help pages. To do this, drop your help folder on the Help Indexer application in the Utilities folder of your Developer tools. An index file is created and put into your folder with your HTML files.
Once you’ve indexed your HTML pages and they work the way you want them to (I suggest viewing them in Safari first), you again use the Add Existing Files… context menu item to add the help folder to your project. When the copy dialog pops up, be sure to mark the “Add folder references” item, or your help won’t work. Why? Because one of the pieces of information you must provide XCode is the name of your help folder!
The other information you must provide to XCode is the name of the help book as you want it to appear in Help Viewer. To provide these 2 pieces of information you add 2 keys to the info.plist of your project in this form:
[color=red]<key>CFBundleHelpBookName&</key>
<string>YourApp Help</string>
<key>CFBundleHelpBookFolder</key>
<string>YourApp Help</string>[/color]
Your folder name doesn’t have to match the name of the help book, but for convenience sake most developers name them the same.
That’s it. At this point, re-build your app and try out the help menu item. Thanks to Cocoa’s underlying framework, your user can initiate a help session with Help Viewer.
Hand Me That Toolbar
So far the two techniques above haven’t included a single line of Applescript, but this next topic demands it. If you have ever wanted to add toolbars to your application, the only way to do it is through Applescript. Interface Builder doesn’t include the ability to design toolbars (as of Tiger 10.4.10), though that may change in Leopard.
You may have noticed that Interface Builder does include the ability to use the “unified” window look on your windows. But without a toolbar, that checkbox is meaningless. When designing your window and toolbar, think about whether you want the window to have the unified look or not. Try both, and use what looks best to you.
In the Applescript portion of Interface Builder’s Inspector window, make sure you select the awake from nib event for your window. It is during the awake from nib handler that you will initialize your toolbar.
Using the variable theObject, which in an awake from nib handler is a reference to the window in question, you create a toolbar by using make:
-- Make the new toolbar, giving it a unique identifier
set MyWindowToolbar to make new toolbar at end with properties {name:"MyWindow toolbar", identifier:"MyWindow toolbar identifier", allows customization:true, auto sizes cells:true, display mode:default display mode, size mode:default size mode}
-- Setup the allowed and default identifiers.
set allowed identifiers of MyWindowToolbar to {"add client identifier", "remove client identifier", "edit client identifier", "print item identifier", "customize toolbar item identifer", "flexible space item identifer", "space item identifier", "separator item identifier"}
set default identifiers of MyWindowToolbar to {"add client identifier", "remove client identifier", "flexible space item identifer","edit client identifier"}
The last 2 commands tell the window what toolbar icons are allowed and what the default set is. Remember, the user can customize the toolbar to suit themselves, so it behooves you to give them the best default set you can think of without being overkill.
Besides the toolbar buttons you create, you also have the freedom to use established buttons like Print, Space, Flexible Space, Separator and Customize Toolbar. Note: The names of two of the standard items are mispelled and must be mispelled to work. The word “identifier” is spelled as “identifer.” The two items are the “flexible space item identifer” and the “customize toolbar item identifer.”
Once the toolbar is created, then you can begin to fill it with buttons, again using make. The standard items already exist, so you don’t need to create them, just the buttons you are adding of your own.
-- Create the toolbar items, adding them to the toolbar.
make new toolbar item at end of toolbar items of MyWindowToolbar with properties {identifier:"add client identifier", name:"add client", label:"Add Client", palette label:"Add Client", tool tip:"Add a new client.", image name:"addclient32.png"} --note the usage of your own icon file, usually at 32x32
make new toolbar item at end of toolbar items of MyWindowToolbar with properties {identifier:"remove client identifier", name:"remove client", label:"Remove Client", palette label:"Remove Client", tool tip:"Remove an existing client.", image name:"removeclient32.png"}
make new toolbar item at end of toolbar items of MyWindowToolbar with properties {identifier:"edit client identifier", name:"edit client", label:"Edit Client", palette label:"Edit Client", tool tip:"Edit a client's information.", image name:"editclient32.png"}
At this point all that is left is to assign the toolbar to the window:
-- Assign our toolbar to the window
set toolbar of theObject to MyWindowToolbar
Gentlemen Prefer Preferences
To really put a spit-shine on your application you create preferences, or user defaults. Support for user defaults is a relatively new addition to Applescript Studio. Previously a developer had to use Cocoa call method calls to achieve saving and restoring preferences.
So, to make use of preferences, you need some script properties to hold the prefs while your application is running. You’ll set these properties to the default values for your preferences.
property NW98firstRun : "YES"
property NW98taxRate : 0
property NW98Logo : "None"
You create preferences by making new user default keys and writing these initial values to those keys. The best place to do this is when your application starts up, so I put them in the will finish launching event handler. You turn this event on in Interface Builder, by selecting the “File’s Owner” item and checking the box “will finish launching” in the Application section of the Applescript item in the Inspector.
tell user defaults
make new default entry at end of default entries with properties {name:"NW98firstRun", contents:NW98firstRun}
make new default entry at end of default entries with properties {name:"NW98taxRate", contents:NW98taxRate}
make new default entry at end of default entries with properties {name:"NW98Logo", contents:NW98Logo}
end tell
OK, here’s where things get strange. You do this every time the application runs, even if you have already created the default items before. Why? Because you don’t have a way to tell if this is the VERY first time the application is run. Applescript is smart enough to NOT bother existing preference values if the specified keys already exist.
After you initialize the preferences, you can then read them. If you just wrote them, you’ll get back the original default values. If this isn’t the first time the application is run and the user has changed some of the preferences, you’ll get back whatever they were changed to the last time.
tell user defaults
set NW98firstRun to contents of default entry "NW98firstRun"
set NW98taxRate to (contents of default entry "NW98taxRate") as real
set NW98Logo to contents of default entry "NW98Logo"
end tell
Finally, when your application ends is time to write the user defaults back to the preferences file. A good time to do this is in the will quit handler. You should also do this when the user changes the defaults; usually this will be when the user quits the preferences dialog.
tell user defaults
set contents of default entry "NW98firstRun" to NW98firstRun
set contents of default entry "NW98taxRate" to NW98taxRate
set contents of default entry "NW98Logo" to NW98Logo
end tell
call method "synchronize" of object user defaults
The “synchronize” call method flushes the defaults and makes sure they are actually written to disk. Originally, the Applescript “register” command was meant to do this, but as of Applescript Studio 1.4 (the current version), it does not do this.
End Tell
There you have four techniques for making your application more savvy, slicker, and smarter. There’s one more thing that you can do to make your application better, and it’s one that most people don’t think of - trapping for errors. Never count on the user to know what to do, or to input the right thing. Anytime things can go wrong, they probably will. So use a try…on error block to catch errors and respond appropriately.
Have fun, and crunch code!
