User manual ADOBE PHOTOSHOP CS 2.0 - SCRIPTING GUIDE

Scripting Guide ® ® bc Adobe Photoshop cs2 © Copyright 2005 Adobe Systems Incorporated. All rights reserved. Adobe® Creative Suite 2 Photoshop® Scripting Guide for Windows® and Macintosh®. NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Adobe Systems Incorporated. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Illustrator, and Photoshop are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Mac, and Macintosh are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. JavaScript and all Java-related marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group. All other trademarks are the property of their respective owners. All other trademarks are the property of their respective owners. If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Contents 1 Introduction ................................................................................................................................. 1 About this manual.......................................................................................................................................................................... 1 What is scripting? ........................................................................................................................................................................... 2 Why use scripting? ......................................................................................................................................................................... 2 Why use scripts instead of Actions?......................................................................................................................................... 2 System requirements.................................................................................................................................................................... 3 Choosing a scripting language ................................................................................................................................................. 4 New Features ................................................................................................................................................................................... 5 2 Scripting basics ............................................................................................................................ 6 Introducing Objects....................................................................................................................................................................... 6 Writing Script Statements ........................................................................................................................................................... 7 Object Model Concepts ............................................................................................................................................................... 7 Photoshop CS2's Object Model................................................................................................................................................. 8 Object Elements and Collections.............................................................................................................................................. 9 Object References ........................................................................................................................................................................11 Using Commands and Methods .............................................................................................................................................12 Using Variables..............................................................................................................................................................................13 Using Object Properties .............................................................................................................................................................18 Understanding Object Classes and Inheritance................................................................................................................19 Using Arrays ...................................................................................................................................................................................19 Documenting Scripts ..................................................................................................................................................................20 Using Long Script Lines..............................................................................................................................................................21 Creating a Sample Hello World Script...................................................................................................................................21 Using Operators............................................................................................................................................................................25 Using Conditional Statements.................................................................................................................................................26 Using Subroutines, Handlers and Functions ......................................................................................................................29 Executing JavaScripts from AS or VBS ..................................................................................................................................31 Passing AS or VBS Arguments to JavaScript.......................................................................................................................31 Testing and Troubleshooting ..................................................................................................................................................32 Bibliography...................................................................................................................................................................................34 3 Scripting Photoshop CS2 .......................................................................................................... 36 Viewing Photoshop CS2 Objects, Commands and Methods .......................................................................................36 Targeting and Referencing the Application Object.........................................................................................................37 Creating New Objects in a Script ............................................................................................................................................37 Setting the Active Object ..........................................................................................................................................................39 Opening a Document .................................................................................................................................................................42 Saving a Document .....................................................................................................................................................................44 Setting Application Preferences ............................................................................................................................................46 Allowing or Preventing Dialogs ..............................................................................................................................................46 Working with the Photoshop CS2 Object Model..............................................................................................................47 Working with Color Objects .....................................................................................................................................................63 Working with Filters ....................................................................................................................................................................65 Understanding Clipboard Interaction ..................................................................................................................................66 Working with Units ......................................................................................................................................................................68 iii Adobe Illustrator CS2 Visual Basic Scripting Reference Contents iv Sample Workflow Automation JavaScripts.........................................................................................................................71 Advanced Scripting .....................................................................................................................................................................72 Index ........................................................................................................................................... 85 1 Introduction About this manual This manual provides an introduction to scripting Adobe® Photoshop CS2® on Mac OS® and Windows®. Chapter one covers the basic conventions used in this manual and provides an overview of requirements for scripting Photoshop CS2. Chapter two covers the Photoshop CS2 object model as well as generic scripting terminology, concepts and techniques. Code examples are provided in three languages: AppleScript VBScript JavaScript Note: Separate reference manuals are available for each of these languages and accompany this Scripting Guide. The reference manuals are located on the installation CD. Chapter three covers Photoshop CS2-specific objects and components and describes advanced techniques for scripting the Photoshop CS2 application. Note: Please review the README file shipped with Photoshop CS2 for late-breaking news, sample scripts, and information about outstanding issues. Conventions in this guide Code and specific language samples appear in monospaced courier font: app.documents.add Several conventions are used when referring to AppleScript, VBScript and JavaScript. Please note the following shortcut notations: AS stands for AppleScript VBS stands for VBScript JS stands for JavaScript The term "commands" will be used to refer both to commands in AppleScript and methods in VBScript and JavaScript. When referring to specific properties and commands, this manual follows the AppleScript naming convention for that property and the VBScript and JavaScript names appear in parenthesis. For example: "The display dialogs (DisplayDialogs/displayDialogs) property is part of the Application object." In this case, display dialogs refers to the AppleScript property, DisplayDialogs refers to the VBScript property and displayDialogs refers to the JavaScript property. For larger blocks of code, scripting examples are listed on separate lines. 1 Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Introduction 2 AS layer 1 of layer set 1 of current document VBS appRef.ActiveDocument.LayerSets(1).Layers(1) JS app.activeDocument.layerSets[0].layers[0] Finally, tables are sometimes used to organize lists of values specific to each scripting language. What is scripting? A script is a series of commands that tells Photoshop CS2 to perform a set of specified actions, such as applying different filters to selections in an open document. These actions can be simple and affect only a single object, or they can be complex and affect many objects in a Photoshop CS2 document. The actions can call Photoshop CS2 alone or invoke other applications. Scripts automate repetitive tasks and are often used as a creative tool to streamline tasks that might be too time consuming to do manually. For example, you could write a script to generate a number of localized versions of a particular image or to gather information about the various color profiles used by a collection of images. Why use scripting? While graphic design is characterized by creativity, some aspects of the actual work of illustration and image manipulation are anything but creative. Scripting helps creative professionals save time by automating repetitive production tasks such as resizing or reformatting documents. Any repetitive task is a good candidate for a script. Once you can identify the steps and conditions involved in performing the task, you're ready to write a script to take care of it. Why use scripts instead of Actions? If you've used Photoshop CS2 Actions, you're already familiar with the enormous benefits of automating repetitive tasks. Scripting allows you to extend those benefits by allowing you to add functionality that is not available for Photoshop CS2 Actions. For example, you can do the following with scripts and not with actions: You can add conditional logic, so that the script automatically makes "decisions" based on the current situation. For example, you could write a script that decides which color border to add depending on the size of the selected area in an image: "If the selected area is smaller than 2 x 4 inches, add a green border; otherwise add a red border." A single script can perform actions that involve multiple applications. For example, depending on the scripting language you are using, you could target both Photoshop CS2 and another Adobe Creative Suite 2 Application, such as Illustrator® CS2, in the same script. You can open, save, and rename files using scripts. Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Introduction 3 You can copy scripts from one computer to another. If you were using an Action and then switched computers, you'd have to recreate the Action. Scripts provide more versatility for automatically opening files. When opening a file in an action, you must hard code the file location. In a script, you can use variables for file paths. Note: See Photoshop CS2 Help for more information on Photoshop CS2 Actions. System requirements Any system that runs Photoshop CS2 supports scripting. Mac OS You can create AppleScripts or JavaScripts for use with Photoshop CS2 on a Macintosh system. AppleScript Requirements You can create AppleScripts on a Macintosh using the Script Editor application, which is installed as part of your Mac OS in the Applications/AppleScript folder. If Script Editor is not on your system, you can install it from your original system software CD-ROM. You also need AppleScript, which is installed automatically with the OS. If for any reason AppleScript technology has not been installed on your system, you can install it as well from your system software CD-ROM. Note: As your scripts become more complex, you may want to add debugging and productivity features not found in the Script Editor. There are many third-party script editors that can write and debug Apple Scripts. For details, check http://www.apple.com/applescript. For more information on the AppleScript scripting environment, see `Viewing Photoshop CS2's AppleScript Dictionary' on page 36. This manual uses the Script Editor from Apple for creating AppleScripts. For more information on using Script Editor, see `Creating and Running an AppleScript' on page 22. JavaScript Requirements (Mac OS) You can create JavaScripts using any text editor that allows you to save your scripts in a text format with a .jsx extension. The editor applications that are part of a default Apple OS installation, Script Editor and TextEdit, do not allow you to create and save JavaScript files. However, your Mac OS installation CD includes the Developer application Project Builder, which you can use to create JavaScripts. Windows You can create VBScript scripts on a Windows platform using any text editor that allows you to save your scripts in a text format with a .vbs extension. For more information, see `Creating and Running a VBScript' on page 23. Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Introduction 4 JavaScript You can write JavaScripts on either the Mac OS or Windows platform using any text editor. You must save JavaScript files as text files with a .jsx extension. For more information, see `Creating and Running a JavaScript' on page 24. Choosing a scripting language Your choice of scripting language is determined by two trade-offs: 1. Do you need to run the same script on both Macintosh and Windows computers? If yes, you must create a JavaScript. See `Cross-platform scripts' on page 4. 2. Does the task you are scripting involve multiple applications (such as Photoshop CS2 and Illustrator CS2 or a database program)? If yes, you must create an AppleScript if you are using a Macintosh; you must create a VBScript script if you are using Windows. See `Scripts that control multiple applications' on page 5. Tip: You can combine JavaScript's versatility with the platform-specific advantages of using either AppleScript or VBScript by executing JavaScripts from your AppleScripts or VBScript scripts. See `Executing JavaScripts from AS or VBS' on page 31 for more information. Note: You can use other scripting languages, although they are not documented in this manual. On Mac OS, you can use any language that allows you to send Apple events. On Windows, you can use any OLE Automation-aware language. Legacy OLE Automation scripting Photoshop CS2 supports legacy Automation scripting as long as you modify the way that you refer to the Photoshop CS2 Application object in your scripts. For example, instead of saying: Set appRef = CreateObject("Photoshop.Application") you must change the above code to read: Set appRef = CreateObject("Photoshop.Application.9.1") No other change is necessary for legacy COM scripts to run under Photoshop CS2. Cross-platform scripts Because JavaScripts performs identically on both Windows and Macintosh computers, it is considered a cross-platform scripting language. You run a JavaScript from within Photoshop CS2 by storing the script in the ...Presets\Scripts folder of your Photoshop CS2 installation and then selecting the script from the File > Scripts menu. Running JavaScripts from within Photoshop CS2 eliminates the scripts' facility to directly address other applications. For example, you cannot easily write a JavaScript to manage a workflow that involves Photoshop CS2 and a database management program. Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Introduction 5 Scripts that control multiple applications You can write scripts in either AppleScript or VBScript that control multiple applications. For example, on a Macintosh you can write an AppleScript that first manipulates a bitmap in Photoshop and then commands a web design application to incorporate it. You can write a script with similar capability on Windows using VBScript as the scripting language. New Features The scripting interface now allows you to do any of the following: Specify Camera Raw options when opening a document. Optimize documents for the Web. Create and format contact sheets. Specify options for the Batch command. Apply the Lens Blur filter. Automatically run scripts when specified events occur. For example, using a notifier object, you can associate a script with an event such as the Photoshop CS2 application opening, so that the script runs whenever the application opens. 2 Scripting basics This chapter provides a brief introduction to the basic concepts and syntax of the scripting languages AppleScript, VBScript, and JavaScript. If you are new to scripting, you should read this entire chapter. If you are familiar with scripting or programming languages, you most likely will want to skip many sections in this chapter. Use the following list to locate information that is most relevant to you. For more information on Photoshop CS2's object model, see `Photoshop CS2's Object Model' on page 8. For information on selecting a scripting language, see `Choosing a scripting language' on page 4. For examples of scripts created specifically for use with Photoshop CS2, see Chapter 3, `Scripting Photoshop CS2' on page 36. For detailed information on Photoshop CS2 objects and commands/methods, please refer to the following publications, which are located on the installation CD in the same directory as this Guide: Adobe Photoshop CS2 AppleScript Scripting Reference Adobe Photoshop CS2 Visual Basic Scripting Reference Adobe Photoshop CS2 JavaScript Scripting Reference Introducing Objects A script is a series of commands that tell Photoshop CS2 what to do. Basically, the commands manipulate objects. What are objects in the context of a scripting language? When you use Photoshop CS2, you create documents, layers, channels, and design elements, and you can work with a specific area of an image by selecting the area. These things are objects. The Photoshop CS2 application is also an object. Each type of object has its own properties and commands (AppleScript) or methods (VBScript and JavaScript). Properties describe or characterize the object. For example: A layer object has a background color. It can also have a text item. A channel object has color properties such as red, green, and blue. The selected area of an image, or selection object, has size and shape properties. Commands and methods describe actions you want to take on the object. For example, to print a document, you use the Document object's print/PrintOut/print() command/method. Note: For more detailed information on commands and methods, see `Using Commands and Methods' on page 12. When you write a script to manipulate an object, you can use only the properties and commands or methods defined for that object. For example, a Channel object does not, obviously, have a print/PrintOut/print() command/method. How do you know which properties or commands/methods you can use? Adobe provides all the information you need in the following references, which are available on the installation CD: Adobe Photoshop CS2 AppleScript Scripting Reference 6 Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 7 Adobe Photoshop CS2 Visual Basic Scripting Reference Adobe Photoshop CS2 JavaScript Scripting Reference Tip: Throughout this guide, explanations of how to create a script for a task are followed by instructions for looking up in the appropriate scripting reference the specific elements used in the script. Using these instructions will help you quickly understand how to script Photoshop CS2. Writing Script Statements A scripting language, like human languages, uses sentences or statements, for communication. To write a script statement: Name an object. Name the property you want to change or create. Indicate the task you want to perform on the object's property. In AppleScript, you use a command. In VBScript and JavaScript, you use a method. Add a document called myDocument For example, to create a new document called myDocument, you would write a script statement that says In this example, the object is document, its "name" property is myDocument, and the command or method is add. Syntax Because you use scripting languages to communicate with the your computer, you must follow strict rules that the computer can understand. These rules are called the language's syntax. The syntaxes for AppleScript, VBScript, and JavaScript are different. In this guide, you will learn basic scripting concepts that these languages share. You will also learn some of the syntax that is specific to each language. Object Model Concepts In a script statement, you refer to an object based on where the object is located in an object model. An object model is simply an arrangement of objects. The arrangement is called a containment hierarchy. Here's a way to think about object models: 1. You live in a house, which we will think of as your house object. 2. The house has rooms, which we will call its room objects. 3. Each room has window and door objects. Windows can be open or shut. (In other words, a window object has an open property that indicates whether or not the window is open.) If you want to write a script that opens a window in your house, you would use the property or command/method that accomplishes the task. But first, you need to identify the window. This is where the object model comes in: you identify the window by stating where it is in the careful arrangement of objects contained in your house. First of all, the window is contained by the house. But there are lots of windows, so you need to provide more detail, such as the room in the house. Again, there is probably more than one window in each room, so you'd also need to provide the wall that the window is in. Using the house object model, you would identify the window you want to open as "the window on the north wall in the living room in my house". Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 8 To get the script to open that window, you'd simply add the command or method for opening it. Thus your scripting statement would look like this: In my house, in the living room, the window on the north wall: open it. Similarly, you could create a script in your house model to change the color of a door to blue. In this case, you might be able to use the door object's color property instead of a command or method: In my house, in the bedroom, the door to the bathroom: blue. Containment Hierarchy When we refer to an object model as a containment hierarchy, we mean that we identify objects in the model partially by the objects that contain them. You can picture the objects in the house model in a hierarchy, similar to a family tree, with the house on top, rooms at the next level, and the windows and doors branching from the rooms. Applying the Concept to Photoshop CS2 Now apply this object model concept to Photoshop CS2. The Photoshop CS2 application is the house, its documents are the rooms, and the layers, layersets, channels, and selected areas in your documents are the windows, doors, ceilings, and floors. You can tell Photoshop CS2 documents to add and remove objects or set or change individual object properties like color, size and shape. You can also use commands or methods, such as opening, closing, or saving a file. Photoshop CS2's Object Model To create efficient scripts, you need to understand the containment hierarchy of the Photoshop CS2 object model. . Application Object Model Classes Document Selection Path Item Channel Art Layer Layer Set Document Info Notifier History State Path Point Histogram Array Text Item (Object) Art Layer Layer Set Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 9 The following table provides information about each object. Object Name Application Document Description The Photoshop CS2 application The working object, in which you create layers, channels, actions, and so on. In a script, you name, open, or save a document as you would a file in the application. The selected area of a layer or document. A drawing object, such as the outline of a shape or a straight or curved line Pixel information about an image's color A layer class within a document that allows you to work on one element of an image without affecting other elements in the image. A collection of Art Layer objects. Metadata about a Document object. Note: Metadata is any data that helps to describe the content or characteristics of a file, such filename, creation date and time, author name, the name of the image stored in the file, etc. Notifier Notifies a script when an event occurs; the event then triggers the script to execute. For example, when a user clicks an OK button, the notifier object tells the script what to do next. Stores a version of the document in the state the document was in each time you saved it. Note: You can use a History State object to fill a Selection object or to reset the document to a previous state. Choose File > Scripts > Script Events Manager. To create this object without using a script: Start the Photoshop CS2 application. In Photoshop CS2, choose File > New or File > Open. Selection Path Item Choose the marquee or lasso tools and drag your mouse. Choose the path selection or pen tools and draw a path with the mouse. Choose Window > Channels. Choose Layer > New > Layer or Window > Layers. Choose Layer > New > Layer Set. Choose File > File Info. Channel Art Layer Layer Set Document Info History State Choose Window > History, and then choose a history state from the History palette. Object Elements and Collections When you add an object to your script, the object is included automatically in an object element (AppleScript) or collection (VBScript, JavaScript). The objects in a single element or collection are identical types of objects. For example, each Channel object in your script belongs to a Channels element or collection; each Art Layer object belongs to an Art Layers element or collection. Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 10 Note: Your scripts place objects in elements or collections even when there is only one object of that type in the entire script, that is, only one object in the element or collection. When you add an object, the object is numbered automatically within its respective element or collection. You can identify the object in other script statements by using its element or collection name and assigned number. Using the house example, when you add a room to your house, your script stores a number that identifies the room. If it's the first room you've added, your AppleScript considers the room to be room1; your VBScript script or JavaScript considers the room to be room0. Here's how the scripting languages handle the automatic numbering if you add a second room: AppleScript considers the new room room1 and renumbers the previously added room so that it becomes room2. AppleScript object numbers shift among objects to indicate the object that you worked with most recently. See the AppleScript section in `Referring to an Object in an Element or Collection' on page 10 for further details on this topic. VBScript or JavaScript numbers are static; they don't shift when you add a new object to the collection. Object numbering in VBScript and JavaScript indicates the order in which the objects were added to the script. Because the first room you added was considered room0, the next room you add is considered room1; if you add a third room, it is labeled room2. When you add an object that is not a room, the numbering starts all over for the new object element or collection. For example, if you add a door, your AppleScript considers the door to be door1; your VBScript script or JavaScript considers the door door0. Note: You can also name objects when you add them. For example, you can name the rooms livingRoom and bedRoom. If an object has a name, you can refer to the object in your script either by name or by the element/collection name followed by the assigned number. Generally, beginning scripters are encouraged to use object names in AppleScript. In VBScript or JavaScript, you'll find object numbers very useful. For example, you may have several files in which you want to make the background layer white. You can write a script that says "Open all files in this folder and change the first layer's color to white." If you didn't have the capability of referring to the layers by number, you'd need to include in your script the names of all of the background layers in all of the files. Chances are, if you created the files using the Photoshop CS2 application rather than a script, the layers don't even have names. Indexes or Indices An object's number in an element or collection is called an index. Referring to an Object in an Element or Collection A collection or element name is the plural version of the object type name. For example, an element or collection of Document objects is called documents. In JavaScript and VBScript, you can use the collection name and the index to refer to an object. The syntax is slightly different in AppleScript. The following code samples demonstrate the correct syntax for using an object's index when referring to the object. Tip: Remember that VBScript and JavaScript indices begin with 0. Beginning your count with 0 may seem confusing, but as you learn about scripting, you'll find that using 0 gives you added capabilities for getting your scripts to do what you want. Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 11 AS In AppleScript, you use the object type name followed by a space and then the index. The following statement refers to the current document. Notice that the element name is implied rather than used explicitly. document 1 Note: If the element name were used, this statement would be document 1 of documents. AppleScript abbreviates the syntax by inferring the element name from the object type name. In AppleScript, the number that refers to an object in an element changes when the script manipulates other objects. Unless you update the older art layer's status to "active layer", references made to art layer 1 of current document refer to the new layer. Note: See `Setting the Active Object' on page 39 for more information about selecting the active layer. Tip: For beginning scripters, it's a good idea to name all objects in your AppleScripts and then refer to the objects by name. VBS In VBScript, you use the collection name followed by the index enclosed in parentheses. There is no space between the collection name and the parentheses. Documents(1) JS In JavaScript, the collection name is followed by the index in square brackets with no space between the object name and the brackets. documents[0] Object References Because scripts use a containment hierarchy, you can think of an object reference as being similar to the path to a file. You can use an object's name or index to refer to the object. (See `Indexes or Indices' on page 10.) The following code samples demonstrate the syntax for referring to an artLayer object named Profile, which was the first layer added to the layerSet object named Silhouettes, which in turn was the first layer added to the current document: AS Object index reference: layer 1 of layer set 1 of current document Object name reference: layer "Profile" of layer set "Silhouettes" of current document Note: When you refer to an object by name, you must enclose the name in double quotes (""). You can also combine the two types of syntax: layer 1 of layer set "Silhouettes" of current document Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 12 VBS Object index reference: appRef.ActiveDocument.LayerSets(0).Layers(0) Object name reference: appRef.ActiveDocument.LayerSet("Silhouettes").Layer("Profile") You can also combine the two types of syntax: appRef.ActiveDocument.LayerSets(1).Layer("Profile") Tip: Notice that when you refer to an object by its assigned name you use the object classname, which is singular (LayerSet or Layer). When you use a numeric index to refer to an object, you use the collection name, which is plural (LayerSets or Layers). JS Object index reference: app.documents[1].layerSets[0].layers[0] Object name reference: appRef.document("MyDocument").layerSet("Silhouettes").layer("Profile") You can also combine the two types of syntax: appRef.activeDocument.layerSet("Silhouettes").layers[0] Note: When you refer to an object by its assigned name you use the object classname, which is singular (document or layerSet or layer). When you use a numeric index to refer to an object, you use the collection name, which is plural (documents or layerSets or layers). Using Commands and Methods Commands (in AppleScript) and methods (in VBScript and JavaScript) are directions you add to a script to perform tasks or obtain results. For example, you could use the open/Open/open() command/method to open a specified file. Note: You can use only the methods or commands associated with that object type. For example, you can use the open/Open/open() command/method on a Document object but not on a Selection object which, obviously, cannot be opened. Before using a command on an AppleScript object, look up either the object type or the command in the Adobe Photoshop CS2 AppleScript Scripting Reference to be sure the association is valid. For example, you could look up open in the "Commands" chapter of the scripting reference; or you could look up the Document object in the "Objects" chapter. Before using a method on a VBScript or JavaScript object, look up the method in the Methods table for the object type in the Adobe Photoshop CS2 Visual Basic Scripting Reference or the Adobe Photoshop CS2 JavaScript Scripting Reference. For example, you could look up the Document object in the "Interface" chapter, and then find the object's Methods table. Commands and Command Properties Commands (AppleScript) use normal English sentence syntax. The script statement begins with an imperative verb form followed by a reference to the object upon which you want the script to perform the task. The following AppleScript command prints the first layer of the current document: print layer 1 of current document Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 13 Some commands require additional data. In AppleScript, the make new command adds a new object. You can specify properties for the object by enclosing the properties in brackets and preceding the brackets with the phrase with properties. The following statement creates a new document that is four inches wide and two inches high. make new document with properties {width:4 as inches, height:2 as inches} Note: See `Setting the Active Object' on page 39 for information on making sure your script performs the task on the correct object. Methods and Arguments You insert methods at the end of a VBScript or JavaScript statement. You must place a period before the method name to separate it from the rest of the statement. The following VBScript statement prints the current document: appRef.Documents(1).PrintOut A method in JavaScript must be followed by parentheses, as in the following statement: app.documents[0].print() Some methods require additional data, called arguments, within the parentheses. Other methods have optional arguments. The following statements use the Add/add() method to add a bitmap document named myDocument that is 4000 pixels wide and 5000 pixels tall and has a resolution of 72 pixels per inch: Note: Even though the Document object in the following script statements is given a name (myDocument), you use the object collection name when you add the object. See `Referring to an Object in an Element or Collection' on page 10 for more information on object collections. See `Object References' on page 11 for information on object collection names versus object names in a singular form. VBS appRef.Documents.Add(4000, 5000, 72, "myDocument", 5) Note: The enumerated value 5 at the end of the script statement indicates the value psNewBitmap for the constant PsNewDocumentMode. The Adobe Photoshop CS2 Visual Basic Scripting Reference contains detailed information about enumerated values and constants. JS app.documents.add(4000, 5000, 72, "myDocument", DocumentMode.BITMAP) Using Variables A variable is a container for data you use in your script. For example, in the following AppleScript statements the variables docWidth and docHeight replace the width and height specifications for the new document. Without variables: make new document with properties {width:4 as inches, height:2 as inches} With variables: set docWidth to 4 inches set docHeight to 2 inches make new document with properties {docWidth, docHeight} Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 14 Why Use Variables? There are several reasons for using variables rather than entering values directly in the script. Variables make your script easier to update or change. For example, if your script creates several 4 x 2 inch documents and later you want to change the documents' size to 4 x 3 inches, you could simply change the value of the variable docHeight from 2 to 3 at the beginning of your script and the entire script would be updated automatically. If you had used the direct value 2 inches to enter the height for each new document, updating the document sizes would be much more tedious. You would need find and change each statement throughout the script that creates a document. Variables make your scripts reusable in a wider variety of situations. As a script executes, it can assign data to the variables that reflect the state of the current document and selection, and then make decisions based on the content of the variables. Data Contained in Variables The data that a variable contains is the variable's value. To assign a value to a variable, you use an assignment statement. A variable's value can be a number, a string (a word or phrase or other list of characters enclosed in quotes), an object reference, a mathematical expression, another variable, or a list (including collections, elements, and arrays). See `Using Operators' on page 25 for information on using mathematical expressions or other variables as values. See `Using Object Properties' on page 18 for information about arrays. Assignment statements require specific syntax in each scripting language. See `Creating Variables and Assigning Values' on page 14 for details. Creating Variables and Assigning Values This section demonstrates how to create two variables named thisNumber and thisString, and then assign the following values: Variable thisNumber thisString Value 10 "Hello World" Note: When you assign a string value to a variable, you must enclose the value in straight, double quotes (""). The quotes tell the script to use the value as it appears without interpreting or processing it. For example, 2 is a number value; "2" is a string value. The script can add, subtract, or perform other operations with a number value. It can only display a string value. AS In AppleScript, you must both create and assign a value to a variable in a single statement. You can create a variable using either the set command or the copy command. With the set command, you list the variable name (called an identifier in AppleScript) first and the value second, as in the following example: set thisNumber to 10 set thisString to "Hello, World" With the copy command, you list the value first and the identifier second. copy 10 to thisNumber copy "Hello World" to thisString Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 15 Using the Variable in a Script After declaring and assigning values to your variables, you use the variables in your script to represent the value; you use only the variable name without the set or copy command. The following statement uses the display dialog command to create a dialog box with the text Hello World. display dialog thisString Assigning an Object Reference as a Value You can also use variables to store references to objects. (See `Object References' on page 11 for an explanation of object references.) The following statement creates a variable named thisLayer and as its value, creates a new Art Layer object. When you use thisLayer in a script statement, you are referring to the new layer. set thisLayer to make new art layer in current document You can also assign a reference to an existing object as the value: set thisLayer to art layer 1 of current document AppleScript Value Types You can use the following types of values for variables in your AppleScripts. Note: For now, don't worry about the value types you don't understand. Value Type boolean integer What It Is Logical true or false. Whole numbers (no decimal points). Integers can be positive or negative. A number that may contain a decimal point. A series of text characters. Note: Strings appear inside (straight) quotation marks. Sample Value true 14 real string 13.9972 "I am a string" list object record An ordered list of values. The values of a list may be any type. {10.0, 20.0, 30.0, 40.0} A specific reference to an object. current document An unordered list of properties, Each property is identified by its label. {name: "you", index: 1} VBS To create a variable in VBScript, you use the Dim keyword at the beginning of the statement. The following statements create the variables thisNumber and thisString. Dim thisNumber Dim thisString You can declare multiple variables in a single Dim statement by separating the variables with a comma (,), as follows: Dim thisNumber, thisString Photoshop CS2 Adobe Photoshop CS2 Scripting Guide Scripting basics 16 To assign a value to a variable, you use the equals sign (=), as follows: thisNumber = 10 thisString = "Hello, World" Note: Remember to enclose string values in straight, double quotes (""). Another rule of thumb for proper scripting in VBScript is to declare all of your variables somewhere near the beginning of the script. That way you can easily see which variables are in use without having to search throughout the script for them. The VBScript tool Option Explicit forces you to declare all variables before you use them in a script statement. It also helps you avoid situations in which you try to use a misspelled variable name or an undeclared variable. You use Option Explicit before you declare any variables, as in the following code sample: Option Explicit Dim thisNumber Dim thisString thisNumber = 10 thisString = "Hello, World" Assigning an Object Reference as a Value You assign an object reference as the value of a variable, use the Set command as well as the equal sign. The following example uses Set and the Add method to create the variable thisLayer, create a new Art Layer object, and then assign the new Art Layer object as the value of thisLayer: Dim thisLayer Set thisLayer = AppRef.Documents(0).ArtLayers.Add The next example uses Set to assign an existing Art Layer object (in this case, the third Art Layer object added to the script) as the value of thisLayer: Dim thisLayer Set thisLayer =AppRef.Documents(0).ArtLayers(2) Using the Variable in a Script Statement When you use variables in your script to represent values, you use only the variable name without the Dim or Set keyword. The following example rotates the selected section of the Art Layer object represented by the variable thisLayer by 45 degrees: thisLayer.Selection.Rotate(45) VBScript Value Types You can use the following types of values for variables in VBScript. Note: For now, don't worry about the value types you don't understand. Value Type Boolean Empty Error Null What It Is Logical true or false The variable holds no data Stores an error number The variable holds no valid value (Usually used to test an error condition) Any number not inside double quotes Example true false myVar = Empty null Number 3.7 2000