Adobe 23101335 - Photoshop

ADOBE SYSTEMS INCORPORATED

Corporate Headquarters

345 Park Avenue

San Jose, CA 95110-2704

(408) 536-6000

http://partners.adobe.com

bbc

March 2002

Photoshop 7.0

Scripting Guide

Adobe Photoshop Scripting Guide

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

This manual suits for next models

Table of contents

Other Adobe Software manuals

Adobe

Adobe DRIVE 2 User manual

Adobe

Adobe 22020807 User manual

Adobe

Adobe 09972554AD01A12 - Acrobat Pro - Mac User manual

Adobe

Adobe 8500 User manual

Adobe

Adobe 65036570 - Director - PC User manual

Adobe

Adobe FLEX 2-MIGRATING APPLICATIONS TO FLEX 2 User manual

Adobe

Adobe ACROBAT 3 User manual

Adobe

Adobe PREMIERE PRO 2 User manual

Adobe

Adobe 17510676 - InDesign CS PageMaker Edition User manual

Adobe

Adobe FRAMEMAKER 6.0 User manual

Adobe

Adobe PHOTOSHOP CS2 User manual

Adobe

Adobe 22001438 - Acrobat - PC Guide

Adobe

Adobe PHOTOSHOP ELEMENTS 2.0 - LESSONS FOR EDUCATORS (ST. PATRICK S DAY... User manual

Adobe

Adobe 38043755 - ColdFusion Enterprise - Mac Instruction Manual

Adobe

Adobe 12001196 - Acrobat - Mac User manual

Adobe

Adobe 62000112DM - Acrobat 3D - PC User manual

Adobe

Adobe 62000112DM - Acrobat 3D - PC User manual

Adobe

Adobe 12040118 - After Effects Standard Operation instructions

Adobe

Adobe ILLUSTRATOR 10 Installation and operating instructions

Adobe

Adobe ACROBAT 9 HOW-TOS User manual

Adobe

Adobe 27510753 - InDesign CS2 - PC User manual

Adobe

Adobe 718659340025 - InDesign CS - PC Configuration guide

Adobe

Adobe 38039336 - Flash CS3 Professional User manual

Adobe

Adobe 29170516 - Photoshop Album - PC User manual

Popular Software manuals by other brands

COMPRO

COMPRO COMPROFM manual

Muratec

Muratec OFFICEBRIDGE ONLINE user guide

Oracle

Oracle Contact Center Anywhere 8.1 installation guide

Avaya

Avaya NULL One-X for RIM Blackberry user guide

HP ProLiant BL420c user guide

PS Audio

PS Audio PowerPlay Programming manual

Brady

Brady LOCKOUT PRO 3.0 Administrator's guide

Avaya

Avaya Interaction Center user guide

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Guide book

Novell

Novell GROUPWISE 8 - INTERNET AGENT manual

Oracle

Oracle Application 9i Configuration guide

Acer

Acer RDM user guide

Canon

Canon Vixia HF21 instruction manual

Canon

Canon ZR950 instruction manual

Samsung

Samsung Auto Backup user manual

Polycom

Polycom Vortex EF2201 Application note

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c user manual

Novell

Novell SP2 - S release note

Adobe 23101335 - Photoshop - PC User manual

Popular Software manuals by other brands