Adobe 23101335 - Photoshop - PC User manual

ADOBE SYSTEMS INCORPORATED
Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
[phone]
http://partners.adobe.com
bbc
March 2002
Photoshop 7.0
Scripting Guide

Adobe Photoshop Scripting Guide
Copyright 1991–2002 Adobe Systems Incorporated.
All rights reserved.
The information in this document 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 this document. 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.
Adobe, Photoshop, and PostScript are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States
and/or other countries. Apple, Macintosh, and Mac 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/or
other countries. All other trademarks are the property of their respective owners.

Photoshop 7.0 Scripting Guide iii
Table of contents
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Aboutthismanual.......................................5
1.2 Whatisscripting?.......................................6
1.3 Whyusescripting?.......................................6
1.4 Whataboutactions?......................................6
1.5 Systemrequirements .....................................6
1.6 JavaScript...........................................7
1.7 Choosingascriptinglanguage.................................7
1.8 LegacyCOMscripting.....................................8
Chapter2 Scriptingbasics.......................9
2.1 Documentsasobjects.....................................9
2.2 Objectmodelconcepts.....................................9
2.3 Documentingscripts.....................................11
2.4 Values............................................12
2.5 Variables...........................................14
2.6 Operators ..........................................16
2.7 Commandsandmethods..................................17
2.8 Handlers,subroutinesandfunctions.............................20
2.9 TheScriptsmenu ......................................21
2.10 Testingandtroubleshooting.................................23
Chapter3 ScriptingPhotoshop ....................33
3.1 Photoshopscriptingguidelines................................33
3.2 ViewingPhotoshopobjects,commandsandmethods....................34
3.3 YourfirstPhotoshopscript..................................36
3.4 Objectreferences......................................42
3.5 Workingwithunits......................................44
3.6 ExecutingJavaScriptsfromASorVB............................48
3.7 TheApplicationobject....................................50

Photoshop 7.0 Scripting Guide iv
Table of contents
3.8 Documentobject.......................................54
3.9 Layerobjects.........................................58
3.10 Textitemobject .......................................64
3.11 Selections..........................................67
3.12 WorkingwithFilters.....................................74
3.13 Channel object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
3.14 Colorobjects.........................................77
3.15 Historyobject.........................................80
3.16 Clipboardinteraction.....................................81
3.17 ActionManagerscripting...................................84

Photoshop 7.0 Scripting Guide 5
1Introduction
1.1 About this manual
This manual provides an introduction to scripting Adobe Photoshop 7.0 on Mac OS and
Windows®. Chapter one covers the basic conventions used in this manual and provides an
overview of requirements for scripting Photoshop.
Chapter two covers basic scripting terms, concepts and techniques. Experienced AppleScript
writers and Visual Basic programmers may want to skip to Chapter three for specifics on
scripting Photoshop.
1.1.1 Conventions in this guide
Code and specific language samples appear in monospaced courier font:
documents.add();
IMPORTANT: Most code examples in this manual are brief snippets that will not work as
fully functional scripts.
Several conventions will be used when referring to AppleScript, Visual Basic and JavaScript.
Please note the following shortcut notations:
●AS stands for AppleScript
●VB stands for Visual Basic
●JS stands for JavaScript
The term “commands” will be used to refer both to commands in AppleScript and methods in
Visual Basic and JavaScript.
When referring to specific properties and commands, the manual will follow the AppleScript
naming convention for that property and the Visual Basic and JavaScript names will 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 Visual Basic property and displayDialogs refers to the JavaScript property.

Photoshop 7.0 Scripting Guide 6
Introduction
What is scripting? 1
1.2 What is scripting?
A script is a series of commands that tells Photoshop to perform a set of specified actions.
These actions can be simple, and affect only a single object in the current document, or
complex and affect many objects in a Photoshop document. The actions can call Photoshop
alone or also invoke other applications.
Scripts can automate repetitive tasks and be 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.
1.3 Why use scripting?
Graphic design is a field characterized by creativity, but aspects of the actual work of
illustration and image manipulation are anything but creative. Scripting provides a tool to help
save time spent on repetitive production tasks such as resizing or reformatting documents.
Start with short, simple scripts to save a few seconds a day, and move on to more involved
scripts. 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.
1.4 What about actions?
Photoshop actions are different from scripts. A Photoshop action is a series of tasks you have
recorded while using the application—menu choices, tool choices, selection, and other
commands. When you “play” an action, Photoshop performs all of the recorded commands.
Actions and scripts are both ways of automating repetitive tasks, but they work very
differently.
●You cannot add conditional logic to an action. Unlike a script, actions cannot make
decisions based on the current situation.
●A single script can target multiple hosts. Actions can’t. For example, you could target both
Photoshop and Illustrator in the same script.
1.5 System requirements
The language you use to write scripts depends on your operating system: AppleScript for Mac;
Visual Basic for Windows; or JavaScript, a cross-platform scripting language that can run on
either Windows or Mac. While the scripting systems differ, the ways that they work with
Photoshop are very similar.

Photoshop 7.0 Scripting Guide 7
Introduction
JavaScript 1
1.5.1 Mac
Any system that runs Photoshop 7.0 will support scripting. You will also need AppleScript and
a script editor installed. AppleScript and the Script Editor application from Apple are included
with the Mac OS. For Mac OS 9.X the default location for the Script Editor application is the
Apple Extras folder. For Mac OSX, they can be found in the Applications folder. If these items
are not installed on your system, reinstall them from your original system software CD-ROM.
As your scripts become more complex, you may find the need for debugging and productivity
features not found in the Script Editor. There are many third-party script editors that can write
and debug Apple Scripts. Please check http://www.apple.com/applescript for more details.
We use the Script Editor from Apple in this manual.
1.5.2 Windows
Any Windows system that runs Photoshop 7.0 will support scripting. You will also need either
the Windows Scripting Host, Microsoft Visual Basic, or one of the applications that contains a
Visual Basic editor. Most Windows systems include the Windows Scripting Host. If you do not
have Windows Scripting Host or would like more information about Windows Scripting Host,
visit the Microsoft Windows Script Technologies Web site at
(http://msdn.microsoft.com/scripting/).
We use Microsoft Visual Basic in this manual.
1.6 JavaScript
In addition to writing AppleScripts and Visual Basic scripts, you can also write cross-platform
JavaScripts using any text editor. The easiest way to run your JavaScripts is to use the
“Scripts” menu which is installed with Photoshop Scripting Support.
See section 2.9, “The Scripts menu” on page 21 for more information.
1.7 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?
2. Do you need to control multiple applications from the same script?
JavaScript is a cross-platform language that can work with Scripting Support for Photoshop
7.0 on both platforms. The same script will perform identically on Windows and Macintosh
computers. However, JavaScript is invoked from a menu selection within Photoshop and lacks

Photoshop 7.0 Scripting Guide 8
Introduction
Legacy COM scripting 1
the facilities to directly address other applications. For example, you cannot easily write a
JavaScript to manage workflows involving Photoshop and a database management program.
AppleScript and Visual Basic are only offered on their respective platforms. However, you can
write scripts in those languages to control multiple applications. For example, you can write an
AppleScript that first manipulates a bitmap in Photoshop and then commands a web design
application to incorporate it. This same cross-application capability is also available with
Visual Basic on Windows.
You may also use other scripting languages when working with Photoshop Scripting Support.
On Mac OS, any language which lets you send Apple events, such as MacPerl, TCL, or
Latenight Software's JavaScript component, can be used to script Photoshop.
On Windows, any language which is COM aware can be used to script Photoshop. This
includes languages available in Windows Scripting Host, such as VBScript and JScript, as
well as other scripting languages like Perl, Tcl/Tk, and Python.
1.8 Legacy COM scripting
Photoshop 5, Photoshop 6 and Photoshop 7 support COM scripting without the optional
Scripting Support plug-in. This scripting interface is described in the Photoshop SDK
documentation in the “OLE Automation Programming Guide.”
You can use both the old stype COM scripts and the new style COM scripts with Photoshop
7.0, but you have to modify the way that you refer to the Photoshop application object in your
old scripts after you install ScriptingSupport.
Typically you would create a Photoshop application instance by saying:
Set App = CreateObject("Photoshop.Application")
after installing ScriptingSupport, you must change the above code to
Set App = CreateObject("Photoshop.Application.7")
Note that the latter version will work both with and without ScriptingSupport installed.

Photoshop 7.0 Scripting Guide 9
2Scripting basics
2.1 Documents as objects
If you use Photoshop, then you create documents, layers, channels and design elements and
can think of a Photoshop document as a series of layers and channels — or objects.
Automating Photoshop with scripting uses the same object-oriented way of thinking.
The heart of a scriptable application is the object model. In Photoshop, the object model is
comprised of documents, layers and channels. Each object has its own special properties, and
every object in a Photoshop document has its own identity.
This chapter covers the basic concepts of scripting within this object-oriented environment.
2.2 Object model concepts
The terminology of object oriented programming can be hard to understand, at first. “Objects”
belong to “classes” and have “properties” you manipulate using “commands” (AppleScript) or
“methods” (Visual Basic and JavaScript). What do these words mean in this context?
Here’s a way to think about objects and their properties as an object model. Imagine that you
live in a house that responds to your commands. The house is an object, and its properties
might include the number of rooms, the color of the exterior paint or the date of its
construction.
Your house can also contain other objects within. Each room, for example, is an object in the
house, while each window, door, or appliance is an object inside of the room. And each object
can respond to various commands according to its capabilities.
Now apply this object model concept to Photoshop. The Photoshop application is the house,
its documents are the rooms, and the objects in your documents are the windows and doors.
You can tell Photoshop documents to add and remove objects or manipulate individual objects.
2.2.1 Object classes
Objects with the same properties and behaviors are grouped into “classes.” In the house
example, windows and doors belong to their own classes because they have unique properties.
In Photoshop, every type of object— document, art layer, etc.—belongs to its own class, each
with its own set of properties and behaviors.

Photoshop 7.0 Scripting Guide 10
Scripting basics
Object model concepts 2
2.2.2 Object inheritance
Object classes may also “inherit,” or share, the properties of a parent, or superclass. When a
class inherits properties, we call that class a child, or subclass of the class from which it
inherits properties. So in our house example, windows and doors are subclasses of an openings
class, since they are both openings in a house. In Photoshop, art layers, for example, inherit
from the layer class.
Classes will often have properties that aren’t shared with their superclass. In our house, both a
window and door inherit an opened property from the opening class, but a window has a
number of panes property which the Opening class doesn’t. In Photoshop, art layers, for
example, have the property grouped which isn’t inherited from the Layer class.
2.2.3 Object elements or collections
Object elements (AppleScript) or collections (Visual Basic, JavaScript) are objects contained
within other objects. For example, rooms are elements (or collections) of our house, contained
within the house object. In Photoshop, documents are elements of the application object, and
layers are elements of a document object. To access an element (or member of a collection),
you use an index. For example, to get the first document of the application you write:
AS: document 1
VB: appRef.Documents (1)
JS: documents[0];
IMPORTANT: Indices in AppleScript and Visual Basic are 1 based. JavaScript indicies are 0
based.
2.2.4 Object reference
The objects in your documents are arranged in a hierarchy like the house object — layers are
in layer sets, which are inside a document which is inside Photoshop. When you send a
command to a Photoshop object, you need to make sure you send the message to the right
object. To do this, you identify objects by their position in the hierarchy — by an object
reference. You might, for example, write the following statement.
AppleScript
layer 1 of layer set 1 of current document
Visual Basic
appRef.ActiveDocument.LayerSets(1).Layers(1)
JavaScript
activeDocument.layerSets[0].layers[0];

Photoshop 7.0 Scripting Guide 11
Scripting basics
Documenting scripts 2
When you identify an object in this fashion, you’re creating an object reference.While
AppleScript, Visual Basic and JavaScript use different syntax for object references, each gives
the script a way of finding the object you want.
2.3 Documenting scripts
Use comments within your scripts to explain what procedures are taking place. It’s a quick
way to document your work for others and an important element to remember when writing
scripts. Comments are ignored by the scripting system as the script executes and cause no run-
time speed penalty.
AppleScript
To enter a single-line comment in an AppleScript, type “--” to the left of your description. For
multiple line comments, start your comment with the characters “(*” and end it with “*)”.
-- this is a single-line comment
(* this is a
multiple line comment *)
Visual Basic
In Visual Basic, enter “Rem” (for “remark”) or “ ' ” (a single straight quote) to the left of the
comment.
Rem this is a comment
' and so is this
JavaScript
In JavaScript, use the double forward slash to comment a single line or a /* */ notation for
multi-line comments
// This comments until the end of the line
/* This comments
this entire
block of text */
About long script lines
In some cases, individual script lines are too long to print on a single line in this guide.
AppleScript
AppleScript uses the special character (¬) to show that the line continues to the next line. This
continuation character denotes a “soft return” in the script. You can enter this character in the
script editor by pressing Option-Return at the end of the line you wish to continue.

Photoshop 7.0 Scripting Guide 12
Scripting basics
Values 2
Visual Basic
In Visual Basic, you can break a long statement into multiple lines in the Code window by
using the line continuation character, which is a space followed by an underscore ( _).
2.4 Values
Values are the data your scripts use to do their work. Most of the time, the values used in your
scripts will be numbers or text.
TABLE 2.1 AppleScript Values
Value type: What it is: Example:
boolean Logical true or false. true
integer Whole numbers (no decimal
points). Integers can be
positive or negative.
14
real A number which may
contain a decimal point. 13.9972
string A series of text characters.
Strings appear inside
(straight) quotation marks.
"I am a string"
list An ordered list of values.
The values of a list may be
any type.
{10.0, 20.0, 30.0, 40.0}
object reference A specific reference to an
object. current document
record An unordered list of
properties, Each property is
identified by its label.
{name: "you", index: 1}

Photoshop 7.0 Scripting Guide 13
Scripting basics
Values 2
TABLE 2.2 Visual Basic Values
Value type: What it is: Example:
Boolean Logical true or false True
Long Whole numbers (no decimal
points). Longs can be
positive or negative.
14
Double A number which may
contain a decimal point. 13.9972
String A series of text characters.
Strings appear inside
(straight) quotation marks.
"I am a string"
Array A list of values. Arrays
contain a single value type
unless the type is defined as
Variant.
Array(10.0, 20.0, 30.0, 40.0)
Object reference A specific reference to an
object. appRef.ActiveDocument
TABLE 2.3 JavaScript Values
Value type: What it is: Example:
String A series of text characters.
Strings appear inside
(straight) quotation marks.
"Hello"
Number Any number not inside
double quotes. 3.7
Boolean Logical true or false. true
Null Something that points to
nothing. null
Object Properties and methods
belonging to an object or
array.
activeDocument
Undefined Devoid of any value undefined

Photoshop 7.0 Scripting Guide 14
Scripting basics
Variables 2
2.5 Variables
Variables are containers for data. A variable might contain a number, a string, a list (or array),
or an object reference. Variables have names, and you refer to a variable by its name. To put
data into a variable, assign the data to the variable. The file name of the current Photoshop
document or the current date are both examples of data that can be assigned to a variable.
By using variables the scripts you write will be 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, for example, and then make decisions based on the content of the variables.
NOTE:In AppleScript, it is not important to declare your variables before assigning values
to them. In Visual Basic and JavaScript, however, it is considered good form to
declare all of your variables before using them. To declare variables in Visual Basic,
use the Dim keyword. To declare variables in JavaScript, use the var keyword.
2.5.1 Assigning values to variables
The remainder of this section shows how to assign values to variables.
AS
set thisNumber to 10
set thisString to "Hello, World!"
VB
Option Explicit
Dim thisNumber As Long
Dim thisString As String
thisNumber = 10
thisString = "Hello, World!"
The Dim statement assigns a value type to the variable, which helps keep scripts clear and
readable. Memory is also used more efficiently if variables are declared before use. If you start
your scripts in Visual Basic with the line Option Explicit, you will have to declare all
variables before assigning data to them. You will not have to declare them the next time they
are used.
JS
varx=8;
x=x+4;
var thisNumber = 10;
var thisString = "Hello, World!";
The var keyword identifies variables the first time that you use the variable. The next time
you use the variable you should not use the var keyword.

Photoshop 7.0 Scripting Guide 15
Scripting basics
Variables 2
2.5.2 Using variables to store references
Variables can also be used to store references to objects. In AppleScript, a reference is returned
when you create a new object in an Photoshop document as shown below:
set thisLayer to make new art layer in current document
Or you can fill the variable with a reference to an existing object:
set thisLayer to art layer 1 of current document
Visual Basic works similarly, however, there is an important distinction to note. If you are
assigning an object reference to a variable you must use the Set command. For example, to
assign a variable as you create a layer, use Set:
Set thisLayer = appRef.Photoshop.ActiveDocument.ArtLayers(1)
or in reference to an existing layer, since it is also an object reference, use Set:
Set thisLayer = appRef.Photoshop.ActiveDocument.ArtLayers(1)
If you are trying to assign a value to a variable in Visual Basic that is not an object reference,
do not use Set. Use Visual Basic’s assignment operator, the equals sign:
thisNumber = 12
JavaScript looks similar to Visual Basic. To assign a reference to an object, you would write:
var docRef = activeDocument;
andtoassignavalueusethefollowing:
var thisNumber = 12
2.5.3 Naming variables
It’s a good idea to use descriptive names for your variables—something like firstPage or
corporateLogo,ratherthanxor c. You can also give your variable names a standard prefix
so that they’ll stand out from the objects, commands, and keywords of your scripting system.
Variable names must be a single word, but you can use internal capitalization (such as
myFirstPage) or underscore characters (my_first_page) to create more readable names.
Variable names cannot begin with a number, and they can’t contain punctuation or quotation
marks.

Photoshop 7.0 Scripting Guide 16
Scripting basics
Operators 2
2.6 Operators
Operators perform calculations (addition, subtraction, multiplication, and division) on
variables or values and return a result. For example:
docWidth/2
would return a value equal to half of the content of the variable docWidth.SoifdocWidth
contained the number 20.5, the value returned would be 10.25.
You can also use operators to perform comparisons (equal to, not equal to, greater than, or less
than, etc.). Some operators differ between AppleScript, Visual Basic and JavaScript. Consult
your scripting language for operators that may be unique to your OS.
AppleScript and Visual Basic use the ampersand (&) as the concatenation operator to join two
strings.
"Pride " & "and Prejudice."
would return the string “Pride and Prejudice.”
JavaScript uses the “+” operator to concatenate strings.
"Pride" + " and Prejudice"
would return the string “Pride and Prejudice.”

Photoshop 7.0 Scripting Guide 17
Scripting basics
Commands and methods 2
2.7 Commands and methods
Commands (AppleScript) or methods (Visual Basic and JavaScript) are what makes things
happen in a script. The type of the object you’re working with determines how you
manipulate it.
AS
In AppleScript, use the make command to create new objects, the set command to assign
object references to variables and to change object properties, and the get command to
retrieve objects and their properties.
VB
In Visual Basic, use the Add method to create new objects, the Set statement to assign object
references to Visual Basic variables or properties and the assignment operator (=)toretrieve
and change object properties.
JS
In JavaScript, use the add() method to create new objects, and the assignment operator (=)
to assign both object references and variables
2.7.1 Conditional statements
Conditional statements make decisions — they give your scripts a way to evaluate something
like the blend mode of a layer or the name or date of a history state — and then act according
to the result. Most conditional statements start with the word if in all three scripting systems.
The following examples check the number of currently open documents. If no documents are
open, the scripts display a messages in a dialog box.
AS
tell application "Adobe Photoshop 7.0"
set documentCount to count every document
if documentCount = 0 then
display dialog "No Photoshop documents are open!"
end if
end tell

Photoshop 7.0 Scripting Guide 18
Scripting basics
Commands and methods 2
VB
Private Sub Command1_Click()
Dim documentCount As long
Dim appRef As New Photoshop.Application
documentCount = appRef.Documents.Count
If documentCount = 0 Then
MsgBox "No Photoshop documents are open!"
End If
End Sub
JS
var documentCount = documents.length;
if (documentCount == 0)
{alert("There are no Photoshop documents open");
}
2.7.2 Control structures
Control structures provide for repetitive processes, or “loops.” The idea of a loop is to repeat
some action, with or without changes each time through the loop, until a condition is met.
Both AppleScript and Visual Basic have a variety of different control structures to choose
from. The simplest form of a loop is one that repeats a series of script operations a set number
of times.
AS
repeat with counter from 1 to 3
display dialog counter
end repeat
VB
For counter = 1 to 3
MsgBox counter
Next
JS
for (i = 1; i < 4; ++i)
{alert(i);
}

Photoshop 7.0 Scripting Guide 19
Scripting basics
Commands and methods 2
A more complicated type of control structure includes conditional logic, so that it loops while
or until some condition is true or false.
AS
set flag to false
repeat until flag = true
set flag to button returned of (display dialog "Quit?" ¬
buttons {"Yes", "No"}) = "Yes"
end repeat
set flag to false
repeat while flag = false
set flag to button returned of (display dialog "Later?" ¬
buttons {"Yes", "No"}) = "No"
end repeat
VB
flag = False
Do While flag = False
retVal = MsgBox("Quit?", vbOKCancel)
If (retVal = vbCancel) Then
flag = True
End If
Loop
flag = False
Do Until flag = True
retVal = MsgBox("Quit?", vbOKCancel)
If (retVal = vbOK) Then
flag = True
End If
Loop

Photoshop 7.0 Scripting Guide 20
Scripting basics
Handlers, subroutines and functions 2
JS
var flag = false;
while (flag == false)
{flag = confirm("Are you sure?");
}
var flag = false;
do
{flag = confirm("Are you sure?");
}
while (flag == false);
2.8 Handlers, subroutines and functions
Subroutines, or handlers (in AppleScript) and functions (in JavaScript), are scripting modules
you can refer to from within your script. These subroutines provide a way to re-use parts of
scripts. Typically, you send one or more values to a subroutine and it returns one or more
values.
There’s nothing special about the code used in subroutines — they are conveniences that save
you from having to retype the same code lines in your script.
AS
set flag to DoConfirm("Are you sure?")
display dialog flag as string
on DoConfirm(prompt)
set button to button returned of (display dialog prompt ¬
buttons {"Yes", "No"} default button 1)
return button = "Yes"
end DoConfirm