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
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
ix
Chapter 1 Introduction to Finder Scripting
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
1
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
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
99
v
Appendix A Finder Commands at a Glance
Commands 141
Placeholders 145
141
Appendix B Finder Errors
Index
149
147
vi
Tables and Listings
Chapter 1
Chapter 3
Appendix A
Introduction to Finder Scripting
Listing 1-1 A sample recorded script 6
Listing 1-2 A script that either takes a snapshot of the current window
Listing 1-3 A script that adds a new user to the Users & Groups control panel
Finder Commands
Table 3-1 Variations from standard behavior in Finder versions of standard
Table 3-2 Commands defined by the Finder Suite 103
arrangement or restores a previously stored snapshot 11
and adds a drop folder for that user to the startup disk 12
99
application commands 101
Finder Commands at a Glance
Table A-1 Finder command syntax 142
Table A-2 Placeholders used in syntax descriptions 145
1
141
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
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.
(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.
[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.
a | b | cVertical bars separate elements in a group from which
you must choose a single element. The elements are
often grouped within parentheses or brackets.
xi
CHAPTER 1
Figure 1-0
Listing 1-0
Table 1-0
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
CHAPTER 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?
CHAPTER 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
CHAPTER 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?
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
CHAPTER 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
Loading...