Syntax

Tell app "SoundJam MP"
   (* code statements *)
end tell

Description

The tell compound statement identifies the target of an AppleScript command or Apple event (as in tell app "Photoshop 5.5") followed by other AppleScript statements and an end tell. The tell compound statement can enclose any number of AppleScript statements, including other tell statements and flow-control structures such as if or repeat. You can identify any object in a tell statement, but unless the object is an application object such as FileMaker Pro or QuarkXPress, it has to be nested within another tell statement targeting the object's parent application. For example, if you want to use a statement such as:

tell window 1 to close

then you would have to first target the application that "owns" the window, as in the following example:

tell application "BBEdit 5.0"
   (* hasChanged will be true or false *)
   set hasChanged to (front window's modified)
   if hasChanged then
      tell front window to close saving yes
   else
      tell front window to close
   end if
end tell

This script first finds out whether the front BBEdit window has been modified, and it stores this boolean value (true or false) in the hasChanged variable. If true, then a tell simple statement sends the front BBEdit window a close command (with a parameter instructing BBEdit to save the changes). If this tell statement was not nested within the tell app "BBEdit"... statement, then AppleScript would not know which application's window the script was talking about, and an error would be raised. You could also write the program without a nested tell statement, as in this code:

tell application "BBEdit 5.0"
   set hasChanged to (front window's modified)
   if hasChanged then
      close front window saving yes  (* send BBEdit the close command
      without another tell statement *)
   else
      close front window
   end if
end tell

With a feature that was new to AppleScript 1.4, you can add aliases to applications in the Scripting Additions folder of the System Folder. Give these aliases a short, easy-to-recall name like "fm" for FileMaker Pro, and you no longer have to spell out the app's name in the tell statement. You can just use the syntax tell app "fm"..., and AppleScript will find the application.

You can also use the predefined variables me, my, and it within tell statements. AppleScript assumes that any command such as activate, close, or open within a tell statement should be directed to the application that is identified in the tell statement. The exceptions are:

• A nested tell statement that targets a different application; in this case, any commands that are issued within this nested tell are directed to its target app.

• A scripting addition or osax command, such as display dialog or round, can be issued within a tell statement in most cases without any qualifying or accompanying code requirements.

• Commands that are qualified with the my or of me reserved words. This tells AppleScript that the command is a script command, as in:

set theTruth to my func(  )

• Commands that target the app identified in the tell statement.

• Commands that are associated with a script object.

Examples

The script at the end of this section calls the script's own function inside of a tell statement. It also calls a function defined by a script object. it is an AppleScript reserved word that refers to the default target of Apple events, which is normally identified in a tell statement (Chapter 1,describes Apple events). This script is a little bigger than most included in the chapter, and I apologize to those like me who are partial to the use of only code fragments as examples. But it illustrates an important element of how you work with tell statements—the visibility of commands.

The script first identifies the text editor BBEdit in the compound tell statement, then tells this app to make a new window. The next line sets a firstLine variable to the return value of a function call:

InnerScript's getIntro(  )

Without the reference to the script object InnerScript, AppleScript would assume that the getIntro function was a BBEdit command, because getIntro is called inside of a tell app "BBEdit 5.0" statement. However, the script code indicates that this is the getIntro function of the InnerScript object. The following code would also work:

set firstLine to getIntro(  ) of InnerScript

If you look down to the definition of the InnerScript script object, you see that it defines a function (getIntro) that returns the value of InnerScript's Intro property, which is a string: "I'm the first sentence." A lot is going on in the if statement in the next example:

if (my addLine(firstLine)) then display dialog "Text added¬
successfully:  " & its name

The script calls its own function (as opposed to a BBEdit command) called addLine. The reserved word my distinguishes this function (addLine) as defined by the script, not BBEdit, so AppleScript looks for the function definition in the script itself, rather than in BBEdit's dictionary. The following phrase would also work:

addLine(firstLine) of me

The function inserts text into a BBEdit document and returns true if successful. The if statement responds to any true return value from the addLine function by displaying a message string that includes its name. It is an AppleScript constant that refers to the default target for commands, which, inside this tell statement, is BBEdit. So its name returns "BBEdit 5.0":

tell application "BBEdit 5.1"
   make new window with properties {name:"Front Win"}
   (* the InnerScript script object is defined beneath this code *)
   set firstLine to InnerScript's getIntro(  )
   (* addLine is the 'outer script's' function, not InnerScript's *)
   if (my addLine(firstLine)) then display dialog¬
"Text added  successfully: " & its name
end tell

(* user-defined function addline(  ) *)
on addLine(txt)
   try
      tell application "BBEdit 5.1" to insert text txt
   on error
      return false
   end try
   return true
end addLine
(* script object definition *)
script InnerScript
   property Intro : "I'm the first sentence."
   on getIntro(  )
      return Intro
   end getIntro
end script