Macromedia Photoshop - 7.0 Scripting Guide
Photoshop 7.0
bbc
Scripting Guide
ADOBE SYSTEMS INCORPORATED
Corporate Headquarters
345 Park Avenue
San Jose, CA 95110-2704
(408) 536-6000
http://partners.adobe.com
March 2002
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 thatmay appear in this document. The software described in t his document is furnished under license an d
may only be used or c opie d in accordance with the terms of such license.
Adobe, Photoshop, and PostScriptare either registered trademarks or trademarks of Adobe Systems Incorporated in the United States
and/or other count ries. Apple, Macint osh, and Mac are tr ademarks of Apple Comput er, Inc. registered in the United States and other
countries. Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation i n the United States and/or
other countries. All other trademarks are t he property of their respecti ve owners.
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 iii
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 iv
Introduction
1
1.1 About this manual
This manual provides an introduction to scripting Adobe Photoshop 7.0 on Mac OS and
Windows
overview of requirements for scripting Photoshop.
Chapter two covers basic scripting terms, concepts and techniques. Experienced A ppleScript
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
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.
®
. Chapter one covers the basic conventions used in this manual and provides an
fully functional scripts.
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:
display dialogs (DisplayDialogs/displayDialogs) property is part of the
“The
Application object.”
In this case,
to the Visual Basic property and
Photoshop 7.0 Scripting Guide 5
display dialogs refers to the AppleScript property,DisplayDialogs refers
displayDialogs refers to the JavaScript property.
Introduction
What is scripting?
1.2 What i s 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
illustrationand 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 m ove on to more involved
scripts. Any repetitive task is a good candidate for a script. Once you can i dentify the steps and
conditions involved in performing the task, you’re ready to write a script to take care of it.
1
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 t he 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 6
1.5.1 Ma c
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. Youwill 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 WindowsScripting 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/).
Introduction
JavaScript
1
We use Microsoft V isual 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 selectionwithin Photoshop and lacks
Photoshop 7.0 Scripting Guide 7
Introduction
Legacy COM scripting
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.
AppleScriptand VisualBasic are only offered on their respective platforms. However, you can
write scripts in those languages to controlmultiple 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.”
1
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 8
Scripting basics
2
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 Objec t model con cepts
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 t hat 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 9
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
inheritsproperties. 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:
Scripting basics
Object model concepts
2
AS:
document 1
VB: appRef.Documents (1)
JS: documents[0];
IMPORTANT: Indicesin 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 10
Scripting basics
Documenting scripts
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 runtime 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 *)
2
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 11
Scripting basics
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 Va l ue s
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
Values
2
integer Whole numbers (no decimal
points). Integers can be
positive or negative.
real A number which may
contain a decimal point.
string A series of text characters.
Strings appear inside
(straight) quotation marks.
list An ordered list of values.
The values of a list may be
any type.
object reference A specific reference to an
object.
record An unordered list of
properties, Each property is
identified by its label.
14
13.9972
"I am a string"
{10.0, 20.0, 30.0, 40.0}
current document
{name: "you", index: 1}
Photoshop 7.0 Scripting Guide 12
TABLE 2.2 Visual Basic Values
Value type: What it is: Example:
Boolean Logical true or false True
Scripting basics
Values
2
Long Whole numbers (no decimal
points). Longs can be
positive or negative.
Double A number which may
contain a decimal point.
String A series of text characters.
Strings appear inside
(straight) quotation marks.
Array A list of values. Arrays
contain a single value t ype
unless the type is defined as
Variant.
Object reference A specific reference to an
object.
T
ABLE 2.3 JavaScript Values
Value type: What it is: Example:
String A series of text characters.
Strings appear inside
(straight) quotation marks.
14
13.9972
"I am a string"
Array(10.0, 20.0, 30.0, 40.0)
appRef.ActiveDocument
"Hello"
Number Any number not inside
double quotes.
Boolean Logical true or false. true
Null Something that points to
nothing.
Object Properties and methods
belonging to an object or
array.
Undefined Devoid of any value undefined
Photoshop 7.0 Scripting Guide 13
3.7
null
activeDocument
2.5 Va r i ab l es
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
declareall of your variables before using them. To declare variables in VisualBasic,
use the
2.5.1 Assigning va lues to variable s
The remainder of this section shows how to assign values to variables.
Dim keyword. To declare variables in JavaScript, use the var keyword.
Scripting basics
Variables
2
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
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.
Option Explicit, you will have to declare all
Photoshop 7.0 Scripting Guide 14
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
assign a variable as you create a layer, use
Set thisLayer = appRef.Photoshop.ActiveDocument.ArtLayers(1)
or in reference to an existing layer, since it is also an object refere nce, 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
thisNumber = 12
Set. Use Visual Basic’s assignment operator, the equals sign:
Set:
Scripting basics
Variables
Set command. For example, to
2
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 Namin g variab les
It’s a good idea to use descriptive names for your variables—something like firstPage or
corporateLogo,ratherthanx or 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 15
Scripting basics
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 f or operators that may be unique to your OS.
Operators
2
AppleScript and Visual Basic use the ampersand (
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.”
&) as the concatenation operator to join two
Photoshop 7.0 Scripting Guide 16
Scripting basics
Commands and methods
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
retrieve objects and their properties.
VB
In VisualBasic, 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 (
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
get command to
=)toretrieve
2
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
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
if in all three scripting systems.
Photoshop 7.0 Scripting Guide 17
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
Scripting basics
Commands and methods
2
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 18
Scripting basics
Commands and methods
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
2
flag = False
Do Until flag = True
retVal = MsgBox("Quit?", vbOKCancel)
If (retVal = vbOK) Then
flag = True
End If
Loop
Photoshop 7.0 Scripting Guide 19
Scripting basics
Handlers, subroutines and functions
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.
2
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
Photoshop 7.0 Scripting Guide 20
VB
Private Sub ScriptSample_Click(Index As Integer)
result = DoConfirm("Are you sure?")
MsgBox (result)
End Sub
Function DoConfirm(prompt) As Boolean
buttonPressed = MsgBox(prompt, vbYesNo)
DoConfirm = (buttonPressed = vbYes)
End Function
JS
var theResult = DoConfirm( "Are you sure?" );
alert(theResult);
function DoConfirm(message)
{
var result = confirm(message);
return result;
}
Scripting basics
The Scripts menu
2
2.9 The Scripts menu
The Scripts menu item is located in the File > Automate menu. When the Scripts...
item is selected, a dialog is presented from which you can select a JavaScript for execution.
The scripts listed in the dialog are in the Scripts folder
2.9.1 Scripts folder
The Scripts folder is in the Photoshop/Presets folder. This folder is created during Scripting
Support functionality installation. All JavaScript files placed in the Scripts folder w ill be
available for execution from the Scripts Dialog. Only those script f iles found in the root of the
folder will be listed. Any files in subfolders will be ignored and not listed in the dialog. For
both Mac and Windows, a JavaScript file must be saved as a text file with a '.js' file name
extension.
2.9.2 The scripts d ialog box
To execute a script, select it from the list of scripts and click the “Run Script” button. If there is
an error e ncountered during script execution, an error dialog will be displayed containing the
error message returned by the script. If you hold down the option key (alt for Windows), the
Photoshop 7.0 Scripting Guide 21
Scripting basics
The Scripts menu
“Run Script” button will change to “Debug Script.” Clicking this button will execute the
JavaScript in a debug window. See 2.10.3, “JavaScript Debugging” on page 26 for more
information.
There is also a “Browse...” button in the Scripts dialog. When this button is clicked, a file
navigation dialog will be presented. Use this dialog to l ocate and execute scripts outside of the
Scripts folder.If the option (or alt) key is held down when the “Browse…” button is clicked,
the script chosen in the dialog will be executed in debug mode. Here’s the dialog:
2
Photoshop 7.0 Scripting Guide 22
2.10 Testing and troubleshooting
The scripting environments provide tools for monitoring the progress of your script while it is
running — which make it easier for you to track down any problems your script might be
encountering or causing.
2.10.1 AppleScript debugging
While the basic syntax of your script will be checked when compiled, it is possible to create
and compile scripts in AppleScript that will not run properly. The Script Editor Application
doesn’t have extensive debugging tools, but it does have the an Event Log window.
To watch the commands your script sends and the results it receives, choose “Controls > Open
Event Log”. The Script Editor displays the Event Log window. Check the “Show Events” and
“Show Events Results” options at the top of the “Event Log” window and run your script. As
the script executes, you’ll see the commands sent to Photoshop, and Photoshop’s responses.
Scripting basics
Testing and troubleshooting
2
Photoshop 7.0 Scripting Guide 23
Scripting basics
Testing and troubleshooting
You can display the contents of one or more variables in the log window by using the log
command.
log {myVariable, otherVariable}
In addition, the Result window ( choose Controls > Show Result) will display the value from
the last script statement evaluated. Third-party editors offer additional debugging features
2
Photoshop 7.0 Scripting Guide 24
2.10.2 Visual Basic debugging
In Visual Basic, you can stop your script at any point, or step through your script one line at a
time. To stop your script at a particular line, select that line in your script and choose “Debug >
Toggle Breakpoint”.
When you run the script, Visual Basic will stop at the breakpoint you have set. Choose “Debug
> Step Into” (or press F8) to execute the next line of your script, or choose “Run > Start” (or
press F5) to continue normal execution of the script.
You can also observe the values of variables defined in your script using the “Watch” window
— a very valuable tool for debugging your scripts. To view a variable in the “Watch” window,
select the variable and choose “Debug > Quick Watch”. Visual Basic displays the
“Quick Watch” dialog box. Click the “Add” button. Visual Basic displays the “Watch”
window. If you have closed the "Watch" window, you can display it again by choosing “View
> Watch Window.”
Scripting basics
Testing and troubleshooting
2
Check your Visual Basic documentation for more information. Windows Scripting Host also
provides debugging information.
Photoshop 7.0 Scripting Guide 25
2.10.3 JavaScript Debugging
This section describes the information and controls that the main Script Debugger window
provides.
In Photoshop you can use the JavaScript Debugger Window to step through your JavaScript
code.
JavaScript can be executed in two different ways: from the UI via the “Scripts...” menu and
from AppleScript of VisualBasic via the
Testing and troubleshooting
do javascript methods.
Scripting basics
2
When running JavaScript from the UI you must hold down the
alt on Windows to activate the debugger. When you hold down this modifier key the “Run
Script” button changes to “Debug Script”.
When invoking JavaScript from AppleScript or VB you must set the
argument appropriately.
If you set
running the JavaScript from the UI without holding down the modifier key.
If you set
until it detects a run-time error or until it meets a “debugger;” call (see below for an example).
When this happens execution will be stopped and the JavaScript debugger will be shown.
If you set
first line of JavaScript code and the debugger will be shown. This mode corrseponds to
executing JavaScripts from the UI while holding down the modifier key.
show debugger to never you will disable debugging. This corresponds to
show debugger to on runtime error your JavaScript will execute normally
show debugger to at beginning your JavaScript will halt before executing the
option key on the Mac and
show debugger
Photoshop 7.0 Scripting Guide 26
Scripting basics
Testing and troubleshooting
Viewing Debug Informat ion
The Photoshop Script Debugger window provides three informational views that Figure 2.1
depicts.
FIGURE 2.1 Script Debugger window
Stack Trace view
Debug Output view
JavaScript Source view
2
Resume (R)
Pause (P)
Stop (K)
StepOver (S)
StepInto(T)
Script Breakpoints Display
Step Out (U)
The current stack trace appears in the upper-left pane of the script debugger window. This
stack trace view displays the calling hierarchy at the time of the breakpoint. Double-clicking
a line in this view changes the current scope, enabling you to inspect and modify scopespecific data.
All debugging output appears in the upper-right pane of the script debugger window.
The currently-executing JavaScript source appears in the lower pane of the script debugger
window. Double-clickinga line in this JavaScript source view sets or clears an unconditional
breakpoint on that line; that is, if a breakpoint is in effect for that line, double-clicking it clears
the breakpoint, and vice-versa.
Photoshop 7.0 Scripting Guide 27
Scripting basics
Testing and troubleshooting
Controlling Code Execution in the Script Debugger Window
This section describes the buttons that control the execution of code when the Script Debugger
window is active. Most of these buttons also provide a keyboard shortcut available as a
key combination on Windows platforms or a Cmd-key combination on Mac OS platforms.
Resume
Cmd-R (Mac OS)
Ctrl-R (Windows)
Resume execution of the script with the script debugger window open. When the script
terminates, Photoshop closes the script debugger window automatically. Closing the debugger
window manually also causes script execution to resume. This button is enabled when script
execution is paused or stopped.
Pause
Cmd-P (Mac OS)
Ctrl-P (Windows)
Halt the currently-executing script temporarily and reactivate the script debugger window.
This button is enabled when a script is running.
Stop
Cmd-K (Mac OS)
Ctrl-K (Windows)
Ctrl-
2
Stop execution of the script and generate a runtime error. This button is enabled when a script
is running.
Step Into
Ctrl-T (Mac OS)
Cmd-T) (Windows)
Halt after executing a single JavaScript statement in the script or after executing a single
statement in any JavaScript function the script calls.
Step Over
Ctrl-S (Mac OS)
Cmd-S (Windows)
Halt after executing a single JavaScript statement in the script; if the statement calls a
JavaScript function, execute the function in its entirety before stopping.
Step Out
Ctrl-U (Mac OS)
Cmd-U (Windows)
When the debugger is paused within the body of a JavaScript function, clicking this button
resumes script execution until the function returns. When paused outside the body of a
function, clicking this button resumes script execution until the script terminates.
Photoshop 7.0 Scripting Guide 28
Loading...