Inside Macintosh: AppleScript Language Guide / Part 2 - AppleScript Language Reference

Chapter 8 - Handlers / Command Handlers for Script Applications

Run Handlers

All applications that are compatible with System 7 can respond to the Run command, even if they aren't scriptable. The Finder sends a Run command to an application whenever that application is not already running and one of the following actions occurs:

• The user double-clicks the application's icon.
• The user selects the application's icon and chooses Open from the File menu.
• The application's icon is in the Apple Menu Items folder and the user chooses it from the Apple menu.
• The application's icon is in the Startup Items folder and the user restarts
  the computer.

If the application is already running when one of these actions occurs, the application is activated but no commands are sent to it. If the application isn't running, the Finder launches the application and sends it a Run command. The application responds by performing the actions the user expects when the application first opens, such as opening an untitled document.

Like any other application, a script application receives a Run command whenever one of the actions just listed occurs. You can provide a handler for the Run command in a couple of ways. An implicit Run handler consists of all statements at the top level of a script except for property declarations, script object definitions, and other command handlers. An explicit Run handler, like any other handler, is enclosed within an on...end statement.

For example, the script that follows consists a property declaration, an increment command, a handler for the increment command, and a Tell statement. For the Tell statement to work, you have a Scriptable Text Editor document named Count Log open before you run the script. Each time you run the script, the value of the property x increases by 1 and the increase is recorded in the Count Log.

property x : 0

increment() 

on increment()
   set x to x + 1
   display dialog "Count is now " & x & "."
end increment

tell document � 
   "Count Log" of application "Scriptable Text Editor"
   set selection to "Count is now " & x & "." & return
end tell

The implicit Run handler for this script consists of the statement increment() and the Tell statement. If you store this script in a script application and then double-click the script application's icon, the Finder sends a Run command
to the script, and the Run command invokes the two statements in the implicit Run handler.

The script in the preceding example behaves exactly the same way if you rewrite it with an explicit Run handler, like this:

property x : 0

on run
   increment()
   tell document �
      "Count Log" of application "Scriptable Text Editor"
      set selection to "Count is now " & x & "." & return
   end tell
end run

on increment()
   set x to x + 1
   display dialog "Count is now " & x & "."
end increment

The Run handlers in the preceding examples respond the same way to a Run command whether the script is saved as a script application or as a compiled script. If the script is saved as a compiled script, you can invoke its Run handler by clicking the Run button in the Script Editor.

Note

A script can't include both a implicit and an explicit Run handler. If a script includes both an explicit on run handler and top level commands that constitute an implicit Run handler, AppleScript returns an error when you try to compile the script--that is, when you try to run it, check its syntax, or attempt to save it.

The implicit Run handler allows a user to execute top-level statements
in a script application by launching it from the Finder. For example, if a
script application whose script consists only of the word

beep

is not already open and a user double-clicks its icon, the script application launches and (after optionally displaying a startup screen) beeps.

By default, a startup screen appears before the script runs. The user must click the startup screen's Run button or press the Return key before the Finder actually sends the Run command. This allows the user to read the description of the script before running it. If the Never Show Startup Screen checkbox is selected in the Script Editor's Save As dialog box when the script application is created, the script runs immediately without displaying the startup screen.

You can also send a Run command to a script application from within another script. For information about how to do this, see "Calling a Script Application" on page 251.