Adobe 23101764 - Photoshop CS - PC User manual

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

Adobe Photoshop Scripting Guide
Copyright 1991–2003 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 areeither registeredtrademarksor trademarksof AdobeSystems Incorporated inthe UnitedStates
and/or other countries. Apple, Macintosh, and Mac are trademarks of Apple Computer, Inc. registered in the United States and other
countries.Microsoft andWindows 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 CS Scripting Guide
iii
Table of contents
Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 What is scripting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.3 Why use scripting?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.4 What about actions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.5 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.6 JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.7 Choosing a scripting language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.8 Legacy COM scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.9 New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.10 What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Chapter 2 Scripting basics . . . . . . . . . . . . . . . . . . . . . . . 8
2.1 Documents as objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.2 Object model concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3 Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4 Documenting scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.5 Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.6 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.7 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.8 Commands and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.9 Handlers, subroutines and functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.10 Debugging and Error Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.11 What’s Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Chapter 3 Scripting Photoshop. . . . . . . . . . . . . . . . . . . . .31
3.1 Photoshop scripting guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.2 Viewing Photoshop objects, commands and methods. . . . . . . . . . . . . . . . . . . . 31
3.3 Your first Photoshop script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.4 Advanced Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Photoshop CS Scripting Guide
iv
Table of contents
3.5 Object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
3.6 Working with units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
3.7 Executing JavaScripts from AS orVB . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
3.8 The Application object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
3.9 Document object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
3.10 Layer objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
3.11 Text item object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
3.12 Selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
3.13 Working with Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
3.14 Channel object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
3.15 Color objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
3.16 History object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3.17 Clipboard interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Photoshop CS Scripting Guide
1
1
Introduction
1.1 About this manual
This manual provides an introduction to scriptingAdobe
®
Photoshop
®
CS 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 the Photoshop object model as well as generic scripting terminology,
concepts and techniques. Code examples are provided in three languages:
• AppleScript
•Visual Basic
•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-specific objects and components and describes advanced
techniques for scripting the Photoshop application.
Note : Please review the README file shipped with Photoshop CS for late-breaking news,
sample scripts, and information about oustanding issues.
1.1.1 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, 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, this manual follows the AppleScript
naming convention for that property and the Visual Basic and JavaScript names appear in
parenthesis. For example:
“The display dialogs ( DisplayDialogs/displayDialogs ) property is part of the
Application object.”

Photoshop CS Scripting Guide
2
Introduction
What is scripting?
1
In this case, display dialogs refers to theAppleScript property, DisplayDialogs refers
to the Visual Basic property and displayDialogs refers to the JavaScript property, as
illustrated below.
Once you become familiar with this notation, simply focus on the values and description for
the language you intend to use, ignoring the rest.
For larger blocks of code, scripting examples are often placed side by side.
AppleScript
layer 1 of layer set 1 of current document
Visual Basic
appRef.ActiveDocument.LayerSets(1).Layers(1)
JavaScript
app.activeDocument.layerSets[0].layers[0];
Finally, tables are sometimes used to organize lists of values specific to each scripting
language.
1.2 What is scripting?
A script is a series of commands that tells Photoshop 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 complex and affect many objects in a Photoshop document.
The actions can call Photoshop 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.
The display dialogs (DisplayDialogs/displayDialogs) property is part of the
Application object.
Visual Basic JavaScript
AppleScript

Photoshop CS Scripting Guide
3
Introduction
Why use scripting?
1
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 such as those described in this manual and move on to more
involved scripts as you become more proficient.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 two 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.
•Asingle script can target multiple hosts.Actions can’t. For example, you could target both
Photoshop and Illustrator in the same script.
The Actions palette, invoked under the Window menu, supports actions with a great deal of
sophistication (including the ability to display dialogs) and allows users to work with selected
objects, as illustrated below.

Photoshop CS Scripting Guide
4
Introduction
System requirements
1
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.
1.5.1 Mac
Any system that runs Photoshop CS will support scripting.You will also needAppleScript and
a script editor installed.AppleScript and the Script Editor application fromApple are included
with the Mac OS. For Mac OS X, 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 debugApple Scripts. For more details, check:
http://www.apple.com/applescript
We use the Script Editor from Apple in this manual.
For more information on theAppleScript scripting environment, see Section 3.2.1, “Viewing
Photoshop’s AppleScript dictionary
1.5.2 Windows
Any Windows system that runs Photoshop CS will support scripting.You will also need either
the Windows Scripting Host, MicrosoftVisual Basic, or one of the applications that contains a
Visual Basic editor. Most Windows systems include theWindows 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 the Microsoft Visual Basic developer framework to edit scripts in this manual.
For more information on the Visual Basic scripting environment, see Section 3.2.2, “Viewing
Photoshop’s type library (VB)

Photoshop CS Scripting Guide
5
Introduction
JavaScript
1
1.6 JavaScript
In addition to writingAppleScripts and Visual Basic scripts, you can also write cross-platform
JavaScripts (using the text editor or your choice) on either the Mac or Windows platform.
Photoshop provides a built-in, platform-independent framework for executing JavaScripts.
The easiest way to run your JavaScripts is to use the “File>Scripts” menu. JavaScripts are
stored in or accessed through the Scripts folder.
Scripts folder
The Scripts folder is located in the “Presets” folder of your Photoshop installation. All
JavaScript files placed in the Scripts folder are available for execution from the Scripts menu.
On both Mac and Windows, JavaScript files must be saved as text files with a '.js' file name
extension.
For more information on the JavaScript scripting environment, see Section 3.2.3, “Viewing the
JavaScript Environment.
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?
As mentioned earlier, JavaScript is a cross-platform language that works on either platform.
The same script will perform identically on Windows and Macintosh computers. However,
JavaScript is invoked from the Scripts menu within Photoshop and lacks 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 andVisual 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. On Mac OS, any
language which lets you send Apple events can be used to script Photoshop.
On Windows, any language which is COM aware can be used to script Photoshop.

Photoshop CS Scripting Guide
6
Introduction
Legacy COM scripting
1
1.8 Legacy COM scripting
Photoshop CS supports legacy COM scripting as long as you modify the way that you refer to
the Photoshop 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.8.1")
No other change is necessary for legacy COM scripts to run under Photoshop CS.
1.9 New Features
• Layer Comps
New to Photoshop CS is the ability to group layers into a "layer comp" or layer
composition.
A layer comp is a snapshot of a state of the Layers palette. Layer comps record three types
of layer options: layer visibility (whether a layer in the Layers palette is showing or
hidden); layer position in the document; and layer appearance (whether a layer style is
applied to the layer).
Designers often create multiple compositions or "comps" of a page layout to show clients.
Using layer comps, you can create, manage and view multiple versions of a layout in a
single Photoshop or ImageReady file.
•Web Photo Gallery
One of the most popular features of Photoshop is the ability to create a web photo gallery
out of a folder of files.You can now perform the same function through scripting.
•JavaScripts get their own Scripts menu
JavaScripts now join AppleScript and Visual Basic scripts as first-class citizens.You can
add your own custom JavaScripts to the Photoshop menu system. The JavaScripts you
write are displayed in the “File->Scripts” menu item along with several pre-built
JavaScripts that ship with the product.
• UI for JavaScript
New to Photoshop CS is the ability to create graphical interface objects, such as windows
and panels, employing the JavaScript programming language. UI for JavaScripts is covered
in the JavaScript Reference Guide.
•Paths
Although Illustrator is the premier path (or vector ) editing application, many users want to
modify their path items in Photoshop. This release of Photoshop allows you to manipulate
the path items and obtain path points in a Photoshop document. Functions include the
ability to create, modify, delete and copy paths using scripts.