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, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR 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	About This Guide				ix
	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
Chapter 1	Introduction to Scripting Additions								1
	Installing Scripting Additions						1
	Sending Scripting Addition Commands							2
Chapter 2	Scripting Addition Commands							5
	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

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	Writing Scripting Additions						85
	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

iv

Appendix	Scripting Additions at a Glance				105
	Scripting Addition Commands			105
	Placeholders		110
	Index	113

v

Figures, Tables, and Listings

Chapter 1	Introduction to Scripting Additions				1
	Figure 1-1	A scripting addition icon				1
Chapter 2	Scripting Addition Commands			5
	Figure 2-1	A Choose Application dialog box						14
	Figure 2-2	A Choose File dialog box					16
	Figure 2-3	A Choose Folder dialog box					18
	Figure 2-4	A Display Dialog dialog box					23
	Figure 2-5	Alert icons	26
	Figure 2-6	A New File dialog box			38
	Figure 2-7	The Script Editor’s Event Log window							61
	Table 2-1	Scripting addition commands described in this guide								6
	Listing 2-1	Reading a specific record from a text-based database file									72
	Listing 2-2	Deleting a record from a text-based database file								74
	Listing 2-3	Inserting a record in a database file						77
	Listing 2-4	Opening a file for write access and creating one if the file
		doesn’t exist	82
Chapter 3	Writing Scripting Additions		85
	Listing 3-1	Resource type declaration for the 'osiz' resource								89
	Listing 3-2	Classes array for a scripting addition that returns a record									92
	Listing 3-3	Play Sound scripting addition					94
Appendix	Scripting Additions at a Glance				105
	Table A-1	Command syntax for standard AppleScript scripting
	Table A-2	additions	106
		Placeholders used in syntax descriptions							110

vii

P R E F A C E

About This Guide

The AppleScript Scripting Additions Guide: English Dialect describes the scripting 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.

Before using this guide, you should read Getting Started With AppleScript to 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 AppleScript Language Guide: English Dialect (referred to throughout the rest of this book as the AppleScript Language Guide), which 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.

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 Getting Started With AppleScript to learn what hardware and software you need to use AppleScript; how to install AppleScript; and how to run, record, and edit scripts.

AppleScript Language

0

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

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 Inside Macintosh: Interapplication Communication. For definitions of the standard suites, see the Apple Event Registry: Standard Suites.

Conventions Used in This Guide

0

Words and sample scripts in monospaced font are AppleScript language 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	Italic text indicates a placeholder that you must replace
	with an appropriate value. (In some programming
	languages, placeholders are called nonterminals.)
[optional]	Brackets indicate that the enclosed language element or
	elements are optional.
(a group)	Parentheses group together elements. If parentheses are
	part of the syntax, they are shown in bold.
[optional]...	Three ellipsis points (. . .) after a group defined by
	brackets indicate that you can repeat the group of
	elements within brackets 0 or more times.

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

C H A P T E R 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 AppleScript Language Guide.

Installing Scripting Additions	0

When you install AppleScript using the Installer as described in Getting Started With AppleScript, the Installer creates a folder in the Extensions folder (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.”

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 A scripting addition icon

Installing Scripting Additions

1

C H A P T E R 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

C H A P T E R 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

C H A P T E R 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

C H A P T E R 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

C H A P T E R 2

Scripting Addition Commands

	Table 2-1	Scripting addition commands described in this guide
	Name of	Name of command	Description of command
	scripting addition file
	Not a separate file;	Activate	Activates an application.
	part of AppleScript	Log	Places a string between comment
	extension
			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.

continued

6	Scripting Addition Files

C H A P T E R 2

Scripting Addition Commands

Table 2-1	Scripting addition commands described in this guide (continued)
Name of	Name of command	Description of command
scripting addition file
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	Close Access	Closes a file opened with Open
Commands		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

C H A P T E R 2

Scripting Addition Commands

Table 2-1	Scripting addition commands described in this guide (continued)
Name of	Name of command	Description of command
scripting addition file
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

C H A P T E R 2

Scripting Addition Commands

SYNTAX

activate referenceToApplication

PARAMETER

referenceToApplication

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

RESULT

None

EXAMPLES

set x to application "Scriptable Text Editor" activate x

activate application ¬

"Mac HD:Applications:Scriptable Text Editor"

tell application "Scriptable Text Editor" activate

end tell

tell application "Scriptable Text Editor" to activate

NOTES

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

C H A P T E R 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.

ERRORS
Error	Error message
number
–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

C H A P T E R 2

Scripting Addition Commands

EXAMPLES

ASCII character 100 --result: "d"

ASCII character 101 --result: "e"

ERRORS
Error	Error message
number
–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

C H A P T E R 2

Scripting Addition Commands

PARAMETER

string	An ASCII character.
	Class: String

RESULT

The ASCII number that corresponds to the specified character.

EXAMPLES

ASCII number "d" --result: 100

ASCII number "e" --result: 101

ERRORS

Error	Error message
number
–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

C H A P T E R 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

beep beep 3

NOTES

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

C H A P T E R 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

C H A P T E R 2

Scripting Addition Commands

PARAMETERS

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"

RESULT

A reference to the application specified by the user.

EXAMPLES

choose application with prompt "Choose a spelling checker:"

tell (choose application with prompt ← "Choose a scriptable text editor:")

--other statements end tell

NOTES

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

C H A P T E R 2

Scripting Addition Commands

ERRORS
Error	Error message
number
–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

C H A P T E R 2

Scripting Addition Commands

PARAMETERS

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)

RESULT

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

EXAMPLE

choose file with prompt "Please choose a file:" of type ¬ {"TEXT", "APPL"}

open result

NOTES

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.

ERRORS

Error	Error message
number
–108	Out of memory.
–128	User canceled.

Command Definitions

17

C H A P T E R 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