TITLE
    AppleScript: Using AppleScript Documentation
Article ID:
Created:
Modified: 		17036
1/18/95
3/18/99
TOPIC

    This article contains the Using AppleScript Documentation supplied with versions of AppleScript shipped as part of the Macintosh Operating System.

DISCUSSION

    Contents

    Preface
    Welcome to AppleScript
    What is AppleScript?
    About this guide
    Balloon Help
    Where to go from here

    Section I
    Using the Script Editor
    Opening a script
    Recording a script
    Editing a script
    Checking the syntax of a script
    Formatting a script
    Saving a script
    Saving a script without compiling it
    Save options for script applications
    Saving a script as run-only
    Running a script
    Viewing AppleScript terms
    Using different scripting systems
    Using different AppleScript dialects
    Displaying the Result window
    Pasting an object reference into a script

    Section 2
    Script Editor Command Reference
    File menu
    Edit menu
    Controls menu
    Font and Style menus


    Preface

    Welcome to AppleScript
    This manual is your introduction to the AppleScript application program. Use it to begin working with AppleScript. You can use AppleScript on Macintosh computers that use system software version 7.0 or later. If you're new to the Macintosh, read the information that came with your computer before you install the AppleScript application program. You'll need to know basic Macintosh operations and vocabulary to use AppleScript.


    What is AppleScript?
    When you use your Macintosh computer, you use the mouse and keyboard to open documents and application programs, move documents and file folders, enter information, print, and perform any other actions you want. AppleScript gives you a whole new way to work: You can give the computer a list of things you want it to do*a script*and let the computer do everything on your list.

    You can create a script by simply turning on the recorder and performing a set of actions. AppleScript keeps a list of what you do while the recorder is turned on. When you turn the recorder off, you can see the recorded script. When you run the script, your computer repeats your actions automatically.

    You can use the Finder and many application programs with AppleScript. Scripts can make the Finder or the program do many things for you. For example, a script might format a letter the way you want, save it in a particular folder, and print it.

    You can also use AppleScript to combine the capabilities of application programs. For example, a script might use the calculation capabilities of a spreadsheet and the formatting capabilities of a word processor to assemble an invoice.


    Scriptable application programs and the Scriptable Finder
    You can create scripts to control any scriptable application programs you have installed on your Macintosh. An application is scriptable when you can use AppleScript to control it. Many Macintosh programs are scriptable. If you're not sure your program is scriptable, contact the program's manufacturer for information.

    With system software version 7.5, the Finder (inside the System Folder) is scriptable. When you begin working with the Script Editor, you can use the Finder to try recording and playing a script.


    About this guide
    This guide tells you how to use the Script Editor to record scripts and how to change a script to do something different. The Script Editor is an application program you use to open and run scripts, make new scripts by recording or writing them, and save scripts. You don't need to know how to write computer programs to do anything described in this manual.


    Balloon Help
    You can use Balloon Help with the application program that come with AppleScript (the Script Editor). Choose Show Balloons from the Guide menu (near the right end of the menu bar).

    Note: When you point to any feature of the Script Editor application program, a balloon appears explaining the feature.


    Where to go from here
    For more information about using the Script Editor to work with scripts, open the file called "Using AppleScript part 2" to see Chapter 1 ("Using the Script Editor") and Chapter 2 ("Script Editor Command Reference").

    If you wish to create more complex scripts, see an authorized Apple dealer for information about the AppleScript Scripter's Kit. The Scripter's Kit contains additional AppleScript software and manuals.


    Section 1

    Using the Script Editor
    Use this chapter to find out how to use the Script Editor to:
    • open scripts that have been saved
    • record new scripts
    • make changes in scripts you record
    • check scripts for errors
    • format scripts
    • save scripts in several formats (that is, as different kinds of documents)
    • run scripts
    • view the AppleScript terms you can use with a scriptable application
    • use different scripting systems
    • use different AppleScript dialects
    • display the Result window
    • paste an object reference into a script
    The instructions in this chapter assume that the Script Editor is active and that you have at least one script and the Scriptable Finder on your hard drive.


    Opening a script
    You can use the Script Editor to open any script except those that have been saved as run-only scripts. (For more information about formats for saving scripts, see "Saving a Script" later in this chapter.)

    To open a script, follow these steps:
      1. Choose Open Script from the File menu.
      2. In the dialog box that appears, select the script you want to open and click Open.
    You can open one of the scripts in the Automated Tasks folder (inside the AppleScript folder). The script appears in a new script window.


    Recording a script
    You can use the Script Editor to record a series of actions. You can only record actions in a recordable application. For example, you can't record anything you do in SimpleText, because SimpleText isn't scriptable or recordable. In system software version 7.5, the Finder (inside the System Folder) is scriptable and recordable.

    An application is scriptable when you can use AppleScript to control it. It is recordable when you can use the recorder with it. An application can be scriptable without being recordable.

    Not all actions are recorded. If you move the mouse in circles, for example, it won't be recorded in your script. That's because moving the mouse doesn't result in a change in your document. The recorder records only things you do that change your document in some meaningful way. For example, typing a message in a text window is a meaningful change, because it makes something about the document different. Saving a file also results in a meaningful change. Clicking somewhere in the document doesn't result in a change in the document and isn't recorded.

    To start recording your actions as a script:
    • Open the File menu and choose New Script.
    • Click the Record button in the active script window. (You can also choose Record from the Controls menu.)
    • Open a scriptable application and perform the actions you want to record.
    To stop recording:
      1. Click the script window to make it active (or choose Script Editor from the Application menu).
      2. Click the Stop button.
    You can also choose Stop from the Controls menu.


    Editing a script
    You can edit a script much as you would edit any text document on your Macintosh computer. The editing actions you can take include:
    Action
    Result
    Click Places an insertion point in the text at the location you clicked.
    Click and drag Selects the portion of the script you drag across.
    Double-click Selects a word.
    Triple-click Selects an entire line.
    Press arrow key Moves the insertion point in the direction of the arrow.
    Option*Left Arrow key Moves the insertion point to the beginning of the line.
    Option*Right Arrow key Moves the insertion point to the end of the line.
    Option*Up Arrow key Moves the insertion point to the beginning of the script.
    Option*Down Arrow key Moves the insertion point to the end of the script.
    Option*Return Inserts a line continuation character (*).
    Shift*Return Moves the insertion point to the beginning of the next line.



    Checking the syntax of a script
    You can use the Script Editor to check the syntax of a script. If the syntax is correct, the script is then compiled.

    When you record a script and don't make any changes to it, the Check Syntax button is not available. This is because the Script Editor does not record scripts with incorrect syntax. When you make a change to a recorded script, or when you write a script, you can use the Check Syntax button.

    When you write a script, all of the terms you type appear in the same font and size (the default is 10-point Courier). When you check the syntax, the Script Editor applies different fonts, sizes, styles, and colors to the different kinds of terms in your script. You can choose the formatting applied to the terms in your script. To find out how to make changes to script formatting, see the next section, "Formatting a Script."

    To check the syntax of a script:

    Click the Check Syntax button in the script window.

    The Script Editor identifies the first syntax error it finds for you by selecting the text that appears to contain the error. When the Script Editor finds a syntax error in a script, it does not apply any formatting to the script.

    If the syntax of the script is correct, the Script Editor compiles the script.

    Checking syntax won't find all the problems a script can have, but it will identify AppleScript expressions that are put together incorrectly. A script containing syntax errors can be saved only as text, not as a compiled script or script application.


    Formatting a script
    ===================
    Scripts have a number of different parts, including operators such as "+" and "=," keywords, comments, and more. The Script Editor keeps track of these different parts for you, and applies formatting to help you identify them.

    You can change the fonts, sizes, styles, and colors used for parts of scripts. The changes you make apply to all of your scripts, not just the active script.

    To change script formatting:
      1. Choose AppleScript Formatting from the Edit menu.
      2. In the dialog box that appears, click a script element to select it.
      3. Use the Font and Style menus to choose a font, size, style, and color for the script element you selected.
    The following table describes the kinds of terms you can format.
    Category
    What It Means
    New text Any portion of a script you type before saving, running, or checking syntax, or an entire script that will not compile due to syntax errors.
    Operators Operators perform actions ("operate") on values. For example, the "+" operator adds two values together.
    Language keywords The scripting terms built into AppleScript and available to all scripting applications.
    Application keywords The scripting terms specific to an application.
    Comments Explanations about things in your script. You can use them yourself and for people who read your scripts. The computer ignores comments.
    Values A kind of data (information) that AppleScript can use. Numbers and words can be values.
    Variables Terms that are used as containers for values (such as a number or a word).
    References Phrases that specify an object that a script can identify. For example, "word 2 of document 1" is a reference. Reference formatting is applied only in the Result window, not in the script window.



    To format a script you must use the AppleScript Formatting command; you can't select part of a script and choose an item from the Font or Style menus. This is so that the formatting is consistent throughout the whole script. You can, however, use the Font and Style menus to format text in the description area of the script window. If you save the script as an application, the formatting you apply to its description appears in the script's startup screen.

    In addition to formatting your script by choosing fonts, sizes, styles, and colors, the Script Editor automatically indents some lines of your scripts. All lines within compound statements are indented. (A compound statement is one that takes up more than one line and includes other statements within it.)

    You can use the Tab key to indent lines in your scripts. If you use the Tab key in the middle of a line, however, the tab will be replaced by a space when you check syntax.

    To indent your scripts automatically, press Return at the end of each line.

    To force the next line of your script to begin at the left margin, hold down the Shift key and press Return.

    Lines in a script are sometimes too long to fit in the active window. You can make a line shorter by breaking it up into two lines with the continuation character. To insert a continuation character into a line in your script, hold down the Option key and press Return. A line broken into two or more lines with a continuation character is treated as a single line when you run your script.


    Saving a script
    You can save a script as one of three kinds of document:
    • as a text file, for opening in the Script Editor or other Macintosh applications
    • as a compiled script, for opening in the Script Editor
    • as an application, for using by itself without the Script Editor
    You can also save a script in two run-only formats. See "Saving a Script As Run-Only" later in this chapter.

    To save a script:
      1. Choose Save or Save As from the File menu.
      2. In the dialog box that appears, choose a location, specify a name, and choose a format for the script.
      3. Click Save.

    Saving a script without compiling it
    When you save a script, it is usually compiled before it is saved. To save a script without compiling it:
    • Hold down the Shift key while choosing Save from the File menu.
    The Save dialog box appears, but you can only save the script as a text document.


    Save options for script applications
    When you save a script as an application, two additional buttons appear in the dialog box:
    • Stay Open. Choose this option when you want your script to remain available after it runs (instead of quitting automatically). This can be useful when you want to send commands from another script to the open script.
    • Never Show Startup Screen. Choose this option when you don't want the startup screen to appear. The startup screen displays the description of the script you write in the top part of the Script Editor window.

    Saving a script as run-only
    You can save a script in a format that can be run but cannot be opened in the Script Editor (or any other application). This is called a run-only script.

    To save a script as run-only:
    • Choose Save As Run-Only from the File menu.
    • In the dialog box that appears, choose a location, specify a name, and choose a format for the script.
    • Click Save.
    Note: You can save run-only scripts as compiled scripts or as applications. You cannot save a run-only script as text.


    Running a script
    To run a script that's in the active script window: Click the Run button.

    You can also choose Run from the Controls menu.

    To stop a script that's running, press the Stop button (or hold down the command key and type a period).


    To run a script application
    Double-click the icon of the script application.

    You can force the script's startup screen to appear by holding down the Control key when you open the script application.


    Viewing AppleScript terms
    The Scriptable Finder and every scriptable application has its own dictionary, which is a set of AppleScript terms that you can use with it. You can open the Finder's dictionary or an application's dictionary in order to find out what terms are available and their syntax. To open a dictionary, follow these steps:
    • Choose Open Dictionary from the File menu. A dialog box appears in which you can select the Finder (inside the System Folder) or a scriptable application.
    • Select the Finder (inside the System Folder) or application you want and click Open. (The Dictionary window opens.)
    • To see the details about using a term, click it.
    The details for using the term appear in the window.

    A suite is a set of AppleScript terms that are related. The required suite is the most basic set of AppleScript terms. The standard suite is the set of terms that every scriptable application should support. Most scriptable applications (such as the Scriptable Finder also have their own suite of commands.

    The terms available in a dictionary are organized into suites. For example, the Finder Dictionary includes the required suite, the standard suite, and the Finder suite.


    Using different scripting systems
    You can use the Script Editor to write scripts for scripting systems other than AppleScript.

    A scripting system is software that lets you write scripts using a set of terms put together according to rules of syntax. AppleScript has one set of terms and syntactic rules. Other scripting systems offer different terms and rules.

    To use a different scripting system, you must first install the system. To find out how to install a specific scripting system, see the documentation that came with it. To use the Script Editor with an installed scripting system, choose the scripting system from the pop-up menu at the bottom of the Script Editor window.

    For more information about a scripting system you have on your Macintosh, see the information that came with the scripting system.


    Using different AppleScript dialects
    The examples in this guide are based on the English dialect of AppleScript. If you have the proper software installed on your Macintosh computer, you can use a different AppleScript dialect in the Script Editor.

    An AppleScript dialect is a version of AppleScript based on the words and syntax of a particular language (a human language or a computer language). The English dialect is based on the English language. AppleScript can resemble any language if there is an AppleScript dialect for that language.

    To choose a different AppleScript dialect, follow these steps:
      1. Choose AppleScript Formatting from the Edit menu.
      2. In the dialog box that appears, choose a dialect from the pop-up menu if more than one exists.
    Note: Be sure you understand the dialect you choose. When you choose a dialect, all the AppleScript terms in the Script Editor appear in that dialect. This can present problems if you don't understand the dialect.


    Displaying the Result window
    When a script runs, some of its expressions can produce an outcome or a result. For example, the expression "2+2" produces the result "4." When a script produces a result, it appears in the Result window. Some error messages also appear in the Result window.

    You can open the Result window at any time when you use the Script Editor.

    To open the Result window choose "Show Result" from the Controls menu.

    The Result window opens. If the open script ran and produced a result, the result appears in the window.


    Pasting an object reference into a script
    You can use the Paste Reference command (in the Edit menu) to paste an object reference into your script. An object reference is an AppleScript phrase that identifies an object in an application program. For example, the phrase "word 3 of document 1" identifies an object in the Scriptable Text Editor.

    To paste an object reference into your script, follow these steps:
    • Select an object in the Finder or in an application program. (For example, to select a Finder object you can click the icon for your startup disk.)
    • Choose Copy from the Edit menu.
    • Make a Script Editor window the active window. (You can choose Script Editor from the Application menu, or you can click an open Script Editor window.)
    • Choose Paste Reference from the Edit menu.

    The reference phrase is pasted into your script at the location of the insertion point. For example, you can paste the reference phrase for your startup disk (a Finder object.)

    You can paste references only from applications that support this particular feature. An application can be scriptable and recordable without allowing pasting of object references.


    Section 2

    Script Editor Command Reference

    File menu

    New Script - Opens a new script window in which you can write or record a new script.

    Open Script - Opens the script you select.

    Open Dictionary - Opens a window containing all the AppleScript

    terms you can use with an application program you select.

    Close - Closes the active window.

    Save - Compiles and saves the script in the active script window.
    If you have not saved the script before, you choose the format in which to save the script, the name, and the location.

    In the dialog box that appears, you can save a script in one of three formats:

    Compiled Script. This is the normal format. When you open a script saved as a compiled script, you see the script in the active script window of the Script Editor.

    Text. You can open a script saved as text in SimpleText or in most word-processing and text-editing application programs. This is the only format in which you can save a script that contains syntax errors.

    Application. This format saves your script as its own application program. When you open a script saved as an application, you see a window (or "startup screen") containing the description of the script. The description is the information you entered in the description area of the window for that script. When you click the Run button in the startup screen, the script runs. You do not see a script window for the script.

    When you save a script as an application, you have two additional choices: Stay Open and Never Show Startup Screen.

    If you check Stay Open, the script stays open after you run it (instead of closing automatically after it is run).

    If you check Never Show Startup Screen, the script runs immediately when you open it, rather than displaying its description first.

    Note: To save a script without compiling it, hold down the Shift key while you choose the Save command.

    Save As - Saves a copy of the script in the active script window.
    You specify a name and a location and choose the format in which to save the script. The new copy becomes the active script.

    Save As Run-Only - Saves a copy of the script in the active script window as a compiled script or an application that cannot be edited. You specify a name and a location in which to save it.

    Revert - Returns the script in the active script window to the way it was the last time you saved it. Any changes you made since the last time you saved the script are lost.

    Page Setup - Opens a dialog box in which you can choose page size, orientation, and other printing options. The options you can choose depend on the printer you have selected in the Chooser.

    Print - Prints the script in the active script window. The name of the script and its description are also printed. Different parts of the script are printed in the font, size, style, and color you choose in the AppleScript Formatting dialog box. (To open the AppleScript Formatting dialog box, choose AppleScript Formatting from the Edit menu.)

    Set Default Window Size - Sets the size of the active script window as the default. New script windows you open (by choosing New Script from the File menu) are automatically opened at the default size.

    Quit - Quits the Script Editor.


    Edit menu

    Undo - Reverses the effects of your last action. If you choose Undo while recording a script, the last line you see in the script window is removed.

    Cut - Removes selected text and places a copy on the Clipboard.

    Copy - Places a copy of selected text on the Clipboard.

    Paste - Places a copy of the text that's on the Clipboard at the location of the insertion point, in either the description area or the script area of the active script window.

    Clear - Removes selected text without placing a copy on the Clipboard.

    Paste Reference - Pastes an AppleScript expression from the Clipboard into the script area of the active script window, at the location of the insertion point. The AppleScript expression is a reference*a phrase that identifies something in an application program. For example, "startup disk of application Finder" is a reference that is used with the Scriptable Finder. You can use the Paste Reference command only with application programs that support it.

    Select All - Selects all the text in the description area or script area of the active script window, whichever contains the insertion point.

    AppleScript Formatting - Opens a dialog box in which you select the font, size, style, and color of text indicating various parts of scripts.


    Controls menu

    Record - Starts recording your actions as a script. Choosing Record is the same as clicking the Record button in the active script window.

    Run - Checks the script in the active script window for syntax errors, and if no errors are found, compiles and runs the script. Choosing Run is the same as clicking the Run button in the active script window.

    Stop - Stops the script that is currently running.

    Show Result - Opens the Result window. The Result window displays the outcomes of some types of expressions in scripts. (For example, a script with the expression "2+2" would display "4" in the Result window.)


    Font and Style menus

    You use the Font and Style menus to change the font, size, style, and color of:

    * selected text in the description area of a script window
    * text indicating different parts of a script

    Any changes you make to the formatting of the text in the description area also appear in the startup screen when the script runs.

    To change the font, size, style, or color of selected text in the description area:

    1. Select the text in the description area of the active script window.

    2. Choose the font and size you want from the Font menu.

    3. Choose the style and color you want from the Style menu.


    To change the font, size, style, or color of text indicating different parts of scripts:

    1. Choose AppleScript Formatting from the Edit menu.

    2. In the window that appears, click to select one of the parts of a script.

    3. Choose the font and size you want from the Font menu.

    4. Choose the style and color you want from the Style menu.

    5. If you want, select another part of a script, then repeat steps 3 and 4.


Document Information
Product Area: Apple Software
Category: AppleScript
Sub Category: General Topics

Copyright © 2000 Apple Computer, Inc. All rights reserved.