Apple AppleScript Finder Finder Guide

AppleScript Finder Guide

English Dialect

Apple Computer, Inc.

© 1994 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, LaserWriter, and Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries.

AppleScript and Finder 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.

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 MERCHANTABILITY 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

	Tables and Listings		vii
Preface	About This Guide			ix
	Audience	ix
	Organization of This Guide				ix
	For More Information			x
	Getting Started		x
	AppleScript Language			x
	Scripting Additions			x
	Other AppleScript Dialects					xi
	Conventions Used in This Guide					xi
Chapter 1	Introduction to Finder Scripting						1
	Installation	1
	What Is Finder Scripting?			2
	Recording Actions in the Finder					5
	Modifying Recorded Scripts					6
	Simplifying Recorded Scripts					8
	Writing Scripts That Control the Finder						10
Chapter 2	Finder Objects		15
	Using Object Class Definitions					15
	Properties	15
	Element Classes		16
	Commands Handled			17
	Default Value Class Returned					17
	Examples	17

iii

The Finder Application Object						18
Properties and Elements of the Finder							20
References to Finder Windows						22
References Returned for the Insertion Location property								24
References Returned for a Point							25
Object Class Definitions					26
Accessory Process					26
Accessory Suitcase					27
Alias File		28
Application			31
Application File				38
Application Process					41
Container		43
Container Window					47
Content Space			50
Control Panel			51
Desk Accessory File					55
Desktop-Object				56
Disk	57
Document File			60
File	61
Folder		63
Font File		65
Font Suitcase			66
Group		68
Information Window					69
Item	73
Process		77
Sharable Container					79
Sharing Privileges					83
Sharing Window				85
Sound File		88
Status Window			89
Suitcase		90
Trash-Object			91
User	93
Window		95

iv

Chapter 3 Finder Commands			99
Using Command Definitions				99
Syntax	99
Parameters		100
Result	101
Examples		101
Command Definitions			101
Clean Up		104
Close	106
Computer		107
Copy	109
Count	110
Data Size		111
Delete	113
Duplicate		114
Eject	115
Empty	116
Erase	117
Exists	118
Get	119
Make	121
Move	124
Open	125
Print	126
Put Away		127
Quit	129
Restart	130
Reveal	131
Select	132
Set	133
Shut Down		134
Sleep	134
Sort	135
Update	137

v

Appendix A Finder Commands at a Glance 141

Commands 141

Placeholders 145

Appendix B Finder Errors

147

Index 149

vi

Tables and Listings

Chapter 1	Introduction to Finder Scripting			1
	Listing 1-1	A sample recorded script			6
	Listing 1-2	A script that either takes a snapshot of the current window					11
	Listing 1-3	arrangement or restores a previously stored snapshot
		A script that adds a new user to the Users & Groups control panel
		and adds a drop folder for that user to the startup disk					12
Chapter 3	Finder Commands		99
	Table 3-1	Variations from standard behavior in Finder versions of standard
	Table 3-2	application commands			101
		Commands defined by the Finder Suite				103
Appendix A Finder Commands at a Glance				141
	Table A-1	Finder command syntax			142
	Table A-2	Placeholders used in syntax descriptions				145

vii

P R E F A C E

About This Guide

The AppleScript Finder Guide: English Dialect describes the commands and object classes defined by the Finder for use with the English dialect of the AppleScript language. The Finder scripting software allows you to write, record, or run scripts that control actions in the Finder such as opening and closing folders and manipulating files.

Audience

0

This guide is for anyone who wants to record or write new scripts or modify existing scripts that control actions in the Finder.

Before using this guide, you should have installed AppleScript with the Installer program. You should also be familiar with the AppleScript Language Guide: English Dialect, which describes the English dialect of the AppleScript scripting language, the AppleScript Scripting Additions Guide, and Getting Started With AppleScript.

Macintosh software developers who want to make their programs scriptable or recordable should also refer to Inside Macintosh: Interapplication Communication.

Organization of This Guide

0

This guide contains three chapters:

■Chapter 1, “Introduction to Finder Scripting,” introduces Finder scripting and describes how to record and modify simple scripts.

■Chapter 2, “Finder Objects,” provides definitions for all Finder object classes.

■Chapter 3, “Finder Commands,” provides definitions for all Finder commands.

ix

P R E F A C E

At the end of the guide are two appendixes and an index.

■Appendix A, “Finder Commands at a Glance,” summarizes the commands defined by the Finder.

■Appendix B, “Finder Errors,” lists the error messages returned by the Finder.

For More Information	0
Getting Started	0

See the 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 AppleScript Language Guide: English Dialect (referred to in this book as the 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.

Scripting Additions

0

Scripting additions are files that provide additional commands or coercions you can use in scripts. A standard set of scripting additions comes with AppleScript. Scripting additions are also sold commercially, included

with applications, and distributed through electronic bulletin boards and user groups.

For more information about the scripting additions that come with AppleScript, see the AppleScript Scripting Additions Guide: English Dialect (referred to in this book as the AppleScript Scripting Additions Guide).

x

P R E F A C E

Other AppleScript Dialects

0

A dialect is a version of the AppleScript language that resembles a particular human language or a programming language. This guide describes the terms defined by the Finder for use with the AppleScript English dialect. Versions of the Finder for use with other dialects work the same way but define terms and syntax appropriate for those dialects.

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

placeholder

[optional] (a group) (a group). . .

[optional]...

a | b | c

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.

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 parentheses indicate that you can repeat the group of elements within parentheses one or more times.

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

Vertical bars separate elements in a group from which you must choose a single element. The elements are often grouped within parentheses or brackets.

xi

Figure 1-0

Listing 1-0

Table 1-0

C H A P T E R 1

Introduction to Finder Scripting 1

Finder scripting refers to the use of AppleScript and an application such as the Script Editor to write, record, or run scripts that trigger actions in the Finder. This chapter introduces Finder scripting. It also describes how to

■record your actions in the Finder in the form of a script

■modify recorded Finder scripts

■begin writing Finder scripts

This chapter assumes that you know how to use the Script Editor application to run a script. It also assumes that you understand how commands and object names can be combined in Tell statements to describe actions performed by an application. If these concepts are not familiar, read Part I of the AppleScript Language Guide before reading this chapter.

Installation	1

If you obtained the Finder scripting software with the AppleScript Scripter’s Toolkit, you can install it by running the Installer program on the AppleScript Setup disk. After the Installer opens, click the Customize button, then select the item named Finder Scripting Software and click Install. If you obtained the Finder scripting software on a disk that updates an older version of the AppleScript Scripter’s Toolkit, run the Installer program that’s included on the update disk and click the Install button after the Installer opens.

Finder scripting requires System 7.1 or later versions of system software. Versions later than System 7 Pro (System 7.1.1) include the Finder scripting software, which is installed automatically when you install the system software.

Installation

1

C H A P T E R 1

Introduction to Finder Scripting

IMPORTANT

Finder scripts that return a lot of information may need as much as several hundred kilobytes (K) of free memory to work correctly. To see how much memory is currently free, activate the Finder, choose About This Macintosh from the Apple menu, and check the number labeled Largest Unused Block in the About This Macintosh window. If a script you’ve used successfully stops working, try quitting one or more applications to make more memory available. ▲

What Is Finder Scripting?

1

The Finder is a specialized application that controls the Macintosh desktop: the working area of your screen where you can use the mouse and the keyboard to open and close folders, manipulate files, and inspect or alter various aspects of the computer’s operation. Finder scripting involves performing the same kinds of tasks, except that instead of triggering actions with the aid of the mouse and the keyboard, you trigger actions from scripts.

The Finder is both scriptable and recordable. A scriptable application is one that can respond to commands sent to it when another application, such as the Script Editor, runs a script. A recordable application is one that uses Apple events to report user actions for recording purposes. When recording is turned on, the Script Editor creates statements corresponding to any significant actions you perform in recordable applications, including actions you perform in the Finder. By recording or writing scripts that control the Finder, you can automate many file management and networking tasks that you would otherwise have to perform manually.

For example, the script that follows copies the items from a folder on the startup disk to a folder on a different disk. Instead of opening all the folders by double-clicking them then dragging the contents of the AppleScript folder to a storage disk, you can run the script.

2	What Is Finder Scripting?

C H A P T E R 1

Introduction to Finder Scripting

tell application "Finder"

copy items of folder "AppleScript" of folder "Projects" of ¬ startup disk to folder "Backups" of disk "Storage"

end tell

This script consists of a three-line Tell statement that names the Finder application running on the local computer as the target application. (The ¬ symbol

is a “soft” return; it tells AppleScript to treat the line it’s on and the line that follows as if they are a single line.) As far as AppleScript is concerned, the Finder is just like any other scriptable application.

Like other scriptable applications, the Finder defines commands that you can use in scripts to describe actions. Some of these are standard application commands, such as Copy, Open, Print, and Move, that can be used with most scriptable applications. Others are commands unique to the Finder, such as

Eject, Put Away, and Restart. The Finder also defines classes of objects on which actions can be performed, such as files, folders, and disks. Most of these object classes are unique to the Finder.

The copy command in the preceding example acts on the objects described by the reference items of folder "AppleScript" of folder "Projects" of startup disk. The folder AppleScript is located at the top level of the folder Projects, which located at the top level of the startup disk. The term items refers to all objects in the AppleScript folder, including files, other folders, suitcases, and so on. Any object in the Finder can be identified from within

a script as long as its container and if necessary the container’s containers are also identified.

By using AppleScript features such as Repeat statements and other control statements, you can create more complex scripts that take different actions depending on the outcome of one or more tests. For example, the script that follows checks all the disks of a specified computer for the presence of a folder called Back Me Up. Whenever a disk contains such a folder, the script creates a folder on a storage volume and copies the contents of Back Me Up to that folder. (The storage volume must be mounted on the remote computer for this script to work correctly.)

What Is Finder Scripting?

3

C H A P T E R 1

Introduction to Finder Scripting

tell application "Finder" of machine "Macintosh IIci" repeat with i in every disk in desktop

if folder "Back Me Up" of i exists then set folderName to name of i & " " & ¬

day of (current date) & " " & time of (current date) set newFolder to make folder at ¬

disk "Storage" with properties {name:folderName} duplicate (items of folder "Back Me Up" of i) to newFolder

end if end repeat

end tell

The Repeat statement in this script applies the statements it contains to every disk on the desktop of the computer named Macintosh IIci. The If statement within the Repeat statement checks each disk for the presence of a folder called Back Me Up. If the folder exists on a disk, the second line of the If statement sets the variable folderName to a string that consists of the disk’s name,

the day of the month, and the time in seconds since the beginning of that day, thus ensuring that any other backup folders created from the same disk at a different time will have slightly different names. The rest of the If statement creates a new folder with the name assigned to folderName on a storage disk and asks the Finder to duplicate the items in the Back Me Up folder to the new folder.

As you can see, scripts that control the Finder use familiar terms like folder, disk, and desktop as well as standard AppleScript terms like of, repeat, and tell. Chapter 2, “Finder Objects,” describes all the terms the Finder defines for objects, and Chapter 3, “Finder Commands,” describes the terms it defines for commands. You can use these chapters as references when you need detailed information about specific objects or commands. However, the

easiest way to learn how to use the scripting terminology defined by the Finder is to record your actions in the Finder and examine the resulting script.

The next section describes how to use record and edit scripts that control the Finder. When you see how the Finder uses its own terminology in recorded scripts, you can begin writing your own scripts from scratch.

4	What Is Finder Scripting?

C H A P T E R 1

Introduction to Finder Scripting

Recording Actions in the Finder

1

You can record almost any actions in the Finder that involve manipulating Finder windows or icons: for example, opening folders, copying files, or changing View settings. To record actions in the Finder, click the Record button in the Script Editor application, then activate the Finder (by clicking on the desktop or choosing Finder from the Applications menu) and perform the actions that you want to record.

For example, suppose you like to have certain Finder windows arranged next to each other on the desktop when you’re working on financial matters, so that related files, alias files, or applications are easily accessible. To record the arrangement you want, follow these steps:

1.Open the Script Editor application.

2.Click the Record button.

3.Activate the Finder by clicking on the desktop or choosing Finder from the Applications menu.

4.If any Finder windows are currently open, close them all by holding down the Option key and clicking the close box of the active window.

5.Open, resize, and arrange the windows whose positions you want to record.

6.When you’re satisfied with the arrangement of the desktop, activate the Script Editor again and click the Stop button.

The recorded script should look something like the one in Listing 1-1 on page 6.

If you save your recorded script as a script application, you can arrange the windows the same way at any time by double-clicking the script’s icon in the Finder. The Finder responds by closing any windows that are currently open and opening and arranging windows as specified in the script.

Recording Actions in the Finder

5

C H A P T E R 1

Introduction to Finder Scripting

Listing 1-1 A sample recorded script

tell application "Finder" activate

close every window select startup disk open selection

set position of window of startup disk to {4, 43} set size of window of startup disk to {369, 464} select folder "Financial" of startup disk

open selection

set position of window of folder "Financial" of startup disk to ¬ {378, 43}

set size of window of folder "Financial" of startup disk to ¬ {200, 155}

select folder "Letters" of startup disk open selection

set size of window of folder "Letters" of startup disk to ¬ {257, 385}

set position of window of folder "Letters" of startup disk to ¬ {379, 222}

set size of window of folder "Letters" of startup disk to ¬ {200, 286}

end tell

Modifying Recorded Scripts

1

You can often modify a recorded script to suit new circumstances. For example, you could adapt the script shown in Listing 1-1 for use with an external hard disk rather than the startup disk by changing the term startup disk to disk "nameOfDisk" throughout the script, where nameOfDisk is the name of the hard disk on which the folders Financial and Letters are located.

Or suppose you want to make sure the Finder opens each window specified in Listing 1-1 with a specific view selected in the Views menu. One way to do this might be to place the insertion point after the last line of the script in the script

6	Recording Actions in the Finder

C H A P T E R 1

Introduction to Finder Scripting

window, turn on recording, choose the settings you want for each window from the View menu, and turn off recording. Any significant changes you make to the windows’ views will be recorded; however, if some of the View settings for some of the windows are already set the way you want them, the Finder won’t record the action because nothing changes as a result.

A more reliable approach is to add lines to the recorded script that set the View settings. To do so, you must know how to tell the Finder to set the view of

a window.

The easiest way to learn how to describe an action in the Finder is to try recording the action in a sample script. To learn how the Finder sets a window’s view, follow these steps:

1.Open a new script window in the Script Editor by choosing New Script from the File menu.

2.Click the Record button.

3.Activate the Finder by clicking on the desktop or choosing Finder from the Applications menu.

4.Change the Views setting for one of the Finder’s windows.

5.Activate the Script Editor again and click the Stop button.

The recorded script looks something like this:

tell application "Finder" activate

set view of window of folder "Financial" of startup disk to name end tell

The third line of the recorded script sets the View property of the window for the folder Financial to name. You can now use this line as a template for setting the views of folder windows in a script. For example, to modify Listing 1-1 so that the windows will always open in specific views, you could add these lines just before the last line (that is, before end tell):

set view of window of startup disk to icon

set view of window of folder "Financial" of startup disk to name set view of window of folder "Letters" of startup disk to size

Recording Actions in the Finder

7

C H A P T E R 1

Introduction to Finder Scripting

After you run the new script, the windows have the views specified in the script even if you’ve previously changed them.

To modify recorded scripts or create new scripts that control the Finder, you may need to look up the definitions of some of Finder terms. Like any scriptable application, the Finder contains a dictionary of the AppleScript terms that you can use to control the application. To open the dictionary, drag the Finder’s icon over the icon of the Script Editor, the script-editing application that comes with AppleScript. If you run across an unfamiliar word in a recorded script, you can look it up quickly in the dictionary. If you need a comprehensive definition with examples, look up the term’s entry in this book.

Simplifying Recorded Scripts

1

As is often true of scriptable applications, the Finder allows you to express the same action in several different ways. Recorded scripts are precisely worded so as to avoid ambiguity in variety of circumstances. In the script shown in Listing 1-1 on page 6, however, there is no need to specify the folder and

disk to which a window belongs. If you wish, you can specify a window by name only:

set view of window "Letters" to size

To work correctly, the preceding statement must be contained in a Tell statement that names the Finder as the target application, and the window named Letters must be open. The container for a Finder window is always the Finder itself. If more than one window named Letters is open, the Finder changes the View property for all windows with that name to size.

The previous section described how to add three lines at the end of the script shown in Listing 1-1 that set the window’s views to different values. If instead you want all the windows opened by that script to have the same view, you could add just one line:

set view of windows to name

The plural form windows identifies all open Finder windows.

After opening a window, the recorded script in Listing 1-1 adjusts the window’s Position and Size properties separately. The terms Position and Size name

two different properties of a window. Each property consists of a list of two

8	Recording Actions in the Finder

C H A P T E R 1

Introduction to Finder Scripting

integers. For the Position property, the two integers specify the coordinates of the upper-left corner of the content region of the window (the portion of the window that displays its contents; the title bar and scroll bars are not part of the content region). For the Size property, the two integers specify the vertical and horizontal dimensions of the window’s content region.

Instead of adjusting these properties separately, you can adjust them at the same time by setting the Bounds property. The value of the Bounds property is a list of four integers that specify the coordinates of the four corners of the window’s content region. The first and second integers are identical to the value of the window’s Position property. The third and fourth integers can be obtained by adding the first and second integers of the Position property to the first and second integers of the Size property, respectively.

You can easily obtain the bounds property of a window by asking the Finder for it. Just activate the window and run a script like this:

tell application "Finder" bounds of front window

end tell

--result: {4, 43, 373, 507}

If you wish, you can rewrite a script like the one in Listing 1-1 using the Bounds property instead of Position and Size:

tell application "Finder" activate

close every window open startup disk

set bounds of window of startup disk to {4, 43, 373, 507} open folder "Financial" of startup disk

set bounds of window "Financial" to {378, 43, 578, 198} open folder "Letters" of startup disk

set bounds of window "Letters" to {379, 222, 579, 508} end tell

Although this simplified version of the script in Listing 1-1 won’t run appreciably faster than the original, it is easier to read. In a longer script, using succinct statements can improve performance.

Recording Actions in the Finder

9

C H A P T E R 1

Introduction to Finder Scripting

Writing Scripts That Control the Finder

1

You can use a variety of techniques in scripts you write yourself that you can’t use in recorded scripts. For example, suppose you have several different window arrangements that you like to use, and they tend to evolve and change. Instead of recording a series of scripts, you can write a single script that allows you to perform one of two actions: take a snapshot of the current window arrangement or restore the most recently taken snapshot.

To write a script that performs these tasks, you need to know something about script properties, variables, the Display Dialog scripting addition, If statements, and Repeat statements. For more information about these AppleScript features, see the AppleScript Language Guide and the AppleScript Scripting Additions Guide.

Listing 1-2 shows an example of such a script. It begins by declaring two script properties, boundsAll and refsAll, that hold the windows’ bounds and references to the objects the windows belong to when the script takes a snapshot. At first these properties consist of empty lists. When the script takes a snapshot of the current windows, these properties “remember” the windows’ bounds and references until a new snapshot is taken or the script is recompiled.

After declaring its properties, the script uses the Display Dialog scripting addition command to display a dialog box. The dialog box asks the user to make a choice and displays two buttons: Restore Old Snapshot or Take New Snapshot. These buttons control which of two parts of the If statement that follows runs next.

If the user chooses Take New Snapshot, the second part of the If statement (beginning with else) takes control and stores the bounds and references for the open windows in the boundsAll and refsAll properties. If the user chooses Restore Old Snapshot, the first part of the If statement closes all the

windows that are currently open and uses the values stored in the properties to identify the items whose windows are to be opened, open their windows, and set the windows’ bounds. These actions are accomplished with a Repeat loop that acts on one item and its window at a time.

10	Writing Scripts That Control the Finder

C H A P T E R 1

Introduction to Finder Scripting

Listing 1-2 A script that either takes a snapshot of the current window arrangement or restores a previously stored snapshot

property boundsAll : {} property refsAll : {}

set dialogResult to display dialog ¬ "Restore old snapshot or take new one?" ¬

buttons {"Restore Old Snapshot", "Take New Snapshot"}

if button returned of dialogResult is "Restore Old Snapshot" then tell application "Finder"

close windows

set increment to 0

repeat (number of items in refsAll) times set increment to increment + 1

set i to item increment of refsAll open i

set x to item increment of boundsAll set bounds of window 1 to x

end repeat end tell

else

tell application "Finder"

set boundsAll to the bounds of every window set refsAll to the item of every window

end tell end if

To keep this script handy, store it as a script application on the desktop. Whenever you want to record or restore a window arrangement, double-click the application’s icon. If you want to be able to switch back and forth between several window arrangements, duplicate the script and use each copy to create and store a different one.

Writing Scripts That Control the Finder

11

C H A P T E R 1

Introduction to Finder Scripting

Listing 1-3 shows another script that uses the Display Dialog command. This script automates a couple of tasks that network administrators often have to perform: adding a new user and adding a drop folder for that user.

Listing 1-3 A script that adds a new user to the Users & Groups control panel and adds a drop folder for that user to the startup disk

tell application "Finder"

set dialogResult to display dialog ¬ "Name of new user:" default answer ""

set newUser to text returned of dialogResult

set cPanel to control panel "Users & Groups" of ¬ control panels folder

open cPanel

make user at cPanel with properties {name:newUser}

set newFolder to make folder at startup disk ¬ with properties {name:newUser}

set owner of newFolder to newUser

set group of newFolder to "Department Group"

set see folders of group privileges of newFolder to true set see files of group privileges of newFolder to true set make changes of group privileges of newFolder to true set see folders of owner privileges of newFolder to true set see files of owner privileges of newFolder to true set make changes of owner privileges of newFolder to true set see folders of guest privileges of newFolder to false set see files of guest privileges of newFolder to false set make changes of guest privileges of newFolder to true

end tell

12	Writing Scripts That Control the Finder

C H A P T E R 1

Introduction to Finder Scripting

Unlike the script in Listing 1-2, the script in Listing 1-3 consists of a single Tell statement, and the Display Dialog command is invoked from within the

Tell statement. The dialog box asks for the name of the new user and stores it in the variable newUser. The three statements that follow open the Users & Groups control panel and use the Make command to create a new user object with the name stored in newUser.

The rest of the Tell statement consists of a series of Set commands that create a new folder on the startup disk with the new user’s name and set the folder’s owner and group and its sharing privileges. The owner and members of the Department Group have all sharing privileges set to true. The guest privileges See Folders, See Files, and Make Changes are set to false, false, and true respectively, so guests can drop items into the folder but can’t open it. These privileges are signaled to guests by a belt around the folder and a small black arrow above it.

For the script in Listing 1-3 to work correctly, file sharing must be turned on and the computer on which the script is running must have a group named Department Group. You can modify that name or other settings in the script to suit your own purposes. You can also modify the script in a variety of other ways. For example, you can add an If statement that checks for the presence of a particular group and if necessary creates the group before creating the new user.

Writing Scripts That Control the Finder

13

C H A P T E R 2

Figure 2-0

Listing 2-0

Table 2-0

Finder Objects

2

This chapter begins with a summary of the format used in object class definitions and an introduction to the Finder application object, the outermost container for most other Finder objects. The last section of the chapter provides complete descriptions of the object classes defined by the Finder.

Using Object Class Definitions	2

Object class definitions describe what objects that belong to a particular class have in common. Each definition contains at least five kinds of information: properties, element classes, commands handled, default value class returned, and one or more examples. These categories are briefly described here, using examples from the definition of File that begins on page 61.

For a more detailed discussion of object classes and references to objects, see the AppleScript Language Guide.

Properties

2

A property of an object is a characteristic that has a single value, such as the name of a window or the modification date of a file. Properties are contained by objects in much the same way that elements are (see “Element Classes” on page 16). The main difference is that each of an object’s properties has only one value, whereas an object may have many different elements of a single class.

Properties of an object are distinguished from each other by their unique labels. For example, the script that follows sets the Position property of the file MyFile, causing the icon for that file to move to the specified position.

Using Object Class Definitions

15

C H A P T E R 2

Finder Objects

tell application "Finder"

set position of file "MyFile" to {29, 235} end tell

The file in this example must be located on the desktop. A file can have only one Position property, distinguished from the other properties of the file by its label, position.

The Properties section of an object class definition lists all the property labels defined for that object and describes how to use them, including the class used for each property’s value and whether or not the property can be modified. Some objects inherit some or all their properties from other related objects. For example, the definition for File that begins on page 61 lists several properties that are inherited from the object class Item and several that are defined specifically for class File.

IMPORTANT

A property name has no plural form, even if you use it to refer to more than one property. ▲

This script gets a list of the names of the files at the top level of the startup disk:

tell application "Finder"

name of files in startup disk end tell

If you replace name with names, the script won’t compile.

Element Classes

2

Elements are objects contained by an object. For example, a folder can contain files and other folders. The element classes listed in an object class definition show what kinds of elements objects of that class can contain. An object can contain many elements or none, and the number of elements of a particular class may change over time.

A file can be an element of other Finder objects in which files can be stored, such as folders, disks, or the desktop; so File is listed as one of their element classes. The definition for object class File that begins on page 61 indicates that a file can’t contain any other elements.

16	Using Object Class Definitions

C H A P T E R	2
Finder Objects
Commands Handled	2

Objects that belong to the same class can respond to the same commands. Object class definitions list the commands to which all objects of that class respond.

For example, the definition for File that begins on page 61 indicates that you can use any of these commands to perform actions on a file: Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Make, Move, Open, Print, Put Away, Reveal, Select, Sort, Update.

Default Value Class Returned

2

In most scriptable applications, each object has a value that you can obtain simply by referring to the object in a script. For example, the value of a paragraph object in a word-processing application is a string that includes style and font information.

Unlike other scriptable applications, the Finder can control only the representation of its objects within windows and the properties it defines for them; it can’t retrieve or alter text in a text file, for example. Therefore, the value returned for most Finder objects is a reference to the object, not the object’s data.

For example, this script returns a reference to the file MyFile, not the contents of the file:

tell application "Finder"

get file "MyFile" of startup disk end tell

--result: file "MyFile" of startup disk of application "Finder"

Examples

2

Each object class definition in this book include one or more short examples demonstrating how to use the object name in a script. The first example for the File command definition that begins on page 61 is a script that returns a list of references to files whose modification dates are greater than a specified date, and the second example is a script that copies an icon to a group of files.

Using Object Class Definitions

17

C H A P T E R 2

Finder Objects

The Finder Application Object

0

The Finder application object belongs to the object class Application. As is usually the case with scriptable applications, the application object functions as the outermost container for most of the objects the Finder defines.

To send commands to the Finder, use a Tell statement addressed to the Finder:

tell application "Finder" open startup disk

end tell

––result: startup disk of application "Finder"

The result shown appears in the Script Editor’s Result window. The statement

startup disk of application "Finder"

is a complete reference to the startup disk. The Finder application itself is the startup disk’s container. Disks, folders, and files are examples of objects that can be elements of the Finder application. Folders and files can in turn be elements of disks or of folders within disks.

You can identify nested Finder objects in a variety of ways. For example, if the startup disk is named My World, these statements all identify the same object:

folder "My Folder" of startup disk of application "Finder" folder "My Folder" of disk "My World" of application "Finder" item "My Folder" of container "My World" of application "Finder" container "My World:My Folder" of application "Finder"

When recording is turned on, the Finder always records references the same way. Although the Finder can interpret the four statements in the previous example correctly, it records the reference as shown in the first statement.

18	The Finder Application Object