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];