Apple AppleScript Finder Finder Guide

AppleScript Finder Guide

English Dialect

Apple Computer, Inc.

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 modiﬁcation, 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 speciﬁc 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

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

Using Object Class Deﬁnitions 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 Deﬁnitions 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

Chapter 3 Finder Commands

Using Command Deﬁnitions 99

Syntax 99 Parameters 100 Result 101 Examples 101

Command Deﬁnitions 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

Appendix A Finder Commands at a Glance

Commands 141 Placeholders 145

141

Appendix B Finder Errors

Index

149

147

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 deﬁned 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

application commands 101

Finder Commands at a Glance

Table A-1 Finder command syntax 142 Table A-2 Placeholders used in syntax descriptions 145

141

vii

P R E F A C E

About This Guide

The AppleScript Finder Guide: English Dialect describes the commands and object classes deﬁned 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 ﬁles.

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 deﬁnitions for all Finder object classes.

■

Chapter 3, “Finder Commands,” provides deﬁnitions for all Finder commands.

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

deﬁned 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 ﬁles 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).

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 deﬁned by the Finder for use with the AppleScript English dialect. Versions of the Finder for use with other dialects work the same way but deﬁne 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 deﬁned by

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

[optional]... Three ellipsis points (. . .) after a group deﬁned 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.

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

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 ﬁles, 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 signiﬁcant 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 ﬁle 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.

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 deﬁnes 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 deﬁnes classes of objects on which actions can be performed, such as ﬁles, 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 identiﬁed from within a script as long as its container and if necessary the container’s containers are also identiﬁed.

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 speciﬁed 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 deﬁnes for objects, and Chapter 3, “Finder Commands,” describes the terms it deﬁnes for commands. You can use these chapters as references when you need detailed information about speciﬁc objects or commands. However, the easiest way to learn how to use the scripting terminology deﬁned 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 ﬁles, 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 ﬁnancial matters, so that related ﬁles, alias ﬁles, 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 satisﬁed 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 speciﬁed 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 speciﬁed in Listing 1-1 with a speciﬁc 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 signiﬁcant 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 speciﬁc 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 speciﬁed 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 deﬁnitions 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 deﬁnition 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 identiﬁes 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 ﬁrst 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 ﬁrst and second integers of the Position property to the ﬁrst 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 simpliﬁed 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 ﬁrst 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 ﬁrst 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, ﬁle 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 deﬁnitions 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 deﬁned by the Finder.

Using Object Class Deﬁnitions 2

Object class deﬁnitions describe what objects that belong to a particular class have in common. Each deﬁnition contains at least ﬁve kinds of information: properties, element classes, commands handled, default value class returned, and one or more examples. These categories are brieﬂy described here, using examples from the deﬁnition 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 modiﬁcation date of a ﬁle. 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 ﬁle MyFile, causing the icon for that ﬁle to move to the speciﬁed position.

Using Object Class Deﬁnitions 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 ﬁle can have only one Position property, distinguished from the other properties of the ﬁle by its label, position.

The Properties section of an object class deﬁnition lists all the property labels deﬁned 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 modiﬁed. Some objects inherit some or all their properties from other related objects. For example, the deﬁnition for File that begins on page 61 lists several properties that are inherited from the object class Item and several that are deﬁned speciﬁcally 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 ﬁles 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 ﬁles and other folders. The element classes listed in an object class deﬁnition 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 ﬁle can be an element of other Finder objects in which ﬁles can be stored, such as folders, disks, or the desktop; so File is listed as one of their element classes. The deﬁnition for object class File that begins on page 61 indicates that a ﬁle can’t contain any other elements.

16 Using Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Commands Handled 2

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

For example, the deﬁnition for File that begins on page 61 indicates that you can use any of these commands to perform actions on a ﬁle: 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 deﬁnes for them; it can’t retrieve or alter text in a text ﬁle, 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 ﬁle MyFile, not the contents of the ﬁle:

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 deﬁnition in this book include one or more short examples demonstrating how to use the object name in a script. The ﬁrst example for the File command deﬁnition that begins on page 61 is a script that returns a list of references to ﬁles whose modiﬁcation dates are greater than a speciﬁed date, and the second example is a script that copies an icon to a group of ﬁles.

Using Object Class Deﬁnitions 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 deﬁnes.

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 ﬁles are examples of objects that can be elements of the Finder application. Folders and ﬁles 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 ﬁrst statement.

18 The Finder Application Object

CHAPTER 2

Finder Objects

To obtain a standard reference to an element of the Finder while you’re writing a script, follow these steps:

1. Select the object.

2. Choose Copy from the Edit menu.

3. Activate the Script Editor application.

4. Click at the point in your script where you want to paste the reference.

5. Choose Paste Reference from the Edit menu.

Windows are also elements of the Finder application. You can address a Tell statement to a Finder window anywhere in a script:

tell front window of application "Finder"

end tell

Because window is a standard AppleScript term, AppleScript can interpret this script correctly. However, when it compiles a script, AppleScript doesn’t look up the Finder’s terminology deﬁnitions until after it has compiled the ﬁrst line of the ﬁrst Tell statement that addresses the Finder. Therefore, a script that consists of a Tell statement addressed to any other Finder object won’t compile:

tell startup disk of application "Finder"

open

end tell

To address a Tell statement to a Finder object other than a window, enclose it within another Tell Statement, like this:

tell application "Finder"

tell startup disk

open

end tell

The Finder Application Object 19

CHAPTER 2

Finder Objects

Properties and Elements of the Finder 2

The Finder application, like most other Finder objects, has many properties you can refer to in scripts. Some of these properties provide a shorthand method of referring to certain specialized objects.

For example, although the Finder application can contain any number of folders, only one Apple Menu Items folder can be located in the active System Folder for a given Macintosh computer. The Apple Menu Items folder can be described in a script as either an element of the System Folder or a property of the Finder application.

This script identiﬁes the Apple Menu Items folder as an object contained by the System Folder:

tell application "Finder"

open folder "Apple Menu Items" of ¬

folder "System Folder" of startup disk

end tell

This script identiﬁes the Apple Menu Items folder as a property of the Finder application:

tell application "Finder"

open apple menu items folder

end tell

Other specialized containers, such as the startup disk, the System Folder, the Startup Items folder, and the Extensions folder, are also deﬁned as Finder properties.

Note

You can use the Path To scripting addition command to obtain references to some of the objects that can be identiﬁed as properties of the Finder. However, Path To use its own constants for these references and returns a pathname as an AppleScript reference of the form alias "Disk:Folder1:Folder2:...:Filename". ◆

The desktop is another container you can identify as a property of the Finder. Any items contained by the desktop—that is, items that are “loose” on the

20 The Finder Application Object

CHAPTER 2

Finder Objects

working area of your screen and not contained by a folder, disk, or other object—can be considered elements of either the desktop or of the Finder application object, as shown in the following examples.

This script requests a list of the items contained by the desktop:

tell application "Finder"

items of desktop

end tell

--result: {trash of application "Finder", disk "Applications" of application "Finder", disk "Storage" of application "Finder", startup disk of application "Finder"}

If you request the items of the Finder application, you get a similar list:

tell application "Finder"

items

end tell

--result: {trash of application "Finder", disk "Applications" of application "Finder", disk "Storage" of application "Finder", startup disk of application "Finder", desktop of application "Finder"}

The only difference is that the second list includes a reference to the desktop itself, which is also an item contained by the Finder application.

Finally, if you request the contents of the Finder application, you get a list that includes references to windows and to currently running processes as well as to the Finder’s items:

tell application "Finder"

contents

end tell

--result: {trash of application "Finder", disk "Applications" of application "Finder", disk "Storage" of application "Finder", startup disk of application "Finder",

The Finder Application Object 21

CHAPTER 2

Finder Objects

window of startup disk of application "Finder", content space of desktop of application "Finder", desktop of application "Finder", application "Scriptable Text Editor", application "Script Editor"}

For complete lists of the Finder application object’s properties and element classes, see the deﬁnition for the Application object class, which begins on page 31.

References to Finder Windows 2

One of the Finder elements you can refer to in scripts is a content space, which can be any kind of window or the desktop. If you request all the content spaces, the Finder returns a list of references to all kinds of windows (container windows, information windows, sharing windows, and status windows) and the desktop:

tell application "Finder"

content spaces

end tell

--result: {information window of startup disk of application "Finder", window of folder "Projects" of startup disk of application "Finder", window of startup disk of application "Finder", window of disk "Applications" of application "Finder", content space of desktop of application "Finder"}

The result shown in the preceding example includes one information window, three container windows, and the desktop content space. An information window is the window that opens when you select an object’s icon in the Finder and choose Get Info from the File command. Containers are objects that can hold other objects, such as suitcases, folders, disks, and the desktop, and a container window is a window that belongs to a container. The only exception is the desktop window. Even though the desktop is a container, the desktop

22 The Finder Application Object

CHAPTER 2

Finder Objects

content space is a special case and the Finder doesn’t consider it a member of class Window (although you can refer to window of desktop in a script).

The desktop “window” and the desktop are actually the same object, whereas all other windows are distinct from the objects they belong to and may have different properties. For example, the Position property of a disk is different from the Position property of the disk’s window.

The desktop doesn’t have most of the characteristics of windows, so you can’t refer to properties such as Bounds, Position, and so on. If you are performing operations on Finder windows that involve these properties, you may want to get a list of windows that doesn’t include the desktop. Therefore, the Finder doesn’t include the desktop when you request a list of windows:

tell application "Finder"

windows

end tell

The list of window references returned doesn’t include the desktop, but it does include information windows and any other windows that are open. If you want to get a list restricted to windows that belong to containers, request a list of container windows:

tell application "Finder"

container windows

end tell

--result: {window of folder "Projects" of startup disk of application "Finder", window of startup disk of application "Finder", window of disk "Applications" of application "Finder"}

The Finder Application Object 23

CHAPTER 2

Finder Objects

You can refer to windows by name, by number, or as the window property of the object to which they belong. For example, these statements are equivalent:

window "My Folder" window of folder "My Folder" of startup disk

These statements are also equivalent:

window 1 front window

The Finder’s front window isn’t necessarily the active content space, which can be the desktop as well as a window. To get a reference to the active content space, use this statement:

content space 1

References Returned for the Insertion Location property 2

The Finder’s Insertion Location property returns a reference to the object to which new information can currently be added. For example, if the New Folder command in the File menu is active, the insertion location is a reference to the container in whose content space the new untitled folder appears when you choose New Folder. This container can be a folder, a disk, or the desktop:

tell application "Finder"

insertion location

end tell

--result: desktop of application "Finder"

If the active content space is a sharing window or an information window, the insertion location is a reference to the container to which the window belongs.

24 The Finder Application Object

CHAPTER 2

Finder Objects

References Returned for a Point 2

To get a reference to the content space that lies under a particular point on the desktop, run a script like this:

tell application "Finder"

content space {100, 100}

end tell

--result: window of folder "Projects" of startup disk of application "Finder"

The pair of integers in braces identiﬁes the point in which you’re interested relative to the entire screen (including the menu bar), and the result contains a reference either to a window or to the desktop. It is usually easiest to use the term Content Space to obtain this kind of reference, because the script returns a reference even if the point is located in the desktop window.

You can also specify more restricted window classes, such as Window, Container Window, Information Window, and so on, as shown in the next example.

tell application "Finder"

container window {100, 100}

end tell

The script in this example returns a reference only if a container window contains the speciﬁed point. If the speciﬁed point is located in some other kind of content space, such as the desktop or an information window, the script returns an error.

You can use similar methods to ﬁnd out whether an item or other object lies under a particular point. For example, this script returns a reference to an item if the item’s bounds enclose the speciﬁed point:

tell application "Finder"

item {100, 100}

end tell

The Finder Application Object 25

CHAPTER 2

Finder Objects

Object Class Deﬁnitions 2

This section deﬁnes the Finder’s object classes.

Accessory Process 2

An object of class Accessory Process is a process launched from a desk accessory ﬁle.

PROPERTIES

An accessory process has all the properties deﬁned for object class Process on page 77: Creator Type, File, File Type, Frontmost, Name, Partition Size, Partition Space Used, Remote Events, Scriptable, and Visible.

An accessory process also has this property:

desk accessory file

The desk accessory ﬁle from which this accessory process was launched.

Class: Reference Modiﬁable: No

ELEMENT CLASSES

None

COMMANDS HANDLED

Count, Data Size, Exists, Get, Sort

26 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

DEFAULT VALUE CLASS RETURNED

A reference or (if you use the plural form accessory processes) a list of references of the form

application "AccessoryProcessName"

where AccessoryProcessName is the name of an accessory process as it appears in the Applications menu.

EXAMPLE

This script returns a list of references to the accessory processes that are currently running:

tell application "Finder"

every accessory process

end tell

--result: {application "Alarm Clock”, application "Calculator", application "Notepad"}

Accessory Suitcase 2

An object of class Accessory Suitcase is a desk accessory suitcase.

PROPERTIES

An accessory suitcase has all the properties deﬁned for object class Container on page 43: Completely Expanded, Container Window, Entire Contents, Expandable, Expanded, Previous List View, Selection, and View.

Like any other container, an accessory suitcase also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Object Class Deﬁnitions 27

CHAPTER 2

Finder Objects

ELEMENT CLASSES

The only elements that an accessory suitcase can contain are objects of class Item (see page 73 for the deﬁnition of Item). Items can be identiﬁed within an accessory suitcase by name or by number.

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Make, Move, Open, Put Away, Reveal, Select, Set, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a suitcase or, if you use the plural form accessory suitcases, a list of references.

EXAMPLE

This script returns a list of references to the accessory suitcases at the top level of the startup disk:

tell application "Finder"

accessory suitcases of startup disk

end tell

--result: {suitcase "DAs" of startup disk of application "Finder", suitcase "More DAs" of startup disk of application "Finder"}

Alias File 2

A object of class Alias File is an alias—that is, a ﬁle that represents another ﬁle or volume. Icons for alias ﬁles have italicized names.

PROPERTIES

An alias ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

28 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Like any other ﬁle, an alias ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other ﬁles, an alias ﬁle also has this property:

original item

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Eject, Empty, Exists, Get, Make, Move, Open, Print, Put Away, Reveal, Select, Sort, Update

A reference to the original item associated with the alias ﬁle.

Class: Reference Modiﬁable: No

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form alias files, a list of references.

EXAMPLE

If you run this script from the Script Editor, it reveals the original items for any alias ﬁles that are currently selected:

tell application "Finder"

get selection repeat with moose in result

if original item of moose exists then

reveal original item of moose

end if

end repeat

end tell

Object Class Deﬁnitions 29

NOTES

CHAPTER 2

Finder Objects

The Get statement in this script returns a list of references to the selected items. The Repeat statement tests the Original Item property for each selected alias ﬁle. If the property’s value is a valid reference, the If statement asks the Finder to reveal the original item.

For an example of a script application that performs a similar task, see the deﬁnition of the Reveal command on page 131. For examples of scripts that create alias ﬁles, see the deﬁnition of the Make command beginning on page 121.

A reference to an object of class Alias File in a Tell statement addressed to the Finder is different from an AppleScript reference that uses an alias. You can use an AppleScript alias reference like this anywhere in a script to identify a ﬁle:

alias "Disk:Folder1:Folder2:...:Filename"

When you compile the script (for example, by clicking the Check Syntax button in the Script Editor), AppleScript creates an alias record that identiﬁes the ﬁle even after you move the ﬁle from its original location—as long as you don’t recompile the script.

Like an alias record, an alias ﬁle identiﬁes another ﬁle or folder even after the original has been moved. However, a reference to an alias ﬁle is just like any other Finder reference: it must provide a complete description of the alias ﬁle’s location in a form similar to this:

tell application "Finder"

alias file "Filename" [ of container "ContainerX" ]... ¬

of container "Container1" [ of disk "Disk" ]

end tell

If you move the alias ﬁle, the reference won’t be accurate any longer. Also, if you attempt to use a Finder reference to an alias ﬁle outside of a Tell statement addressed to the Finder, the script won’t run.

30 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Application 2

An object of class Application is the Finder application itself, the outermost container for most Finder objects.

Because of its role as the application that controls the Macintosh desktop, the Finder deﬁnes its own application object differently from the way most other applications deﬁne their application objects. For an introduction to the role of the application object in scripts that control the Finder, see “The Finder Application Object,” which begins on page 18.

PROPERTIES

about this macintosh

A list of references that identify the processes shown in the About This Macintosh window. This list includes a reference to system software but doesn’t include a separate reference to the Finder.

Class: List of references to processes Modiﬁable: No

apple menu items folder

A reference to the Apple Menu Items folder in the System Folder. The contents of this folder appear in the Apple menu.

Class: Reference Modiﬁable: No

clipboard A reference to the Clipboard window, which can also be

displayed by choosing Show Clipboard from the Edit menu.

Class: Reference Modiﬁable: No

control panels folder

A reference to the Control Panels folder in the System Folder. This folder is used to store control panels.

Class: Reference Modiﬁable: No

desktop A reference to the desktop.

Class: Reference Modiﬁable: No

Object Class Deﬁnitions 31

CHAPTER 2

Finder Objects

extensions folder

A reference to the Extensions folder in the System Folder. This folder is used to store extension ﬁles.

Class: Reference Modiﬁable: No

file sharing

A Boolean value that indicates whether ﬁle sharing is on (true) or off (false).

Class: Boolean Modiﬁable: Yes

fonts folder

A reference to the Fonts folder in the System Folder. This folder contains the fonts currently available to the system software.

Class: Folder Modiﬁable: No

frontmost A Boolean value that indicates whether the Finder is the

frontmost application (true) or not (false).

Class: Boolean Modiﬁable: Yes

insertion location

A reference to the object to which new information can currently be added (see page 24 for more information).

Class: Container window Modiﬁable: No

largest free block

An integer that indicates the size, in bytes, of the largest free block of process memory available. This value is approximately the same as the value labeled Largest Unused Block in the About This Macintosh window, except that the value in the window is given in kilobytes (K, where 1K = 1024 bytes).

Class: Integer Modiﬁable: No

preferences folder

A reference to the Preferences folder in the System Folder. This folder contains application preferences ﬁles.

Class: Reference Modiﬁable: No

32 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

product version

A string that describes the version of system software running on the same computer as the Finder.

Class: String Modiﬁable: No

selection A list of references to the object or objects that are currently

selected. The objects in the selection are those that would be cut by a Cut command or copied by a Copy command. If no objects are selected, the value of the Selection property is an empty list.

Class: List of references Modiﬁable: Yes

sharing starting up

A Boolean value that indicates whether ﬁle sharing is in the process of starting up (true) or not (false).

Class: Boolean Modiﬁable: No

shortcuts A reference to the Finder Shortcuts window, which can also be

displayed by choosing Finder Shortcuts from the Help menu.

Class: Reference Modiﬁable: No

shutdown items folder

A reference to the Shutdown Items folder in the System Folder. The contents of this folder are automatically opened when the computer is shut down.

Class: Reference Modiﬁable: No

startup items folder

A reference to the Startup Items folder in the System Folder. The contents of this folder are automatically opened when the computer starts up.

Class: Reference Modiﬁable: No

system folder

A reference to the System Folder.

Class: Reference Modiﬁable: No

Object Class Deﬁnitions 33

CHAPTER 2

Finder Objects

temporary items folder

A reference to the Temporary Items folder in the System Folder. Applications use this folder to store temporary items.

Class: Reference Modiﬁable: No

version A string that describes the version of the Finder Scripting

Extension or, for versions of Finder scripting software that don’t require this extension, the version of the Finder ﬁle in the active System Folder.

Class: String Modiﬁable: No

view preferences

A reference to the Views control panel.

Class: String Modiﬁable: No

visible A Boolean value that indicates whether the Finder is currently

visible (true) or hidden (false).

Class: Boolean Modiﬁable: Yes

ELEMENT CLASSES

The Finder application can contain objects of any of the classes listed here. Page numbers indicate the locations of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Container Window (page 47)

Content Space (page 50)

Control Panel (page 51)

Desk Accessory File (page 55)

Desktop-Object (page 56)

Disk (page 57)

Document File (page 60)

34 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

File (page 61)

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Information Window (page 69)

Item (page 73)

Sharable Container (page 79)

Sharing Window (page 85)

Sound File (page 88)

Suitcase (page 90)

Trash-Object (page 91)

Window (page 95)

Elements of any of these classes can be identiﬁed by name or by number. With the exception of the desktop and window objects such as container windows and information windows, an element of the Finder can also be identiﬁed by an AppleScript alias record—that is, a representation of an object, much like an alias icon on the desktop, that identiﬁes the object. For example, both these statements refer to the same ﬁle:

alias "Hard Disk:MyFile" file "MyFile" of disk "Hard Disk"

In most cases the Finder can accept a reference like the ﬁrst example, but you can’t use a Finder reference like the second example outside of a Tell statement addressed to the Finder. This book describes how to use Finder references. For information about AppleScript references to alias records, ﬁles, applications, machines, and zones, see the AppleScript Language Guide.

Objects of class Application File, Disk, and Folder can also be identiﬁed by ID. The ID in each case consists of the application ﬁle’s creator type (as a string), the disk’s ID, and the folder’s folder ID, respectively. For example, this statement identiﬁes the startup disk:

disk ID -1

-—result: startup disk of application "Finder"

Object Class Deﬁnitions 35

CHAPTER 2

Finder Objects

This statement identiﬁes a folder:

folder ID 918 of startup disk

-—result: folder "My Folder" of startup disk of application "Finder"

This statement identiﬁes the TeachText application:

application file id "ttxt"

-—result: file "TeachText 7.1" of startup disk of application "Finder"

You can identify the frontmost window that lies under a particular point on the desktop by running a script like this:

tell application "Finder"

content space {100,100}

end tell

--result: window of folder "Projects" of startup disk of application "Finder"

The pair of integers in braces in the preceding example identiﬁes the point in which you’re interested, and the result contains a reference to the window that contains that point. It is usually easiest to use the term Content Space to obtain this kind of reference, because the script returns a reference even if the point is located on the desktop or in some specialized window such as an Information Window.

You can also specify more restricted window classes, such as Window, Container Window, Information Window, and so on. For example, if you request a reference to a container window for a point that’s located in some other kind of window, the Finder returns an error.

COMMANDS HANDLED

Clean Up, Computer, Count, Data Size, Exists, Get, Print, Quit, Restart, Select, Shut Down, Sleep, Sort

36 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

DEFAULT VALUE CLASS RETURNED

Reference.

EXAMPLES

This script turns on the Calculate Folder Sizes property of the Views control panel:

tell application "Finder"

set calculate folder sizes of view preferences to true

end tell

This script turns on ﬁle sharing for the local computer.

tell application "Finder"

set file sharing to true

end tell

The next example selects all the unselected items in the active window.

NOTES

tell application "Finder"

repeat with x in front window

set selected of x to not selected of x

end repeat

end tell

Although Startup Disk and Trash are properties of the desktop object, you can also refer to them as if they were properties of the Finder. Thus, the Finder interprets both of these statements are references to whatever disk is currently the startup disk:

startup disk startup disk of desktop

Object Class Deﬁnitions 37

CHAPTER 2

Finder Objects

Similarly, the Finder interprets both of these statements as a reference to the Trash:

trash trash of desktop

Application File 2

An object of class Application File is an application’s ﬁle on a disk. References to application ﬁles must always include a complete description of the ﬁle’s container. Such references are different from standard AppleScript references to application objects, which don’t always require a complete pathname.

PROPERTIES

An application ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, an application ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other ﬁles, an application ﬁle also has these properties:

minimum partition size

An integer indicating the minimum amount of memory, in bytes, that the application requires to run. This value is equivalent to the value in the box labeled “Minimum size” under “Memory Requirements” in the application ﬁle’s information window (see “Notes”).

Class: Integer Modiﬁable: Yes

partition size

An integer indicating the amount of memory, in bytes, that the application is launched with if a block of this size is available. This value is equivalent to the value in the box labeled “Preferred size” under “Memory Requirements” in the application ﬁle’s information window (see “Notes” on page 40).

Class: Integer Modiﬁable: Yes

38 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

scriptable A Boolean value that indicates whether the application is high-

suggested partition size

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Duplicate, Exists, Get, Make, Move, Open, Put Away, Reveal, Select, Sort, Update

level event aware (true) or not (false)—that is, whether it can respond to the Open, Run, Print, and Quit commands.

Class: Boolean Modiﬁable: No

An integer indicating the amount of memory, in bytes, suggested for running the application. This value is equivalent to the value in the box labeled “Suggested size” under “Memory Requirements” in the application ﬁle’s information window.

Class: Integer Modiﬁable: No

DEFAULT VALUE CLASS RETURNED

A reference to a ﬁle or, if you use the plural form application files, a list of references.

EXAMPLES

The script that follows checks the Scriptable Text Editor’s partition size before opening the application. If the amount of memory available is greater than the partition size, the script opens the application. If the amount of memory available is less than the partition size, the script displays a dialog box warning the user that the Scriptable Text Editor prefers more memory. This might be useful if a script performs actions requiring more memory than an application’s minimum partition size permits.

Object Class Deﬁnitions 39

CHAPTER 2

Finder Objects

tell application "Finder"

set x to largest free block set y to partition size of ¬

application file "Scriptable Text Editor" of startup disk if x > y then

open application file "Scriptable Text Editor" of startup disk else

display dialog ¬

"The Scriptable Text Editor prefers more memory. " & ¬ "To increase free memory, quit one or more applications."

end if

end tell

This script returns a list of all the application ﬁles in a folder:

tell application "Finder"

application files in folder "MyApps" of startup disk

end

--result: {file "Scriptable Text Editor" of folder "MyApps" of startup disk, file "Script Editor" of folder "MyApps" of startup disk}

NOTES

The Minimum Partition Size, Partition Size, and Suggested Partition Size are all given in bytes. These values are shown in information windows in kilobytes (K, where 1K = 1024 bytes).

The value of the Partition Size property must be at least as high as the value of the Minimum Partition Size property. If you set the Minimum Partition Size to a value higher than the value of the Partition Size, the Finder also adjusts the Partition Size to match the new Minimum Partition Size. Similarly, if you set the Partition Size to a value lower than the value of the Minimum Partition Size, the Finder also adjusts the Minimum Partition Size to match the new Partition Size.

For example, suppose that the Partition Size and the Minimum Partition Size of the Scriptable Text Editor are both set to 384K. Running this script sets the

40 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Minimum Partition size to 460,800 bytes (450K) and at the same time increases the Partition Size to 450K:

tell application "Finder"

set minimum partition size of ¬

application file "Scriptable Text Editor" of ¬ application "Finder" to 460800

end tell

If you then run this script, the Finder sets the Partition Size of the Scriptable Text Editor back to 393,216 bytes (384K) and at the same time decreases the Minimum Partition Size to 384K:

tell application "Finder"

set partition size of ¬

application file "Scriptable Text Editor" of ¬ application "Finder" to 393216

end tell

Application Process 2

An object of class Application Process is a process that has been launched from an application ﬁle.

PROPERTIES

An application process has all the properties deﬁned for object class Process on page 77: Creator Type, File, File Type, Frontmost, Name, Partition Size, Partition Space Used, Remote Events, Scriptable, and Visible.

An application process also has this property:

application file

The application ﬁle from which this process was launched.

Class: Reference Modiﬁable: No

Object Class Deﬁnitions 41

CHAPTER 2

Finder Objects

ELEMENT CLASSES

None

COMMANDS HANDLED

Count, Data Size, Exists, Get, Sort

DEFAULT VALUE CLASS RETURNED

A reference or, if you use the plural form application processes, a list of references of the form

application "ApplicationProcessName"

where ApplicationProcessName is the name of an application process as it appears in the Applications menu.

EXAMPLES

You can use a script like this to get a list of all the application processes that are currently running:

tell application "Finder"

application processes

end

--result: {application "HyperCard", application "Script Editor", application "Scriptable Text Editor"}

The following script hides the TeachText application process:

tell application "Finder"

set visible of application process "TeachText" to false

end tell

42 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Container 2

An object of class Container is any Finder container, such as a folder, a disk, or the Trash.

PROPERTIES

A container has all the properties deﬁned for object class object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other items, a container also has these properties:

completely expanded

A Boolean value that indicates whether a container and any folders it contains are completed expanded in list view (true) or not (false). For a container to be completely expanded, the window that contains the container must be open in list view (that is, any item other than “by Small Icon” or “by Icon” is selected in the Views menu for the window), the container and all nested folders within the it must be fully expanded with that same list view, and the container’s own window must be closed. Before you can set this property, the window that contains the container must already be open in a list view.

Class: Boolean Modiﬁable: Yes

container window

A reference to the container’s window.

Class: Modiﬁable: No

entire contents

A list of references to the entire contents of the container, including the contents of any other containers within the container.

Class: List of references Modiﬁable: No

Object Class Deﬁnitions 43

CHAPTER 2

Finder Objects

expandable A Boolean value that indicates whether the container can

be opened within its container in outline view (true) or not (false).

Class: Boolean Modiﬁable: No

expanded A Boolean value that indicates whether the item is open in

outline view (true) or not (false).

Class: Boolean Modiﬁable: Yes

previous list view

An integer between 2 and 8 or one of the corresponding constants

name, modification date, size, kind, comment, label index, or version. If the View property of the container is

currently one of these list views, the value of this property is the current list view. If the View property is small icon or icon, the value of this property is the last list view selected. If no list view has been selected since the container was ﬁrst opened, the value of this property is name. You can’t get or set this property unless the container is open, and the value of the property isn’t retained after the container has been closed.

Class: Integer Modiﬁable: No

selection A list of references to the container elements that are currently

selected. The elements in the selection are those that would be cut by a Cut command or copied by a Copy command. If no elements are selected, the value of the Selection property is an empty list.

Class: List of references Modiﬁable: Yes

view An integer between 0 and 8 or one of the corresponding constants

small icon, icon, name, modification date, size, kind, comment, label index, or version, indicating the current

selection in the View menu for the container’s window. You can’t get or set this property unless the container is open.

Class: Integer Modiﬁable: Yes

44 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

ELEMENT CLASSES

Objects of these classes can be identiﬁed at the top level of a container by name or by number. Page numbers indicate the location of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a container or, if you use the plural form containers, a list of references.

Object Class Deﬁnitions 45

EXAMPLES

CHAPTER 2

Finder Objects

The ﬁrst example opens all the containers on the desktop except for the Trash.

tell application "Finder"

open (containers in desktop whose name is not "Trash")

end tell

The next example, if saved as a script application, toggles the value of the Completely Expanded property of all containers at the top level of the front window: that is, it alternately expands all the containers and their nested containers or collapses them. The window in which the script application is located must be open in list view for the script to work on the window’s contents.

property expan : false

tell application "Finder"

if expan = false then

set completely expanded of containers in ¬

container of front window to true

set expan to true

else

set completely expanded of containers in ¬

container of front window to false

set expan to false

end if

end tell

The script begins by declaring the value of the expan property to be false. This property is a Boolean value that changes after the script is run. The script sets expan to true whenever it sets the Completely Expanded property of the front window’s containers to true, or to false whenever it sets their Completely Expanded property to false.

The value of the property container of front window is a reference to the container to which the window belongs. This script must specify the Container property of the window, rather than the window itself, or it may not work consistently. A window’s container always has a ﬁxed number of elements until new elements are added or deleted, whereas a window open in list view has a variable number of elements depending on which folders are expanded.

46 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Container Window 2

An object of class Container Window is a window for a container. For example, the windows for a disk, a folder, or a suitcase are all container windows, while a control panel window, the About This Macintosh window, and an information window are not.

PROPERTIES

A container window has all the properties deﬁned for object class Window on page 95: Bounds, Closeable, Floating, Index, Modal, Position, Resizable, Titled, Visible, Zoomable, and Zoomed.

Unlike other windows, a container window also has these properties:

container A reference to the container to which the container

window belongs.

Class: Reference Modiﬁable: No

disk A reference to the disk on which the container to which the

window belongs is stored.

Class: Reference Modiﬁable: No

folder A reference to the folder to which the container window belongs

(available only for container windows of folders).

Class: Reference Modiﬁable: No

item A reference to the item to which the container window belongs.

Class: Reference Modiﬁable: No

previous list view

An integer between 2 and 8 or one of the corresponding constants

name, modification date, size, kind, comment, label index, or version. If the View property of the container

window is currently one of these list views, the value of this property is the current list view. If the View property is small icon or icon, the value of this property is the last list view selected. If no list view has been selected since the container window was ﬁrst opened, the value of this property is name.

Object Class Deﬁnitions 47

CHAPTER 2

Finder Objects

selection A reference to the current selection.

view An integer between 0 and 8 or one of the corresponding

ELEMENT CLASSES

The elements of a container window include all the items currently displayed inside the window. When folders in a window whose View property is name, date, size, or kind are expanded in outline view, the elements of the expanded folder become elements of the container window in which the folder is located.

You can’t get or set this property unless the container window is open, and the value of the property isn’t retained after the container window has been closed.

Class: Integer Modiﬁable: No

Class: Reference or list of references Modiﬁable: No

constants small icon, icon, name, modification date, size, kind, comment, label index, or version, indicating

the current selection in the View menu for the container window. You can’t get or set this property unless the container window is open.

Class: Integer Modiﬁable: Yes

Objects of the classes listed here can be identiﬁed at the top level of a container window by name or by number. Page numbers indicate the location of deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

Folder (page 63)

48 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Close, Count, Data Size, Exists, Get, Open, Print, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form container windows, a list of references.

EXAMPLE

The script that follows tiles all the open container windows in an overlapping pattern and sets each window’s View property to 3 (“by Names”).

set {a, b, c, d} to {4, 44, 267, 311} tell application "Finder"

repeat with n from 1 to (count of container windows)

if n = 1 then

set bounds of container window n to {a, b, c, d}

else

set {a, b, c, d} to {a + 20, b + 20, c + 20, d + 20} set tiledBounds to {a, b, c, d}

set bounds of container window n to tiledBounds end if set view of container window n to 3 open container window n

end repeat

end tell

Object Class Deﬁnitions 49

CHAPTER 2

Finder Objects

The phrase count of container windows at the beginning of the Repeat loop requests that the Finder count all the container windows. Windows that aren’t container windows, such as information windows, are ignored. The Finder returns an integer, which the Repeat statement uses as the number of times to repeat.

The If statement within the Repeat statement resets the bounds of each successive container window so that it is shifted down and to the right from the previously tiled window. After the View for each container window is set, the last statement within the Repeat statement sends an Open command to that window so that it overlaps the previously tiled window.

Content Space 2

An object of class Content Space can be any Finder content space, including a container window, the desktop, an information window, a sharing window, a status window, or a window.

PROPERTIES

None

ELEMENT CLASSES

Like any window, a content space can contain any of the elements that can be contained by the object to which it belongs.

COMMANDS HANDLED

Clean Up, Close, Count, Data Size, Exists, Get, Open, Print, Sort, Update

DEFAULT VALUE RETURNED

Reference to a content space or, if you use the plural form content spaces, a list of references.

50 Object Class Deﬁnitions

EXAMPLE

CHAPTER 2

Finder Objects

This script returns a list of all Finder content spaces that are currently open, including the desktop:

tell application "Finder"

content spaces

end tell

For more information about using content spaces in scripts, see “References to Finder Windows,” which begins on page 22.

Control Panel 2

An object of class Control Panel is a control panel ﬁle on a disk.

PROPERTIES

A control panel has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, a control panel also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other kinds of ﬁles and unlike other control panels, the Views control panel may also have these properties:

Object Class Deﬁnitions 51

CHAPTER 2

Finder Objects

calculate folder sizes

A Boolean value that indicates whether the checkbox labeled “Calculate folder sizes” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

comment heading

A Boolean value that indicates whether the checkbox labeled “Show comments” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

date heading

A Boolean value that indicates whether the checkbox labeled “Show date” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

disk information heading

A Boolean value that indicates whether the checkbox labeled “Show disk info in header” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

icon size An integer indicating the icon size selected under List Views in

the Views control panel: 0 for the largest size, 1 for the medium size, and 2 for the smallest size.

Class: Integer Modiﬁable: Yes

kind heading

A Boolean value that indicates whether the checkbox labeled “Show kind” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

52 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

label heading

A Boolean value that indicates whether the checkbox labeled “Show label” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

size heading

A Boolean value that indicates whether the checkbox labeled “Show size” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

snap to grid

A Boolean value that indicates whether the checkbox labeled “Always snap to grid” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

staggered grid

A Boolean value that indicates whether the checkbox labeled “Staggered grid” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

version heading

A Boolean value that indicates whether the checkbox labeled “Show version” in the Views control panel is selected (true) or not (false).

Class: Boolean Modiﬁable: Yes

view font The ID of the font selected in the Views control panel.

Class: Integer Modiﬁable: Yes

view font size

The size of the font selected in the Views control panel.

Class: Integer Modiﬁable: Yes

Object Class Deﬁnitions 53

CHAPTER 2

Finder Objects

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form control panels, a list of references.

EXAMPLES

This script turns on the Snap to Grid property of the Views control panel:

tell application "Finder"

set snap to grid of control panel "Views" of ¬

control panels folder to true

end tell

You can also use the View Preferences property of the Finder application object as a reference to the Views control panel. For example, this script toggles the Date Heading property of the Views control panel on and off:

tell application "Finder"

set date heading of view preferences to ¬

not date heading of view preferences

end tell

54 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Desk Accessory File 2

An object of class Desk Accessory File is a desk accessory ﬁle on a disk.

PROPERTIES

A desk accessory ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, a desk accessory ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Set, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form desk accessory files, a list of references.

EXAMPLE

This script opens all the desk accessory ﬁles listed in the Apple menu:

tell application "Finder"

open desk accessory files in apple menu items folder

end tell

Object Class Deﬁnitions 55

CHAPTER 2

Finder Objects

Desktop-Object 2

An object of class Desktop-Object is the desktop of a computer. The Desktop property of the Finder application is a reference to an object of this class.

PROPERTIES

A desktop-object has some (but not all) of the properties deﬁned for object class Container on page 43: Container Window, Entire Contents, Previous List View, Selection, and View.

A desktop-object also has some of the properties deﬁned for object class Item on page 73: Comment, Content Space, Creation Date, Disk, Kind, Modiﬁcation Date, Name, Physical Size, Selected, Size, and Window.

Unlike other containers, a desktop-object also has these properties:

startup disk

A reference to the startup disk from which the Finder application was launched.

trash A reference to the Trash folder.

ELEMENT CLASSES

Objects of these classes can be identiﬁed at the top level of the desktop-object by name or by number. Page numbers indicate the location of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

56 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Count, Data Size, Exists, Get, Print, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference.

EXAMPLE

To refer to a desktop-object, you must use the Desktop property of the Finder application:

tell application "Finder"

clean up desktop

end tell

For more information about the Desktop property, see “Properties and Elements of the Finder,” which begins on page 20.

Disk 2

An object of class Disk is any mounted volume on the desktop. In addition to hard disks and ﬂoppy disks, objects of class Disk can include RAM disks, tape drives, CD-ROM disks, and other storage devices.

Object Class Deﬁnitions 57

PROPERTIES

CHAPTER 2

Finder Objects

A disk has all the properties deﬁned for object class Sharable Container on page 79: Exported, Group, Group Privileges, Guest Privileges, Inherited Privileges, Mounted, Owner, Owner Privileges, Protected, Shared, Sharing Window.

Like any other sharable container, a disk also has all the properties deﬁned for object class Container on page 43: Completely Expanded, Container Window, Entire Contents, Expandable, Expanded, Previous List View, Selection, and View.

In addition, like any other container, a disk has all properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other sharable containers or containers, a disk also has the following properties:

capacity The total number of bytes that can ﬁt on the disk.

Class: Integer Modiﬁable: No

ejectable A Boolean value that indicates whether the disk can be ejected

or put away (true) or not (false).

Class: Boolean Modiﬁable: No

free space The total number of bytes of free space remaining on the disk.

Class: Integer Modiﬁable: No

local volume

A Boolean value that indicates whether the disk is a local (true) or remote (false) volume.

Class: Boolean Modiﬁable: No

startup A Boolean value that indicates whether a disk is the startup

disk (true) or not (false).

Class: Boolean Modiﬁable: No

58 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

ELEMENT CLASSES

Objects of the classes listed here can be identiﬁed at the top level of a disk by name or by number. Page numbers indicate the location of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form disks, a list of references.

Object Class Deﬁnitions 59

CHAPTER 2

Finder Objects

EXAMPLE

The script that follows tests the Ejectable property of each item in a list of the mounted disks and ejects every disk that’s ejectable.

tell application "Finder"

put away (every disk whose ejectable is true)

end tell

Document File 2

An object of class Document File is a document ﬁle on a disk.

PROPERTIES

A document ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, a document ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Print, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

Reference to a ﬁle or, if you use the plural form document files, a list of references.

60 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

EXAMPLE

This script opens all the document ﬁles at the top level of a disk:

tell application "Finder"

open document files in window "My World"

end tell

Application ﬁles, desk accessories, suitcases, and other nondocument ﬁles are ignored.

File 2

An object of class File can be any ﬁle on a disk, including document ﬁles, application ﬁles, and so on.

PROPERTIES

A ﬁle has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Unlike other items, a ﬁle also has these properties:

creator type

A four-character code that indicates the creator type of the application that created the ﬁle.

Class: String Modiﬁable: Yes

file type A four-character code that indicates the type of the ﬁle.

Class: String Modiﬁable: Yes

locked A Boolean value that indicates whether the ﬁle is locked (true)

or not (false).

Class: Boolean Modiﬁable: Yes

Object Class Deﬁnitions 61

CHAPTER 2

Finder Objects

product version

stationery A Boolean value that indicates whether the ﬁle is a stationery

version The version number shown near the middle of the information

ELEMENT CLASSES

None

The version number shown at the top of the information window for the ﬁle.

Class: String Modiﬁable: No

pad (true) or not (false).

Class: Boolean Modiﬁable: Yes

window for the ﬁle.

Class: String Modiﬁable: No

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Make, Move, Open, Print, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a ﬁle or, if you use the plural form files, a list of references.

EXAMPLES

This script returns a list of references to the ﬁles whose modiﬁcation dates are greater than a speciﬁed date:

tell application "Finder"

files of startup disk whose modification date > ¬

date "November 18, 1993"

end tell

62 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

If you save this script as a script application, it copies a new icon to any ﬁles whose icons you drop on the script’s icon. The script uses the scripting addition command Choose File to ask the user to specify which ﬁle’s icon is to be copied:

on open x

tell application "Finder"

choose file with prompt ¬

"Choose the file whose icon you want to copy:" set newIcon to icon of the result repeat with i in x

set the icon of i to newIcon end repeat

end tell

end open

Folder 2

An object of class Folder is a folder on a disk.

PROPERTIES

A folder has all the properties deﬁned for object class Sharable Container on page 79: Exported, Group, Group Privileges, Guest Privileges, Inherited Privileges, Mounted, Owner, Owner Privileges, Protected, Shared, Sharing Window.

Like any other sharable container, a folder also has all the properties deﬁned for object class Container on page 43: Completely Expanded, Container Window, Entire Contents, Expandable, Expanded, Previous List View, Selection, and View.

In addition, like any other container, a folder has all properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Object Class Deﬁnitions 63

CHAPTER 2

Finder Objects

ELEMENT CLASSES

Objects of these classes can be identiﬁed at the top level of the folder by name or by number. Page numbers indicate the location of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Make, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference or, if you use the plural form folders, a list of references.

64 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

EXAMPLE

This script returns references to all the folders at the top level of the startup disk that have been modiﬁed in the last 24 hours:

tell application "Finder"

folders of startup disk where ¬

modification date > ((current date) - 24 * hours)

end tell

Font File 2

An object of class Font File is a ﬁle that contains font data.

PROPERTIES

A font ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, a font ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Content Space, Container, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

Object Class Deﬁnitions 65

CHAPTER 2

Finder Objects

DEFAULT VALUE CLASS RETURNED

A reference to a ﬁle or, if you use the plural form font files, a list of references.

EXAMPLE

If you save this script as a script application, it opens font suitcases or any other containers you drop on its icon and opens the windows for any font ﬁles they contain.

on open x

repeat with i in x

tell application "Finder"

open i open font files in i

end tell

end repeat

end open

Font Suitcase 2

An object of class Font Suitcase is a suitcase ﬁle that contains font information.

PROPERTIES

A font suitcase has all the properties deﬁned for object class Container on page 43: Completely Expanded, Container Window, Entire Contents, Expandable, Expanded, Previous List View, Selection, and View.

Like any other container, a font suitcase also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

ELEMENT CLASSES

Items within a font suitcase can be identiﬁed by name or by number. For more information, see the deﬁnition of object class Item on page 73.

66 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a suitcase or, if you use the plural form font suitcases, a list of references.

EXAMPLE

The script that follows moves a font suitcase called Janson Text into or out of the Fonts folder, ﬁrst asking the user to conﬁrm the move. (If you are using version 1.1 of the Finder scripting software, a second dialog box appears when the Finder is moving suitcases into the Fonts folder, warning the user that the suitcases won’t be available to running applications right away.)

tell application "Finder"

activate set x to name of items in fonts folder if "Janson Text" is in x then

set response to display dialog ¬

"Remove the Janson fonts from the System?"

if button returned of response is "OK" then

move font suitcase "Janson Text" of fonts folder to ¬

folder "Font Storage" of startup disk

end if

else

set response to display dialog ¬

"Move the Janson fonts into the System?"

if button returned of response is "OK" then

move font suitcase "Janson Text" ¬

of folder "Font Storage" of startup disk to fonts folder

end if

end tell

Object Class Deﬁnitions 67

CHAPTER 2

Finder Objects

Group 2

An object of class Group is a group ﬁle in the Users & Groups control panel window. The Finder can’t recognize or create a group unless the Users & Groups control panel window is open.

PROPERTIES

bounds The coordinates of the rectangle that bounds the content region

of the item’s icon. Class: List of four integers (Bounding Rectangle data type). The ﬁrst two integers specify the coordinates of the upper-left corner of the item’s icon, and the last two integers specify the coordinates of the lower-right corner of the icon. Modiﬁable? Yes

icon A bitmap of the item’s icon.

Class: Icon family (data type deﬁned by Finder) Modiﬁable: Yes

label index

The number of the label currently selected for the item in the Label menu (None = 0).

Class: Integer Modiﬁable: Yes

name The group’s name.

Class: String Modiﬁable: Yes

position Tw o integers that specify the position of the upper-left corner of

the group’s icon. Class: List of two integers (Point data type) that specify the coordinates of the upper-left corner of the group’s icon Modiﬁable? Yes

ELEMENT CLASSES

None

68 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

COMMANDS HANDLED

Clean Up, Close, Count, Data Size, Exists, Get, Make, Open, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a group or, if you use the plural form groups, a list of references.

EXAMPLE

This script displays a dialog box requesting the name of the new group to create, then opens the control panel Users & Groups, creates the new group, and sets its name:

tell application "Finder"

set response to display dialog ¬

"Name of new group:" default answer ""

set newGroup to text returned of response set cPanels to control panel "Users & Groups" of ¬

control panels folder

open cPanels make group at cPanels with properties {name: newGroup}

end tell

Information Window 2

An object of class Information Window is the window that opens when you select an item and choose Get Info from the File menu.

PROPERTIES

An information window has all the properties deﬁned for object class Window on page 95: Bounds, Closeable, Floating, Index, Modal, Position, Resizable, Titled, Visible, Zoomable, and Zoomed.

Object Class Deﬁnitions 69

CHAPTER 2

Finder Objects

Unlike other windows, an information window also has these properties:

comment The comment displayed in the information window.

Class: String Modiﬁable: Yes

creation date

The date on which the item to which the information window belongs was created.

Class: Date Modiﬁable: No

icon A bitmap of the icon for the item to which the information

window belongs.

Class: Icon family (data type deﬁned by Finder) Modiﬁable: Yes

item A reference to the item to which the information window

belongs.

Class: Reference Modiﬁable: No

locked A Boolean value that indicates whether the ﬁle to which the

information window belongs is locked (true) or not (false).

Class: Boolean Modiﬁable: Yes

minimum partition size

An integer indicating the minimum amount of memory, in bytes, that an application requires to run (available only for information windows that belong to application ﬁles). This value is equivalent to the value in the box labeled “Minimum size” under “Memory Requirements” in the information window (see “Notes”).

Class: Integer Modiﬁable: Yes

modification date

The date on which the item to which the information window belongs was most recently modiﬁed.

Class: Date Modiﬁable: No

70 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

partition size

An integer indicating the amount of memory, in bytes, that an application is launched with if a block of this size is free (available only for information windows that belong to application ﬁles). This value is equivalent to the value in the box labeled “Preferred size” under “Memory Requirements” in the information window (see “Notes”).

Class: Integer Modiﬁable: Yes

physical size

The physical size of the item on disk, in bytes. Class: Integer Modiﬁable: No

product version

The version number shown at the top of the information window.

Class: String Modiﬁable: No

size The logical size of the item on disk, in bytes.

Class: Integer Modiﬁable: No

stationery A Boolean value that indicates whether a document ﬁle is

a stationery pad (true) or not (false) (available only for information windows that belong to document ﬁles.)

Class: Boolean Modiﬁable: Yes

suggested partition size

An integer indicating the amount of memory, in bytes, suggested for running an application (available only for information windows that belong to application ﬁles). This value is equivalent to the value in the box labeled “Suggested size” under “Memory Requirements” in the information window (see “Notes”).

Class: Integer Modiﬁable: No

version The version number shown near the middle of the information

window.

Class: String Modiﬁable: No

Object Class Deﬁnitions 71

CHAPTER 2

Finder Objects

warn before emptying

A Boolean value that indicates whether the Finder should warn the user before emptying the Trash (true) or not (false) (available only for the Trash).

Class: String Modiﬁable: Yes

ELEMENT CLASSES

None

COMMANDS HANDLED

Close, Count, Data Size, Exists, Get, Open, Sort

DEFAULT VALUE CLASS RETURNED

A reference to an information window or, if you use the plural form information windows, a list of references.

EXAMPLE

This script opens the information windows for all application ﬁles in a disk whose partition sizes are greater than 1000K:

tell application "Finder"

open (information window of application files of ¬

disk "Applications" whose partition size > 1024000)

end tell

NOTES

The Minimum Partition Size, Partition Size, and Suggested Partition Size are all given in bytes. These values are shown in information windows in kilobytes (K, where 1K = 1024 bytes). For more information about the relationships among these properties, which are identical to the properties of the same name deﬁned for class Application File, see page 40.

72 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Item 2

An object of class Item is any item in a container.

PROPERTIES

bounds The coordinates of the rectangle that bounds the content region

of the item’s icon. Class: List of four integers (Bounding Rectangle data type). The ﬁrst two integers specify the coordinates of the upperleft corner of the item’s icon, and the last two integers specify the coordinates of the lower-right corner of the icon. Modiﬁable? Yes

comment The comment displayed in the item’s information window.

Class: String Modiﬁable: Yes

container A reference to the container in which the item is located.

Class: Reference Modiﬁable: No

content space

A reference to the content space that opens when the item is opened.

Class: Content Space Modiﬁable: No

creation date

The date on which the item was created.

Class: Date Modiﬁable: No

disk A reference to the disk on which the item is stored.

Class: Reference Modiﬁable: No

folder A reference to the folder, if any, in which the item is stored.

Class: Reference Modiﬁable: No

icon A bitmap of the item’s icon.

Class: Icon family (data type deﬁned by Finder) Modiﬁable: Yes

Object Class Deﬁnitions 73

CHAPTER 2

Finder Objects

id The item’s hierarchical ﬁle system (HFS) ID number, an integer

that identiﬁes an application ﬁle, folder, or disk. (For examples of the use of this property, see page 35.)

Class: Integer Modiﬁable: No

information window

A reference to the item’s information window.

Class: Reference Modiﬁable: No

kind The kind of item as listed under Kind in the item’s

container window.

Class: String Modiﬁable: No

label index

The number of the label currently selected for the item in the Label menu (None = 0).

Class: Integer Modiﬁable: Yes

modification date

The date on which the item was most recently modiﬁed.

Class: Date Modiﬁable: No

name The item’s name.

Class: String Modiﬁable: Yes

physical size

The physical size of the item on disk, in bytes. Class: Integer Modiﬁable: No

position Tw o integers that specify the position of the upper-left corner of

the item’s icon.

Class: List of two integers (Point data type) Modiﬁable? Yes

selected A Boolean value that indicates whether the item is selected

(true) or not (false).

Class: Boolean Modiﬁable: Yes

74 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

size The logical size of the item on disk, in bytes.

Class: Integer Modiﬁable: No

window A reference to the window that opens when the item is opened.

Class: Reference Modiﬁable: No

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a ﬁle, folder, disk, the Trash, or the desktop or, if you use the plural form items, a list of references.

EXAMPLES

The script that follows moves a group of items that start with an at (@) symbol back and forth between the Apple Menu Items folder and a folder at the top level of the startup disk called Apple Menu Extras.

To work correctly, this script must be stored as a script application at the top level of the startup disk; the startup disk must also contain a folder called Apple Menu Extras to store the items you want to move in and out of the Apple Menu Items folder; and the names of the items in the Apple Menu Items folder must all begin with an @ symbol. It is also important, as with any script, to have some free memory available in addition to the memory used by any currently running processes—preferably several hundred kilobytes.

Object Class Deﬁnitions 75

CHAPTER 2

Finder Objects

property Extras : false

tell application "Finder"

if (exists item " Add Extras" of apple menu items folder) ¬

= false and ¬ (exists item " Remove Extras" of apple menu items folder) ¬

= false then

make alias file with data (file "Toggle Apple Menu Extras" of ¬

startup disk) at apple menu items folder ¬ with properties {name:" Add Extras"}

end if

if Extras is false then

move contents of folder "Apple Menu Extras" of startup disk to ¬

apple menu items folder

set the name of item " Add Extras" in apple menu items folder ¬

to " Remove Extras"

set Extras to true

else

move (every item of apple menu items folder ¬

whose name begins with "@") to ¬ folder "Apple Menu Extras" of startup disk

set the name of item " Remove Extras" in ¬

apple menu items folder to " Add Extras"

set Extras to false

end if

end tell

The script begins by declaring the value of the Extras property to be false. This value may change after the script is run.

If the script hasn’t been run before, the ﬁrst If statement in the script creates an alias ﬁle of the script application in the Apple Menu Items folder with the name Add Extras. This alias ﬁle appears in the Apple menu along with all the other

76 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

items in the Apple Menu Items folder, and its name changes to Remove Extras after the extra items have been added to that folder.

If the value of Extras is false, the ﬁrst part of the second If statement moves the contents of the Apple Menu Extras folder into the Apple Menu Items folder, changes the name of the alias ﬁle to Remove Extras, and sets the value of Extras to true.

If the value of Extras is true, the second part of the second If statement moves all items in the Apple Menu Items folder that begin with an @ symbol into the Apple Menu Extras folder, changes the name of the alias ﬁle to Add Extras, and sets the value of Extras to false.

Process 2

An object of object class Process is a running process.

PROPERTIES

creator type

A four-character code that indicates the creator type of the application from which the process was launched.

Class: String Modiﬁable: No

file A reference to the ﬁle from which the process was launched.

Class: Reference Modiﬁable: No

file type A four-character code that indicates the ﬁle type of the ﬁle.

Class: String Modiﬁable: No

frontmost A Boolean value that indicates whether the process is the

frontmost process (true) or not (false).

Class: Boolean Modiﬁable: Yes

name The name of the process.

Class: Reference Modiﬁable: No

Object Class Deﬁnitions 77

CHAPTER 2

Finder Objects

partition size

An integer indicating the amount of memory, in bytes, that a process is launched with if a free block of this size exists. This value is equivalent to the value in the box labeled “Preferred size” under “Memory Requirements” in the information window for the application ﬁle from which the process was launched, except that the value in the information window is given in kilobytes (K, where 1K = 1024 bytes).

Class: Integer Modiﬁable: No

partition space used

The number of bytes currently used in the partition for this process.

Class: Integer Modiﬁable: No

remote events

A Boolean value that indicates whether this process accepts (true) or doesn’t accept (false) remote events.

Class: Boolean Modiﬁable: No

scriptable A Boolean value that indicates whether the process is high-level

event aware (true) or not (false)—that is, whether it can respond to the Open, Run, Print, and Quit commands.

Class: Boolean Modiﬁable: No

visible A Boolean value that indicates whether the process is currently

hidden or not.

Class: Boolean Modiﬁable: Yes

ELEMENT CLASSES

None

COMMANDS HANDLED

Count, Data Size, Exists, Get, Sort

78 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

DEFAULT VALUE CLASS RETURNED

A reference or (if you use the plural form processes) a list of references of the form

application "ProcessName"

where ProcessName is the name of a process as it appears in the Applications menu.

EXAMPLE

In the ﬁrst version of the Finder scripting software, this script returns a list of all processes except the Finder itself:

tell application "Finder"

every process

end tell

In later versions, the list of processes returned includes the Finder. To exclude the Finder, use the statement every process whose file type is not "FNDR".

Sharable Container 2

An object of class Sharable Container is a container that can be shared.

PROPERTIES

A sharable container has all the properties deﬁned for object class Container on page 43: Completely Expanded, Container Window, Entire Contents, Expandable, Expanded, Previous List View, Selection, and View.

Like any other container, a sharable container also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

Object Class Deﬁnitions 79

CHAPTER 2

Finder Objects

Unlike other containers, a sharable container also has these properties:

exported A Boolean value that indicates whether the sharable container is

either shared or inside another container whose contents are being shared. If one of these conditions is true, the value is true and the sharable container can be mounted or accessed remotely; if neither of these conditions is true, the value is false and the container isn’t available to remote computers.

Class: Boolean Modiﬁable: No

group The name of the user or group with special access to the sharable

container, as indicated in the pop-up menu labeled User/Group in the sharing window for the container.

Class: String Modiﬁable: Yes

group privileges

The group privileges shown in the Sharing window for the container. For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for a user or group, the value of this property is "See Files, Make Changes" (see “Notes” on page 83).

Class: Sharing Privileges Modiﬁable: Yes

guest privileges

The guest privileges shown in the sharing window for the container (that is, the settings labeled Everybody). For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for Everybody, the value of this property is "See Files, Make Changes" (see “Notes” on page 83).

Class: Sharing Privileges Modiﬁable: Yes

inherited privileges

A Boolean value that indicates whether the privileges for the sharable container are the same as the privileges for the container in which it is stored (true) or not (false). This property corresponds to the checkbox in the sharing window labeled “Same as enclosing folder”. The value of this property is

80 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

set to false if you set any of the group, guest, or owner privileges individually.

Class: Boolean Modiﬁable: Yes

mounted A Boolean value that indicates whether the sharable container is

mounted on another computer’s desktop (true) or not (false).

Class: Boolean Modiﬁable: No

owner The name of the sharable container’s owner as indicated in the

sharing window for the container.

Class: String Modiﬁable: Yes

owner privileges

The owner privileges shown in the sharing window for the sharable container. For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for the container’s owner, the value of this property is "See Files, Make Changes" (see “Notes” on page 83).

Class: Sharing Privileges Modiﬁable: Yes

protected A Boolean value that indicates whether the sharable container is

protected (true) or not (false). This property corresponds to the checkbox in the sharable container’s sharing window labeled “Can’t be moved, renamed, or deleted”.

Class: Boolean Modiﬁable: Yes

shared A Boolean value that indicates whether the sharable container

and its contents are shared (true) or not (false). This property corresponds to the checkbox in the sharable container’s sharing window labeled “Share this item and its contents”. If the value is true, the sharable container can be mounted on the desktop of a remote computer.

Class: Boolean Modiﬁable: Yes

sharing window

A reference to the sharing window for the sharable container.

Class: Reference Modiﬁable: No

Object Class Deﬁnitions 81

CHAPTER 2

Finder Objects

ELEMENT CLASSES

Objects of these classes can be identiﬁed at the top level of a sharable container by name or by number. Page numbers indicate the location of corresponding deﬁnitions in this chapter.

Accessory Suitcase (page 27)

Alias File (page 28)

Application File (page 38)

Container (page 43)

Control Panel (page 51)

Desk Accessory File (page 55)

Document File (page 60)

File (page 61)

Folder (page 63)

Font File (page 65)

Font Suitcase (page 66)

Item (page 73)

Sharable Container (page 79)

Sound File (page 88)

Suitcase (page 90)

COMMANDS HANDLED

Clean Up, Close, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

DEFAULT VALUE CLASS RETURNED

A reference to a disk or a folder or, if you use the plural form sharable containers, a list of references.

82 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

EXAMPLE

This script changes the Shared property to false for all sharable containers that belong to a speciﬁed owner:

tell application "Finder"

set shared of sharable containers whose owner is "Greg" to false

end tell

NOTES

The properties Group Privileges, Guest Privileges, and Owner Privileges each return an object of class Sharing Privileges. You can test for a speciﬁc privilege by checking the values of the Sharing Privileges properties as described in the next section.

Sharing Privileges 2

PROPERTIES

An object of class Sharing Privileges corresponds to the group privileges, guest privileges, or owner privileges selected in the sharing window for a sharable container.

make changes

A Boolean value that corresponds to the Make Changes checkbox for a speciﬁed user or group is selected in a sharable container’s sharing window.

Class: Boolean Modiﬁable: Yes

see files A Boolean value that corresponds to the See Files checkbox for

a speciﬁed user or group is selected in a sharable container’s sharing window.

Class: Boolean Modiﬁable: Yes

Object Class Deﬁnitions 83

CHAPTER 2

Finder Objects

see folders

A Boolean value that corresponds to the See Folders checkbox for a speciﬁed user or group is selected in a sharable container’s sharing window.

Class: Boolean Modiﬁable: Yes

ELEMENT CLASSES

None

COMMANDS HANDLED

None

DEFAULT VALUE CLASS RETURNED

None

EXAMPLE

This script returns a Boolean value that indicates whether the checkbox labeled “See ﬁles” for the current User/Group in the startup disk’s sharing window is selected or not:

tell application "Finder"

see files of group privileges of startup disk

end tell

--result: true

84 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

Sharing Window 2

An object of class Sharing Window is a sharing window that appears when you choose Sharing from the File menu while a sharable container is selected.

PROPERTIES

A sharing window has all the properties deﬁned for object class Window on page 95: Bounds, Closeable, Floating, Index, Modal, Position, Resizable, Titled, Visible, Zoomable, and Zoomed.

Unlike other windows, a sharing window also has these properties:

container A reference to the container to which the sharing

window belongs.

Class: Reference Modiﬁable: No

exported A Boolean value that indicates whether the container to which

the sharing window belongs is either shared or inside another container whose contents are being shared. If one of these conditions is true, the value is true and the container can be mounted or accessed remotely; if neither of these conditions is true, the value is false and the container isn’t available to remote computers.

Class: Boolean Modiﬁable: No

folder A reference to the folder, if any, to which the sharing

window belongs.

Class: Reference Modiﬁable: No

group The name of the user or group selected in the pop-up menu

labeled User/Group.

Class: String Modiﬁable: Yes

Object Class Deﬁnitions 85

CHAPTER 2

Finder Objects

group privileges

The group privileges selected in the sharing window. For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for a user or group, the value of this property is "See Files, Make Changes" (see page 83 for the definition of Sharing Privileges).

Class: Sharing Privileges Modiﬁable: Yes

guest privileges

The guest privileges selected in the sharing window (that is, the settings labeled Everybody). For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for Everybody, the value of this property is "See Files, Make Changes" (see page 83 for the deﬁnition of Sharing Privileges).

Class: Sharing Privileges Modiﬁable: Yes

inherited privileges

A Boolean value that indicates whether the privileges for the object to which the sharing window belongs are the same as the privileges for the container in which the object is stored (true) or not (false). This property corresponds to the checkbox in the sharing window labeled “Same as enclosing folder”. The value of this property is set to false if you set any of the group, guest, or owner privileges individually.

Class: Boolean Modiﬁable: Yes

item The item to which the sharing window belongs.

Class: Reference Modiﬁable: No

mounted A Boolean value that indicates whether the sharable container to

which the sharing window belongs is mounted on another computer’s desktop (true) or not (false).

Class: Boolean Modiﬁable: No

owner The name of the sharable container’s owner.

Class: String Modiﬁable: Yes

86 Object Class Deﬁnitions

CHAPTER 2

Finder Objects

owner privileges

The owner privileges selected in the sharing window. For example, if the See Folders checkbox is not selected and the See Files and Make Changes checkboxes are selected for the container’s owner, the value of this property is "See Files, Make Changes" (see page 83 for the definition of Sharing Privileges).

Class: Sharing Privileges Modiﬁable: Yes

protected A Boolean value that indicates whether the sharable container is

protected (true) or not (false). A protected container can’t be moved, renamed, or deleted. This property corresponds to the checkbox labeled “Can’t be moved, renamed, or deleted” and is not available for disks.

Class: Boolean Modiﬁable: Yes

sharable container

The sharable container to which the sharing window belongs.

Class: Reference Modiﬁable: No

shared A Boolean value that indicates whether the sharable container

to which the sharing window belongs is shared (true) or not (false). This property corresponds to the checkbox in the sharing window labeled “Share this item and its contents”. If the value is true, the sharable container to which the sharing window belongs can be mounted on the desktop of a remote computer.

Class: Boolean Modiﬁable: Yes

ELEMENT CLASSES

None

COMMANDS HANDLED

Close, Count, Data Size, Exists, Get, Open, Sort

Object Class Deﬁnitions 87

CHAPTER 2

Finder Objects

DEFAULT VALUE CLASS RETURNED

A reference to a sharing window or, if you use the plural form sharing windows, a list of references.

EXAMPLE

This script opens the sharing windows for sharable containers on the desktop that belong to a speciﬁed owner:

tell application "Finder"

open (sharing window of sharable containers whose owner is "John")

end tell

Sound File 2

An object of class Sound File is a sound ﬁle.

PROPERTIES

A sound ﬁle has all the properties deﬁned for object class File on page 61: Creator Type, File Type, Locked, Product Version, Stationery, and Version.

Like any other ﬁle, a sound ﬁle also has all the properties deﬁned for object class Item on page 73: Bounds, Comment, Container, Content Space, Creation Date, Disk, Folder, Icon, ID, Information Window, Kind, Label Index, Modiﬁcation Date, Name, Physical Size, Position, Selected, Size, and Window.

ELEMENT CLASSES

None

COMMANDS HANDLED

Clean Up, Copy, Count, Data Size, Delete, Duplicate, Exists, Get, Move, Open, Put Away, Reveal, Select, Sort, Update

88 Object Class Deﬁnitions

Apple AppleScript Finder Finder Guide

Specifications and Main Features

Frequently Asked Questions

User Manual