Apple AppleScript Scripting User Manual

AppleScript Scripting
Additions Guide

English Dialect

Apple Computer, Inc.

© 1996 Apple Computer, Inc.
All rights reserved.

No part of this publication or the
software described in it may be
reproduced, stored in a retrieval
system, or transmitted, in any form
or by any means, mechanical,
electronic, photocopying, recording,
or otherwise, without prior written
permission of Apple Computer, Inc.

Printed in the United States of
America.

The Apple logo is a trademark of
Apple Computer, Inc. Use of the
“keyboard” Apple logo (Option­Shift-K) for commercial purposes
without the prior written consent of
Apple may constitute trademark
infringement and unfair competition
in violation of federal and state laws.

No licenses, express or implied, are
granted with respect to any of the
technology described in this book.
Apple retains all intellectual
property rights associated with the
technology described in this book.
This book is intended to assist
application developers to develop
applications only for Apple
Macintosh computers.

Apple Computer, Inc.
20525 Mariani Avenue
Cupertino, CA 95014
408-996-1010

Apple, the Apple logo, AppleShare,
AppleTalk, HyperCard, HyperTalk,
LaserWriter, Macintosh, and MPW
are trademarks of Apple Computer,
Inc., registered in the United States
and other countries.

AppleScript, Finder, QuickDraw,
and ResEdit are trademarks of
Apple Computer, Inc.

Adobe Illustrator and PostScript are
trademarks of Adobe Systems
Incorporated, which may be
registered in certain jurisdictions.

FrameMaker is a registered
trademark of Frame Technology
Corporation.

Helvetica and Palatino are
registered trademarks of Linotype
Company.

ITC Zapf Dingbats is a registered
trademark of International Typeface
Corporation.

Microsoft is a registered trademark
of Microsoft Corporation.

Simultaneously published in the
United States and Canada.

LIMITED WARRANTY ON MEDIA
AND REPLACEMENT

If you discover physical defects in the
manuals distributed with an Apple
product, Apple will replace the manuals
at no charge to you, provided you return
the item to be replaced with proof of
purchase to Apple or an authorized
Apple dealer during the 90-day period
after you purchased the software. In
addition, Apple will replace damaged
manuals for as long as the software is
included in Apple’s Media Exchange
program. See your authorized Apple
dealer for program coverage and details.
In some countries the replacement
period may be different; check with
your authorized Apple dealer.

ALL IMPLIED WARRANTIES ON
THIS MANUAL, INCLUDING
IMPLIED WARRANTIES OF
MERCHANTA­BILITY AND FITNESS FOR A
PARTICULAR PURPOSE, ARE
LIMITED IN DURATION TO NINETY
(90) DAYS FROM THE DATE OF THE
ORIGINAL RETAIL PURCHASE OF
THIS PRODUCT.

Even though Apple has reviewed this
manual, APPLE MAKES NO
WARRANTY OR REPRESENTATION,
EITHER EXPRESS OR IMPLIED, WITH
RESPECT TO THIS MANUAL, ITS
QUALITY, ACCURACY, MERCHANTA­BILITY, OR FITNESS FOR A PARTIC­ULAR PURPOSE. AS A RESULT, THIS
MANUAL IS SOLD “AS IS,” AND
YOU, THE PURCHASER, ARE
ASSUMING THE ENTIRE RISK AS TO
ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE
LIABLE FOR DIRECT, INDIRECT,
SPECIAL, INCIDENTAL, OR
CONSEQUENTIAL DAMAGES
RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS MANUAL,
even if advised of the possibility of such
damages.

THE WARRANTY AND REMEDIES
SET FORTH ABOVE ARE EXCLUSIVE
AND IN LIEU OF ALL OTHERS, ORAL
OR WRITTEN, EXPRESS OR IMPLIED.
No Apple dealer, agent, or employee is
authorized to make any modification,
extension, or addition to this warranty.

Some states do not allow the exclusion
or limitation of implied warranties or
liability for incidental or consequential
damages, so the above limitation or
exclusion may not apply to you. This
warranty gives you specific legal rights,
and you may also have other rights
which vary from state to state.

Contents

Figures, Tables, and Listings vii

Preface

Chapter 1

Chapter 2

About This Guide

Audience ix
Organization of This Guide ix
Sample Applications and Scripts x
For More Information x

Getting Started x
AppleScript Language x
Other AppleScript Dialects x
Information for Programmers xi

Conventions Used in This Guide xi

ix

Introduction to Scripting Additions

Installing Scripting Additions 1
Sending Scripting Addition Commands 2

Scripting Addition Commands

Scripting Addition Files 5
Command Definitions 8

Activate 8
ASCII Character 10
ASCII Number 11
Beep 13
Choose Application 14
Choose File 16
Choose Folder 18
Close Access 19
Current Date 21

5

1

iii

Display Dialog 22
Get EOF 27
Info For 28
List Disks 32
List Folder 33
Load Script 34
Log 36
New File 37
Offset 39
Open for Access 41
Path To 43
Random Number 46
Read 48
Round 54
Run Script 55
Scripting Components 57
Set EOF 58
Start Log 60
Stop Log 62
Store Script 63
Time to GMT 66
Write 68

Using Read/Write Commands 70

Chapter 3

iv

Writing Scripting Additions

Types of Scripting Additions 85

Apple Event Handler Scripting Addition 86

Apple Event Coercions Scripting Addition 87
The Scripting Addition Size Resource 89
Using Other Resources With Scripting Additions 91
Using Records for Scripting Addition Reply Values 91
Scripting Addition Limitations 93
Sample Scripting Addition 93

85

Appendix

Scripting Additions at a Glance

Scripting Addition Commands 105
Placeholders 110

105

Index

113

v

Figures, Tables, and Listings

Chapter 1

Chapter 2

Chapter 3

Introduction to Scripting Additions

Figure 1-1

A scripting addition icon 1

Scripting Addition Commands

Figure 2-1
Figure 2-2
Figure 2-3
Figure 2-4
Figure 2-5
Figure 2-6
Figure 2-7

Table 2-1

Listing 2-1
Listing 2-2
Listing 2-3
Listing 2-4

Writing Scripting Additions

A Choose Application dialog box 14
A Choose File dialog box 16
A Choose Folder dialog box 18
A Display Dialog dialog box 23
Alert icons 26
A New File dialog box 38
The Script Editor’s Event Log window 61

Scripting addition commands described in this guide 6

Reading a specific record from a text-based database file 72
Deleting a record from a text-based database file 74
Inserting a record in a database file 77
Opening a file for write access and creating one if the file

doesn’t exist 82

85

1

5

Appendix

Listing 3-1
Listing 3-2
Listing 3-3

Resource type declaration for the
Classes array for a scripting addition that returns a record 92
Play Sound scripting addition 94

Scripting Additions at a Glance

Table A-1

Table A-2

Command syntax for standard AppleScript scripting
additions 106

Placeholders used in syntax descriptions 110

105

'osiz'

resource 89

vii

P R E F A C E

About This Guide

The

AppleScript Scripting Additions Guide: English Dialect

additions that accompany the AppleScript English dialect of the AppleScript
language. Scripting additions are files that extend the capabilities of the
AppleScript language by providing additional commands you can use
in scripts.

Audience 0

This guide is for anyone who wants to write new scripts or modify existing
scripts. It also provides some basic information for Macintosh software
developers who want to write scripting additions.

describes the scripting

Before using this guide, you should read
learn what hardware and software you need to use AppleScript; how to
install AppleScript; and how to run, record, and edit scripts. You should
also be familiar with the
to throughout the rest of this book as the
describes the English dialect of the AppleScript scripting language.

Macintosh software developers who want to write scripting additions should
also refer to

Inside Macintosh: Interapplication Communication

AppleScript Language Guide: English Dialect

Getting Started With AppleScript

(referred

AppleScript Language Guide

.

), which

to

Organization of This Guide 0

This guide contains these chapters:

■

Chapter 1, “Introduction to Scripting Additions,” introduces scripting
additions and the use of their commands.

■

Chapter 2, “Scripting Addition Commands,” describes the commands
provided by the standard scripting additions that come with AppleScript.

■

Chapter 3, “Writing Scripting Additions,” provides information for
programmers who wish to write scripting additions.

ix

P R E F A C E

At the end of the guide are one appendix and an index.

■

The appendix, “Scripting Additions at a Glance,” summarizes the
commands defined by the standard scripting additions.

Sample Applications and Scripts 0

A sample application, the Scriptable Text Editor, is included with AppleScript.
The Scriptable Text Editor is scriptable; that is, it understands scripts written in
the AppleScript language. It also supports recording of scripts: when you use
the Record button in the Script Editor (the application you use to write and
modify scripts), the actions you perform in the Scriptable Text Editor generate
AppleScript statements for performing those actions. Scripts for performing
tasks in the Scriptable Text Editor are used as examples throughout this guide.

For More Information 0

Getting Started 0

See the companion book
and software you need to use AppleScript; how to install AppleScript; and how
to run, record, and edit scripts.

Getting Started With AppleScript

to learn what hardware

AppleScript Language 0

See the companion book
about the commands and other terms provided by the English dialect of the
AppleScript scripting language and by the Scriptable Text Editor application.

AppleScript Language Guide

for complete information

Other AppleScript Dialects 0

A

dialect

is a version of the AppleScript language that resembles a particular
human language or a programming language. Each AppleScript dialect has
a corresponding set of standard scripting additions for that dialect. This guide

x

P R E F A C E

describes the terms defined by the standard scripting additions that come
with the AppleScript English dialect. Scripting additions intended for use with
other dialects work the same way but define terms and syntax appropriate for
those dialects.

Information for Programmers 0

If you are an experienced programmer and you want to write your own
scripting additions, you should be thoroughly familiar with the Apple Event
Manager, Apple event terminology resources, and the standard suites of Apple
events. For information about the Apple Event Manager and Apple event
terminology resources, see
definitions of the standard suites, see the

Inside Macintosh: Interapplication Communication.

Apple Event Registry: Standard Suites.

For

Conventions Used in This Guide 0

Words and sample scripts in
elements that must be typed exactly as shown.

Here are some additional conventions used in syntax descriptions:

language element

Plain computer font indicates an element that you must
type exactly as shown. If there are special symbols (for
example, + or &), you must also type them exactly as
shown.

placeholder

[

optional

(

a group

[

optional

]

)

]...

Italic text indicates a placeholder that you must replace
with an appropriate value. (In some programming
languages, placeholders are called nonterminals.)

Brackets indicate that the enclosed language element or
elements are optional.

Parentheses group together elements. If parentheses are
part of the syntax, they are shown in bold.

Three ellipsis points (. . .) after a group defined by
brackets indicate that you can repeat the group of
elements within brackets 0 or more times.

monospaced font

are AppleScript language

xi

P R E F A C E

(

a group). . . Three ellipsis points (. . .) after a group defined by

parentheses indicate that you can repeat the group of
elements within parentheses one or more times.

a | b | c Vertical bars separate elements in a group from which

you must choose a single element. The elements are
often grouped within parentheses or brackets.

xii

CHAPTER 1

Figure 1-0
Listing 1-0
Table 1-0

Introduction to Scripting Additions 1

Scripting additions are files that extend the capabilities of the AppleScript
language by providing additional commands or coercions you can use in
scripts. They are similar to XCMDs and XFCNs in HyperTalk.

This chapter describes how to install scripting additions and briefly describes
how scripting addition commands work. For more information about the
differences between scripting addition commands, application commands,
AppleScript commands, and user-defined commands, see Chapter 4,
“Commands,” of the

Installing Scripting Additions 0

When you install AppleScript using the Installer as described in

Started With AppleScript,

(which is located inside the System Folder for your computer) called Scripting
Additions and copies a number of scripting addition files into that folder.
The file type of a scripting addition (displayed in the Get Info window) is
“AppleScript document.”

AppleScript Language Guide.

Getting

the Installer creates a folder in the Extensions folder

Figure 1-1 shows a scripting addition icon. For a list of the scripting additions
installed with AppleScript and the commands they provide, see Table 2-1 on
page 6.

Figure 1-1

Installing Scripting Additions

A scripting addition icon

1

CHAPTER 1

Introduction to Scripting Additions

Each scripting addition file contains one or more command handlers. If a
scripting addition file is located in the Scripting Additions folder (in the
Extensions folder of the System Folder), the command handlers it provides are
available for use by any script whose target is an application on that computer.

Some scripting additions also define object classes for records returned by their
commands. However, scripting addition commands do not normally act on
objects defined by individual applications.

The scripting addition commands Activate, Log, Start Log, and Stop Log are
part of the AppleScript extension and do not have separate files in the Scripting
Additions folder. With the exception of these commands, AppleScript
recognizes scripting addition commands only if the corresponding scripting
addition files are located in the Scripting Additions folder. If after installing
AppleScript you receive additional scripting additions from Apple or another
vendor, you must copy them into the Scripting Additions folder before you can
use their commands in scripts.

If you use a scripting addition command in a script and get an error message
stating that the command is undefined, check to make sure the corresponding
scripting addition is installed in the Scripting Additions folder.

Sending Scripting Addition Commands 1

Like the target of an application command, the target of a scripting addition
command is always an application object or a script object. If the script
doesn’t explicitly specify the target with a Tell statement, AppleScript sends
the command to the default target application, which is usually the application
running the script (for example, the Script Editor).

A scripting addition command performs its action only after the command has
been received by a target application. Unlike application commands, scripting
addition commands always work the same way regardless of the application to
which they are sent.

For example, the scripting addition command Display Dialog displays a dialog
box that can include text, one or more buttons, an icon, and a field in which the
user can type text. In the script that follows, the target of the Display Dialog
command is the Scriptable Text Editor application. When the script runs, the

2

Sending Scripting Addition Commands

CHAPTER 1

Introduction to Scripting Additions

Scriptable Text Editor becomes the frontmost application (that is, its menus
become visible and its windows become the frontmost windows on the screen)
and passes the command to the scripting addition’s handler for the Display
Dialog command, which displays the dialog box.

tell application "Scriptable Text Editor"

display dialog "What’s your name?" default answer ""

end tell

In the next example, the Display Dialog command is not enclosed in a Tell
statement, nor does it have a direct parameter, so its target is the Script Editor
(or whatever application runs the script). When you run the script, the Script
Editor passes the command to the scripting addition’s handler for the Display
Dialog command, which displays the dialog box in the Script Editor’s layer
(that is, in front of any other Script Editor windows that may be open) while
the Script Editor is still the active application.

set theCount to number of words in front document of

¬

app "Scriptable Text Editor"

if theCount > 500 then

display dialog "You have exceeded your word limit."

end

You can send scripting addition commands to a target on any remote computer
whose Scripting Additions folder contains the appropriate scripting addition
file. This is true no matter which scripting additions are available to the
computer from which you are sending the command. For example, you can
send the Display Dialog command to any application on a remote computer
whose Scripting Additions folder contains the Display Dialog scripting
addition, even if the Scripting Additions folder on your computer doesn’t
contain that file.

Each scripting addition that contains command handlers has its own
dictionary, which lists the reserved words—including the command
names, parameter labels, and in some cases object names—used to invoke
the commands supported by the scripting addition. If a scripting addition
dictionary includes words that are also part of an application dictionary,
then you cannot use those words within Tell statements to that application.

Sending Scripting Addition Commands

3

CHAPTER 1

Introduction to Scripting Additions

For example, the Offset command provided by the String Commands scripting
addition reports the offset, in characters, of a string within another string.
Offset is also a property of several Scriptable Text Editor objects and is thus a
word in the Scriptable Text Editor dictionary. Therefore, you cannot use Offset
as a scripting addition command within Tell statements to the Scriptable Text
Editor. If you do, you’ll get a syntax error, because the Scriptable Text Editor
treats the word Offset as a property of a text object.

If you specify a script object as the target of a scripting addition command,
the script object either handles the command itself (potentially modifying it)
or uses a Continue statement to pass the command to the default target
application. For more information about scripting addition commands, script
objects, and the Continue statement, see Chapter 9, “Script Objects,” of the
AppleScript Language Guide.

4 Sending Scripting Addition Commands

CHAPTER 2

Figure 2-0
Listing 2-0
Table 2-0

Scripting Addition Commands 2

This chapter describes what the standard AppleScript scripting addition
commands do and how to use them in scripts. The first two sections summarize
the standard scripting addition files and the commands they provide. The last
section describes in more detail how to use the commands provided by the
Read/Write scripting addition, whose commands are usually used together.

Scripting Addition Files 2

The standard scripting addition files are copied into the Scripting Additions
folder (located in the Extensions folder in the System Folder) when you install
AppleScript according to the instructions in Getting Started With AppleScript.
Each file provides one or more commands. Table 2-1 summarizes the
commands provided by the standard scripting additions.

Each scripting addition that provides commands includes its own dictionary of
the commands and object classes it defines. You can open a scripting addition’s
dictionary in much the same way you open an application’s dictionary—
by selecting the scripting addition’s icon in the Scripting Additions folder,
dragging the icon over the Script Editor’s icon, and releasing the mouse button.

For information about commands provided by scripting additions other than
those described in this manual, see the documentation for those scripting
additions. For information about using command definitions and for
definitions of AppleScript commands and standard application commands, see
the AppleScript Language Guide.

Scripting Addition Files 5

CHAPTER 2

Scripting Addition Commands

Table 2-1 Scripting addition commands described in this guide

Name of
scripting addition file Name of command Description of command

Not a separate file;
part of AppleScript
extension

Activate Activates an application.

Log Places a string between comment

characters in the Script Editor’s
Event Log Window.

Start Log Turns logging on in the Script Editor’s

Event Log window.

Stop Log Turns logging off in the Script Editor’s

Event Log window.

Beep Beep Plays the alert sound.

Choose Application Choose Application Allows the user to choose a running

application from a dialog box.

Choose File Choose File Allows the user to choose a file from

a dialog box.

Choose Folder Allows the user to choose a folder

or volume from a dialog box.

Current Date Current Date Returns a date value that represents

the current time and date.

Display Dialog Display Dialog Displays a dialog box.

File Commands Info For Gets information for a file or folder.

List Disks Returns a list of currently

mounted disks.

List Folder Lists the contents of a specified folder.

Path To Returns full pathname to specified

folder or application.

6 Scripting Addition Files

continued

CHAPTER 2

Scripting Addition Commands

Table 2-1 Scripting addition commands described in this guide (continued)

Name of
scripting addition file Name of command Description of command

Load Script Load Script Loads a compiled script into the current

script as a script object.

New File New File Allows a user to create a new file.

Numerics Random Number Generates a random number.

Round Rounds a number to the nearest integer.

Read/Write
Commands

Close Access Closes a file opened with Open

for Access.

Get EOF Returns the offset, in bytes, of the end

of a specified file from the beginning
of the file.

Open for Access Opens a file for reading or writing using

Read or Write commands.

Read Reads data from file previously opened

with Open for Access command, or
opens file for access, reads data, and
closes file.

Set EOF Sets the end of a specified file.

Write Writes data to file previously opened

with Open for Access command, or
opens file for access, writes data, and
closes file.

Run Script Run Script Runs a specified script.

Scripting Components Scripting Components Returns a list of the scripting

components currently available.

Store Script Store Script Stores a specified script object in a

specified file.

continued

Scripting Addition Files 7

CHAPTER 2

Scripting Addition Commands

Table 2-1 Scripting addition commands described in this guide (continued)

Name of
scripting addition file Name of command Description of command

String Commands ASCII Character Converts a number to its

ASCII equivalent.

ASCII Number Returns the ASCII number

of a character.

Offset Determines the offset of a string

within another string.

Time to GMT Time to GMT Returns the difference, in seconds,

between the current time and
Greenwich mean time.

Command Definitions 2

The sections that follow are in alphabetical order by command name and
provide definitions for all the standard scripting addition commands. For
information about using command definitions, see Chapter 4, “Commands,”
of the AppleScript Language Guide.

Activate 2

The Activate command brings an application to the front (that is, its window
becomes the frontmost window on the desktop). If the application is on the
local computer, AppleScript opens the application if it is not already running. If
the application is on a remote computer, it must be running already.

Unlike most other scripting additions, the Activate command is built into
the AppleScript extension. It does not have a separate file in the Scripting
Additions folder.

8 Command Definitions

SYNTAX

PARAMETER

RESULT

EXAMPLES

CHAPTER 2

Scripting Addition Commands

activate referenceToApplication

referenceToApplication

A reference of the form application nameString (see “Notes”).
Class: Reference

None

set x to application "Scriptable Text Editor"
activate x

activate application ¬

"Mac HD:Applications:Scriptable Text Editor"

NOTES

tell application "Scriptable Text Editor"

activate

end tell

tell application "Scriptable Text Editor" to activate

The way you specify the name (nameString) of the application you want to
activate depends on whether the application is on a local or remote computer.

To specify an application on the local computer, use a string of the form
"Disk:Folder1:Folder2:...:ApplicationName". You can also specify a string
with only an application name ("ApplicationName"). In this case, AppleScript
attempts to find the application in the current directory.

Command Definitions 9

ERRORS

CHAPTER 2

Scripting Addition Commands

To specify an application on a remote computer, you must use a string that
consists of the name of the application as it would be listed in the Application
menu ("ApplicationName"), and you must also specify the name of the
computer and if necessary the zone in which the computer is located.
The application must be running. The Activate command does not launch
applications on remote machines.

For more information about references to applications, see Chapter 5, “Objects
and References,” of the AppleScript Language Guide.

Error
number Error message

–600 Application isn't running.

–606 Application is background-only.

ASCII Character 2

The ASCII Character command returns the ASCII character associated with a
specified number. It is one of several commands provided by the String
Commands scripting addition.

SYNTAX

ASCII character integer

PARAMETER

integer An expression that evaluates to an integer between 1 and 255.

Class: Integer

RESULT

The character that corresponds to the specified ASCII number.

10 Command Definitions

EXAMPLES

ERRORS

CHAPTER 2

Scripting Addition Commands

ASCII character 100

--result: "d"

ASCII character 101

--result: "e"

Error
number Error message

–108 Out of memory.

–1700 Can't make some data into the expected type.

–1701 Some parameter is missing for <commandName>.

–1704 Some parameter was invalid.

–1705 Operation involving a list item failed.

–1718 Reply has not yet arrived.

–1720 Invalid range.

ASCII Number 2

The ASCII Number command returns the ASCII number associated with a
specified character. It is one of several commands provided by the String
Commands scripting addition.

SYNTAX

ASCII number string

Command Definitions 11

PARAMETER

RESULT

EXAMPLES

ERRORS

CHAPTER 2

Scripting Addition Commands

string An ASCII character.

Class: String

The ASCII number that corresponds to the specified character.

ASCII number "d"

--result: 100

ASCII number "e"

--result: 101

Error
number Error message

–108 Out of memory.

–1700 Can't make some data into the expected type.

–1701 Some parameter is missing for <commandName>.

–1704 Some parameter was invalid.

–1705 Operation involving a list item failed.

–1715 Some parameter wasn't understood.

–1718 Reply has not yet arrived.

–1720 Invalid range.

12 Command Definitions

CHAPTER 2

Scripting Addition Commands

Beep 2

The Beep command plays the alert sound for the Macintosh. It is the only
command provided by the Beep scripting addition.

SYNTAX

beep [ numberOfBeeps ]

PARAMETER

numberOfBeeps

The number of times to play the alert sound. If you omit

numberOfBeeps, the alert sound is played once.
Class: Integer
Default Value: 1

RESULT

None

EXAMPLES

NOTES

beep
beep 3

The user can cancel a Beep command—for example, if the value of the
numberOfBeeps parameter is large—by typing Command-period or pressing
the Esc key.

Command Definitions 13

CHAPTER 2

Scripting Addition Commands

Choose Application 2

The Choose Application command allows the user to choose a running
application from a dialog box like the one shown in Figure 2-1.

Figure 2-1 A Choose Application dialog box

The dialog box displays applications on the current computer and on any
computer connected to the same network.

Choose Application is the only command provided by the Choose Application
scripting addition.

SYNTAX

choose application [ with prompt promptString ] ¬

[ application label appListLabel ]

14 Command Definitions

PARAMETERS

RESULT

CHAPTER 2

Scripting Addition Commands

promptString The prompt to be displayed in the dialog box. The prompt can

be up to 255 characters long, but the standard dialog box has
room for only about 50 characters. If you omit the with

prompt parameter, the string "Choose a program to
link to:" is displayed.

Class: String
Default Value: "Choose a program to link to:"

appListLabel The label above the list of applications displayed in the dialog

box. The label can be up to 255 characters long, but the standard
dialog box has room for only about 25 characters. If you omit
the application label parameter, the string "Programs"
is displayed.

Class: String
Default Value: "Programs"

A reference to the application specified by the user.

EXAMPLES

NOTES

choose application with prompt "Choose a spelling checker:"

tell (choose application with prompt ¬

"Choose a scriptable text editor:")

--other statements

end tell

If the user chooses the Cancel button, Display Dialog returns error –128. If you
want your script to continue after the user clicks Cancel, you must include an
error handler. For information about Tell statements and error handlers, see
Chapter 8, “Handlers,” of the AppleScript Language Guide.

Command Definitions 15

CHAPTER 2

Scripting Addition Commands

ERRORS

Error
number Error message

–108 Out of memory.

–128 User canceled.

Choose File 2

The Choose File command displays a dialog box like the one in Figure 2-2 to
allow the user to choose a file.

Figure 2-2 A Choose File dialog box

The Choose File command is one of two commands provided by the Choose
File scripting addition.

SYNTAX

choose file [ with prompt promptString ] [ of type listOfTypes ]

16 Command Definitions

PARAMETERS

RESULT

CHAPTER 2

Scripting Addition Commands

promptString The prompt to be displayed in the dialog box. The prompt can

be up to 255 characters long, but the standard dialog box has
room for only about 40 characters. If you omit the with
prompt parameter, no prompt is displayed.

Class: String
Default Value: (no prompt)

listOfTypes A list of the file types of the files to be displayed in the dialog

box. Each string is a four-character code for the file type, such as

"TEXT", "APPL", "PICT", or "PNTG". If you omit the of
type parameter, all files are displayed.

Class: List of strings; each string is a four-letter code
Default Value: (all file types displayed)

A reference of the form file "Disk:Folder1:Folder2:...:Filename" for the file
specified by the user, if any.

EXAMPLE

NOTES

ERRORS

choose file with prompt "Please choose a file:" of type ¬

{"TEXT", "APPL"}

open result

If the user clicks Cancel in the Choose File dialog box, AppleScript returns error
number –128. If you want your script to continue after the user clicks Cancel,
you must include an error handler. For information about Try statements
and error handlers, see Chapter 7, “Control Statements,” of the AppleScript

Language Guide.

Error
number Error message

–108 Out of memory.

–128 User canceled.

Command Definitions 17

CHAPTER 2

Scripting Addition Commands

Choose Folder 2

The Choose Folder command displays a dialog box like the one in Figure 2-3 to
allow the user to choose a directory (that is, a folder, a volume, or the desktop).

Figure 2-3 A Choose Folder dialog box

The Choose Folder command is one of two commands provided by the Choose
File scripting addition.

SYNTAX

choose folder [ with prompt promptString ]

PARAMETERS

promptString The prompt that appears in the dialog box. The prompt can be

up to 255 characters long, but the standard dialog box has room
for only about 80 characters. If you omit the with prompt
parameter, the string "Choose a folder:" is displayed.

Class: String
Default Value: "Choose a folder:"

18 Command Definitions