What Is It?

Appearance OSAX extends the ways in which your AppleScripts can interact with the user. Normal AppleScripts can present simple dialog boxes that contain either one to three buttons, a text field, or a list of items to select. With Appearance OSAX installed, your scripts can employ alerts, fancy dialogs with many types of fields, floating message and progress windows, and notifications that cause Dock icons to bounce.

How Do I Use It?

Since Appearance OSAX is a scripting addition, it must be installed in the ScriptingAdditions folder. You can then view its dictionary of commands using your favorite script editor. There is no graphical user interface for Appearance OSAX. Instead, you type its commands into your script. AppleScripters commonly use the built-in display dialog command. To access Appearance OSAX’s additional features, simply use display better dialog instead.

Scripts that use Appearance OSAX commands like display better dialog require Appearance OSAX to run. Fortunately, you don’t need to buy a copy of Appearance OSAX for every machine that your script will be deployed on. If your script is distributed as freeware, you can distribute Appearance OSAX with it for no additional charge. Otherwise, you need to pay $149 or more to bundle Appearance OSAX.

An Example

Suppose we want to write a script to help write HTML headings. The script will ask the user whether he wants a first-, second-, or third-level heading, how the heading should be aligned, and what the text should be. The script will return an HTML fragment such as <H1 ALIGN="Left">your heading here</H1>.

We could do this with AppleScript’s display dialog. We could have one dialog that displayed three buttons for the different levels. A second dialog could display a list of the different alignments. A third could display a text field for the heading text. It’s quite simple to write an AppleScript for these three dialogs, but the user experience would not be very good.

Instead, we’ll create a single dialog using Appearance OSAX.

A dialog box created with better display dialog.

We’ll create the radio butons, the pop-up menu, and the text field as better dialog field records.

Each field of the dialog is a better dialog field record.

The AppleScript to create the dialog is:

set h1 to {kind:radio button, name:"H1"}
set h2 to {kind:radio button, name:"H2"}
set h3 to {kind:radio button, name:"H3"}
set levelButtons to {h1, h2, h3}

set alignMenu to {kind:pop-up menu, name:"Align:", ¬
                  menu items:{"Left", "Center", "Right", "Justify"}}

set textField to {kind:text field, name:"Text:", ¬
                  value:"your heading here"}

display better dialog "Heading Level:" ¬
  buttons {"Apply", "Cancel"} default button 1 ¬
  cancel button 2 fields levelButtons & {alignMenu} & {textField}
set theResult to the result

A normal display dialog returns a dialog reply record that says which button was clicked or which text was entered. Since Appearance OSAX dialogs have multiple fields, the corresponding better dialog reply is a bit more complicated. For the above example, it might look like:

{ button returned:"Apply",
 choices returned:{"H1", "Left", "your heading here"},
 -- (omitted) fields returned: a list of all the 
              better dialog fields you passed in}

In most cases, though, you would only care about the first two items of the record, which button was pressed, and which choices the user made. For our example, the code to extract the user’s choices and generate the HTML might look like:

if button returned of theResult is "Apply"
  set theChoices to choices returned of theResult
  set theLevel to item 1 of theChoices
  set theAlignment to item 2 of theChoices
  set theText to item 3 of theChoices
  return "<" & theLevel & " ALIGN=\"" & theAlignment ¬
      & "\">" & theText & "</" & theLevel & ">"
end

What Else Can It Do?

display better dialog supports up to 10 fields and five buttons. Besides the fields demonstrated above, you can have password fields (text fields that hide what you type) and checkboxes. Appearance OSAX also supports simple alert windows, which can display more text than display dialog and also support an alert icon, a help button, and up to three named buttons. As with the dialog example above, you can choose the default and cancel buttons for alert windows. These respond to the Return and Escape keys, respectively. You can also choose whether dialogs and alerts are displayed in movable windows. Unfortunately, it doesn’t seem to be possible to make an Appearance OSAX dialog “give up” after a set number of seconds without any user interaction, as is possible with display dialog.

Appearance OSAX supports message windows and progress indicators. The layout of the progress indicator window is fixed, but you can set the text of the title and the two messages as well as the names of the buttons. If the user clicks on one of the buttons in a progress indicator, Appearance OSAX calls the handle floating window handler in your script. With this mechanism, you can handle simple user interaction (like pausing) quite succinctly.

Message windows can display a lot of text and don’t interrupt the user.

Progress indicators are easy to use and provide a better user experience than the sequence of auto-vanishing modal dialog boxes that many AppleScripters use.

What About AppleScript Studio?

By now you may be wondering why anyone would want to use Appearance OSAX now that AppleScript Studio is available. Indeed, AppleScript Studio is both cheaper (free) and more flexible than Appearance OSAX. Every interface you can create with Appearance OSAX will be a variation on the features I mentioned above. But with AppleScript Studio you can use the full palette of Cocoa widgets and control them at a finer level. You can position controls any way you want right down to the pixel. With Appearance OSAX, dialogs are static; you present the user with a dialog and get a response back. With AppleScript Studio you could make a live dialog that, for instance, let the user pick an HTML tag and then displayed the attributes relevant to that tag.

Nevertheless, these features of AppleScript Studio can get in the way if you don’t need that much control. With Appearance OSAX, you can simply list the fields you want in a dialog and trust that they will be displayed in a suitable manner. There’s no need to use Interface Builder to construct the dialog button by button, making sure that you leave the proper amount of space between each control. AppleScript Studio is even further behind if you want to construct your interface dynamically. It’s difficult to add or remove buttons or fields at runtime. With Appearance OSAX, this is easy; you don’t even have to do anything different from the normal display better dialog command.

Likewise, AppleScript Studio provides many handlers that let you do complex user interaction. It goes far beyond the limited better dialog reply that Appearance OSAX supports. Still, most of the time all you want to know is the current value of each field, and for that the better dialog reply’s simplicity is hard to beat.

Distributing software is a draw. AppleScript Studio applications may be distributed for free, but they only work on recent versions of Mac OS X. Appearance OSAX scripts require that Appearance OSAX be licensed and installed, but there is also an Appearance OSAX for Mac OS 9. I’m not sure how compatible scripts are between the two versions of Appearance OSAX, though. 24U ignored the e-mails I sent to their technical support address, so I can’t give you their take on this either.

To develop with AppleScript Studio, you need to install the Mac OS X developer tools. Project Builder and Interface Builder are industrial-strength tools, and with their power comes a lot complexity. Much of it isn’t relevant to AppleScript development, though you will be exposed it all the same. In fact, to use AppleScript Studio effectively you essentially have to learn AppleScript, Cocoa, Project Builder, and Interface Builder. AppleScript Studio comes with a 300-page manual to help you do this.

Appearance OSAX, by contrast, is pure AppleScript. You can use it with whatever AppleScript environment you are currently using; there’s no need to learn about “building,” or “projects,” or “.nib” files. All it comes with is a few sample scripts and a dictionary, but that’s all you’ll need. If you know AppleScript, I think you’ll be able to pick up Appearance OSAX in a matter of minutes.

Conclusion

I found Appearance OSAX to be nearly perfect at what it does. It’s easy to learn and use, and I think the widgets it provides are adequate for the automation and integration tasks that AppleScript was originally intended for. The bundling terms are reasonable. It beats AppleScript Studio hands down on the simple stuff. That said, if you use AppleScript to write applications rather than scripts, you won’t be happy with Appearance OSAX. That’s when you should turn to AppleScript Studio or Cocoa.