2.1 Script Editor Controls/Commands

The Script window, shown in Figure 2-2 (from the OS 9 desktop) is where you edit and compile code. The other windows that are displayed and used by this program are dictionary windows, Event Log, and Result window (all these are discussed later in this chapter). The title bar of the window contains the name of the script next to a script icon that indicates which file type you saved it as (e.g., compiled script, applet). In Mac OS 9.1 and Mac OS X (i.e., AppleScript 1.5 and later), if you drag that icon to a disk folder the script will be moved to that folder.

All menu commands and windows attributed to Script Editor for OS 9 are replicated without any changes in OS X, except for the fact that the OS X Script Editor has been redesigned for the Aqua interface.

Figure 2-2. Script Editor window in OS 9

The following list describes the parts of the Script window:

2.1.1 Dictionaries

Before scripting an application, first find out which AppleScript commands it supports. The scripter also has to know which of the target application's objects, such as files, paragraphs, or database records, can be manipulated by a script. You can accomplish this task by selecting the program from Script Editor's File Open Dictionary menu command. This command displays the dialog box depicted in Figure 2-3. Figure 2-4 shows what the same dialog box looks like in Mac OS X. Just choose the application icon of the program that you want to examine to view its dictionary in a dictionary window.

You can open a program's dictionary by dragging the program's icon in the Finder to the Script Editor's icon.

Figure 2-3. Open Dictionary dialog box in 0S 9

The application's dictionary specifically lists the sets, or suites, of script commands and classes that the program supports (for example, the Standard Suite, AppleScript suite, or Text suite). Figure 2-5 shows the Finder's dictionary window in OS 9. The left panel of the dictionary window lists the application's commands in plain text and its classes in italics. Remember that commands are the messages or Apple events that a script sends an application in order to get it to do something (e.g., sleep). Classes or objects are the things that a script may try to change or get information about (e.g., a file or folder).

If a system application, extension, or control panel does not show up in their folder when you use File Open Dictionary, then they do not have a dictionary; they are minimally scriptable or not scriptable at all. Some control panels in OS 9, for instance, do not have a dictionary but respond to a "run" AppleScript command (such as Energy Saver). In Mac OS X, for example, if the application icon is dimmed in the Open Dictionary dialog window, then the app does not (yet) have a viewable dictionary .

Figure 2-4. Open Dictionary dialog in OS X

Figure 2-5. Finder's dictionary

2.1.2 Special Edit Menu Items

The Edit AppleScript Formatting menu item allows the scripter to determine the font type and size inside the script window of various AppleScript language elements such as uncompiled text, operators, and comments. A pop-up menu button at the bottom of the dialog box produced by this command identifies the dialect that Script Editor will use (e.g., "AppleScript English").

Script Editor's Edit Paste Reference menu item will add to the script window a reference to any objects (such as files or disks) that you have selected and copied from the desktop. For instance, if you select and copy a disk called "scratch" on your desktop, then choosing this menu item will paste disk "scratch" within the script window.

2.1.3 Script Saving Options

You have four different options for saving a file in Script Editor; however, Mac OS X does not support the stationery option of OS 9. These options are available from the File Save or File Save As menu choices.

A droplet is by definition saved as an applet, but AppleScript gives it a different icon due to the enclosure of its code in an on open handler.

Figure 2-6 shows the icons for AppleScript file types. Mac OS X supports all of these icon types except the stationery one.

Figure 2-6. Icons for AppleScript file types

2.1.3.1 Script text file

If a script cannot compile without errors, or you just want to save it as plain text, then use the script text saving option. The text option saves the file as file type 'TEXT' and creator type 'ToyS'. In OS X, Script Editor tries to compile a script first when you save it, then displays a dialog window if the script cannot be compiled without error, giving the user the option of saving the script as a text file. If you are not finished with the script and therefore do not yet want to try compiling the source code, then you can skip the compilation stage by holding down the Shift key and choosing Script Editor's File Save menu item. The file will only be saved as a text file.

2.1.3.2 Compiled script file

Script Editor will try to compile the source code before saving it. After a script is saved as a compiled script, double-clicking it opens the script in Script Editor, rather than executing it. These scripts have a file type of 'osas' and creator type 'ToyS'. You can run these scripts from within Script Editor.

The Mac OS distinguishes different kinds of files by giving them unique four-character file types, such as 'osas' for a compiled script, 'TEXT' for an ASCII text file, and 'APPL' for an application that can be double-clicked to launch in the Finder. The four-character creator type identifies the application that handles the file when it is double-clicked (for example, 'ToyS' for Script Editor).

2.1.3.3 Classic applet

These file icons represent an applet that the user can double-click in the Finder to execute. An applet is a self-contained Macintosh application, independent from Script Editor. Classic applets have a file type of 'APPL' and a creator type of 'aplt'. You can still edit these files within Script Editor by choosing File Open Script, then selecting the applet, or by dragging and dropping the applet icon on to the Script Editor icon. A classic applet is designed to run on Mac OS X but only within the classic environment. Figure 2-7 shows the classic (OS-9 type) dialog produced by executing an applet that was saved as a classic applet on an OS X machine.

Figure 2-7. A classic applet executes within the confines of the classic environment

There are a few instances when you would want to run a classic applet inside OS X. One of them is that you want to automate a program that is running in the classic environment on OS X. Another reason is if you are developing an applet for an organization that is using OS 9. If you want to do any Mac OS X scripting, just create and test the applet using the latest version of Script Editor on OS X.

2.1.3.4 MacOS X applets

These applets are intended to work on a computer running Mac OS X (and future OS versions) or on an OS 9 machine that has the CarbonLib extension installed. However, the "MacOS X applet" saving option only works with AppleScript Version 1.5.5 or later, which installed with Mac OS 9.1, so only the MacOS X applets that are created on OS 9.1 machines will run on Mac OS X machines (running the Mac OS X for instance). MacOS X applets are also self-contained applications, independent from Script Editor.

Unraveling Classic and MacOS X Applets on OS X A classic applet that targets a Mac OS 9.1 application (e.g., BBEdit 5.1) does what you would expect it to when double-clicked within Mac OS X. It runs within Mac OS X's classic environment (and opens the classic environment if that has not yet been launched by the operating system), launches the OS 9.1 program, and performs the applet's actions with that program. A MacOS X applet that does not target an OS 9.1 program does not use the classic environment. But what about a MacOS X applet that targets an OS 9.1 program? My testing with Mac OS X indicates that a script saved as a MacOS X applet can still be used to script a program that is running within the classic environment. A MacOS X applet that inserts some text in a BBEdit document file will launch BBEdit in the classic environment and perform the script's actions, just like an applet saved as "classic" will. Strangely enough, I found that both the MacOS X applet and the same applet saved as a classic applet were also able to script elements of the OS X Finder. This is the simple script that I used to test the behavior of both classic and MacOS X applets. It first sends commands to a program that is running within the classic environment, then it scripts the Mac OS X Finder: tell application "BBEdit 5.1" activate insert text "some more text" end (* Now script the OS X Finder *) tell application "Finder" activate set target of Finder window 1 to "/users/" end tell

The File Save dialog box in OS 9 also presents you with a Stationery Option, which gives you the option of saving the file as a template (a stationery pad in Macintosh parlance) or as a document file. If you choose the stationery option, then every time you open the file a new document will be created with the template's contents.

You can prevent the further editing of either a compiled script or an applet by choosing File Save As Run-Only. A run-only compiled script will not reopen in Script Editor if double-clicked, unlike compiled scripts that are not saved as run-only. The applets saved as run-only will execute when double-clicked, but you cannot open them in a new script window for further editing. If you want to prevent users from opening up the application to view its source code, then this is one reason for saving it as run-only.

When you save a script as an applet (classic or Mac OS X), you have two other checkbox options in the Script Editor's File Save As dialog box:

Stay Open

Check this option and the script will not quit after it has completed its job. It will remain one of the running processes on the computer and will even show up in the Mac's About This Computer window. This window displays (on OS 9) a list of running applications and how much RAM they are using; it is accessible from the Apple menu in the upper left corner of the screen. You have to manually quit these scripts from their menu bars, or send them a quit Apple event in some other manner, such as from another script. A Common Gateway Interface (CGI) script on a Mac web server is an example of an application that should be saved using the Stay Open option.

Never Show Startup Screen

Unless this option is checked, executing an applet will cause the display of a startup screen or window, which offers the user the option to run or quit the applet. The top of the startup screen also displays any text that you included in the script window's description field before you saved the applet. In OS 9, this option is checked by default. In other words, running the applet will not produce a window before the applet does anything else.

2.1.3.5 Applets versus droplets

A script application or applet behaves differently in the Finder than script droplets.

A script applet acts like any other Mac application—it performs its operations when the user double-clicks it. And if you display the Application Switcher palette, the applet's icon shows up there. Unless the scripter chose the Stay Open option of the File Save As menu command when she saved the applet, the script process quits after it has completed all of its statements (and after the user has dismissed any dialog boxes the applet displays).

You can also save your script as a droplet. Droplets execute when files, folders, or other objects are dragged and dropped on to the droplet's icon on the Mac desktop. The dropped objects are then passed as an object of value type list to the droplet's open handler. (See Chapter 8, for a description of handlers or subroutines.)

To save a script as a droplet, you have to nest the script inside of an on open...end open handler. When you save the script as an applet with one of these handlers, it has a different icon than other script applications. See Figure 2-6 for an example.

Droplets are very handy for the drag-and-drop processing of entire folders. For example, you could create a droplet that uploads to a web site directory the entire contents of whatever folder is dragged to the droplet. When you drop an item (such as a file, folder, or disk icon) on to the droplet, the droplet automatically executes its open handler. The parameter to the open handler stores whatever is dropped on the droplet as a list object containing objects of value type alias. (An alias looks like a pathname when converted to a string, as in "Macintosh HD:Desktop folder:myfile.txt.") You have to include a parameter with your open handler definition if you want the droplet to deal with the objects that are dropped on it.

If you only drag one file to this droplet, such as a single text file, then the parameter will consist of a list with one alias object in it. If the droplet cannot handle whatever object is dragged and dropped on it, then the droplet icon will not highlight when you drag the item over it.

For example, the script in Example 2-1 displays a dialog box that reveals the file type and creator type of the first item that is dropped on the droplet. If you do not understand several aspects of this program, rest assured that the rest of the book goes into great detail on variables, tell statements, and other AppleScript syntax elements.

Example 2-1. Droplet Displaying File and Creator Types

on open (list_of_aliases)
   (* the parameter to the 'open' handler is a list of aliases*)
   tell application "Finder"
      (* stores the first item that is dropped on the droplet in a variable 
called 'an_item'   *)
      set an_item to (first item of list_of_aliases)
      set amessage to "File type is: " & (an_item's file type as string) &¬
      return & "Creator type is: " & (an_item's creator type as string)
      (* use the 'display dialog' scripting addition command to show 
information to the user *)
      display dialog amessage
   end tell
end open

2.1.4 Debugging with Event Log and Result Windows

Script Editor has two minimal debugging tools on OS 9 and OS X: Event Log and Result windows.

2.1.4.1 Event Log

You can open the Event Log by typing Command-E or by choosing it under Script Editor's Controls menu. If you select the Show Events and Show Event Results checkboxes in the Event Log window, then running the current script will display the result of each Apple event after a (—>) symbol (Chapter 1 discusses Apple events). You can use Event Log to follow along with a program and make sure that the results of each operation are what you expect them to be. Figure 2-8 shows the Event Log window in OS 9.

Figure 2-8. Event Log window

You can use the log keyword in your program and uncheck Show Events and Show Event Results if you just want to track the value of a certain variable in your program. For example, the log window depicted in Figure 2-8 is associated with the program in Example 2-2 (an OS 9 applet).

Example 2-2. Using the log Keyword in Event Log

tell application "Finder"
   set todayFiles to 
   set filecount to 
   log (filecount)
end tell

If you unchecked the checkboxes in Event Log, then the Event Log window will only show the result of the log (filecount) statement bracketed by AppleScript comment symbols (* *). In this case, the result of the log (filecount) statement is the value of the filecount variable. If you had 30 folders on the desktop that did not start with "a", then the Event Log window would display (*30.0*).

You can suppress and restart event-logging activity by using the stop log and start log statements. Here is how event-logging works in OS 9: checking the Show Events checkbox sets a log-level value to 1—whenever this value is greater than 0, the Event Log displays Apple events. The start log statement increases this value by 1. The stop log statement decreases the log-level value by 1. So if the log-level value was 1 to begin with, using the stop log statement will stop displaying Apple events until the code reaches a start log statement.

The following OS 9 program in Example 2-3 stops logging Apple events until the final two statements of a tell code block.

Example 2-3. Using stop log and start log

tell application "Finder"
   stop log
   count (every file of folder "today" of desktop)
   start log
   set filecount to¬
      does not start with "a")) 
   log (filecount)
end tell

Since the stop log statement reduces the log-level value to 0, it prevents Event Log from displaying Apple events until the start log statement appears.

2.1.4.2 Result window

Typing Command-L or using the Controls menu displays the Result window. The sole purpose of this window is to display the result of the last operation in a script you execute. Sometimes this is the only information a programmer needs. An example of a Result window is shown in Figure 2-9.

Figure 2-9. Result window in OS X

For example, type current date by itself in a new script window, then run the script. The Result window will display something like:

date "Saturday, October 7, 2000 3:18:20 PM"