Photoshop CS5 Scripting Guide.pdf

SCRIPTING GUIDEADOBE PHOTOSHOP CS5 2010 Adobe Systems Incorporated.All rights reserved.Adobe Creative Suite 5 Photoshop Scripting GuideAdobe,the Adobe logo,Illustrator,and Photoshop are either registered trademarks or trademarks of Adobe Systems Inc.in the United States and/or other countries.Apple and Mac OS 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 other countries.JavaScript and all Java-related marks are trademarks or registered trademarks of Sun Microsystems,Inc.in the United States and other countries.All other trademarks are the property of their respective owners.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 Inc.Adobe Systems Inc.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 Systems Inc.,345 Park Avenue,San Jose,California 95110,USA.3Contents1Introduction.6About this Manual .6Conventions in this Guide .62Photoshop Scripting Basics.8Scripting Overview.8Why use scripts instead of actions?.8Scripting Support in Photoshop .9JavaScript support .9Executing other scripts.10Startup scripts .10Executing JavaScripts from AS or VBS.10Photoshop Object Model.11Containment hierarchy.11Application and document classes .12Layer classes.12Layer Comp class .13Channel class.13Selection class.13History State class .13Document Info class .13Path Item,Sub Path Item,and Path Point classes.14Preferences class.14Notifier class.14Count Item class.14Color Sampler class .14Measurement Scale class.14The containment hierarchy and the Photoshop user interface .14Additional objects .16Constants.16Creating a sample Hello World script.17Creating and running an AppleScript .18Creating and running a VBScript.19Creating and running a JavaScript.193Scripting Photoshop .21Viewing Photoshop Objects,Commands,and Methods.21Viewing Photoshops AppleScript dictionary.21Viewing Photoshops type library(VBS).22Targeting and Referencing the Application Object .22Creating New Objects in a Script.23Setting the Active Object.25Setting the active document .26Contents 4Setting the active layer.27Setting the active channels.28Opening a Document .28Opening a file with default file format .28Specifying file formats to open .29Saving a Document .31Setting Application Preferences .32Allowing or Preventing Dialogs.33Working with the Photoshop Object Model .33Using the Application object .34Using the Document object .34Manipulating a document object.35Working with layer objects .36Creating an ArtLayer object .37Creating a Layer Set object.38Referencing ArtLayer objects.38Working with Layer Set objects.39Linking layer objects.40Applying styles to layers .40Using the Text Item object .41Determining a layers kind .41Adding and manipulating text in a Text Item object.42Working with Selection objects.42Creating and defining a selection.43Stroking the selection border .44Inverting selections.44Expanding,contracting,and feathering selections .44Filling a selection .45Loading and storing selections.45Working with Channel objects.46Changing channel types .46Using the Document Info object.47Using history state objects .47Using Notifier objects .48Using the PathItem object.49Working with color objects .51Solid color classes.52Using hex values for RGB color .52Getting and converting colors.52Comparing colors.53Getting a Web-safe color.53Working with Filters.53Other filters.54Understanding Clipboard Interaction .54Using the copy and paste commands.54Using the copy merged command/method.55Working with Units.56Unit values .56Special unit value types.56Contents 5AppleScript unit considerations .56Using unit values in calculations.57Unit value usage.57Setting ruler and type units in a script .59Sample Workflow Automation JavaScripts .60Advanced Scripting .60Working with document preferences .61Applying color to a text item .64Applying a wave filter.66Defining the area of a selection object.67Applying a MotionBlur filter .714Action Manager.73The ScriptListener Plug-In .73Installing ScriptListener .73Action Manager Scripting Objects .74Recording a Script using ScriptListener .74Using the Action Manager from JavaScript.75Using the Action Manager from a VBS Script .76Running JavaScript-based Action Manager code from VBScript.79Running JavaScript-based Action Manager code from AppleScript.80Using ScriptListener to find event IDs and class IDs.81Index.84 61IntroductionAbout this ManualThis manual provides an introduction to scripting Adobe Photoshop CS5 on Mac OS and Windows.Chapter 1 covers the basic conventions used in this manual.Chapter 2 covers a brief overview of scripting,how to execute scripts,and the Photoshop object model.Chapter 3 covers Photoshop-specific objects and components and describes advanced techniques for scripting the Photoshop application.Code examples are provided in three languages:AppleScriptVBScriptJavaScriptTMNOTE:Separate Photoshop scripting reference information is provided for each of these languages through the Scripting Reference Manuals provided with this installation,or through the object browsers available for each language.See“Viewing Photoshops AppleScript dictionary”on page 21 and“Viewing Photoshops type library(VBS)”on page 22.For information about using the Extend Script Object Model Viewer,see the JavaScript Tools Guide.Chapter 4 covers the Action Manager,which allows you to write scripts that target Photoshop functionality that is not otherwise accessible in the scripting interface.NOTE:Please review the README file shipped with Photoshop for late-breaking news,sample scripts,and information about outstanding issues.Conventions in this GuideCode and specific language samples appear in monospaced courier font:app.documents.addSeveral conventions are used when referring to AppleScript,VBScript and JavaScript.Please note the following shortcut notations:AS stands for AppleScriptVBS stands for VBScriptJS stands for JavaScriptThe term“commands”will be used to refer both to commands in AppleScript and methods in VBScript and JavaScript.When referring to specific properties and commands,this manual follows the AppleScript naming convention for that property and the VBScript and JavaScript names appear in parenthesis.For example:“The display dialogs(DisplayDialogs/displayDialogs)property is part of the Application object.”CHAPTER 1:IntroductionConventions in this Guide 7In this case,display dialogs refers to the AppleScript property,DisplayDialogs refers to the VBScript property and displayDialogs refers to the JavaScript property.For larger blocks of code,scripting examples are listed on separate lines.ASlayer 1 of layer set 1 of current documentVBSappRef.ActiveDocument.LayerSets(1).Layers(1)JSapp.activeDocument.layerSets0.layers0Finally,tables are sometimes used to organize lists of values specific to each scripting language.82Photoshop Scripting BasicsThis chapter provides an overview of scripting for Photoshop,describes scripting support for the scripting languages AppleScript,VBScript,and JavaScript,how to execute scripts,and covers the Photoshop object model.It provides a simple example of how to write your first Photoshop script.If you are familiar with scripting or programming languages,you most likely will want to skip much of this chapter.Use the following list to locate information that is most relevant to you.For more information on the Photoshop object model,see“Photoshop Object Model”on page 11.For information on selecting a scripting language,refer to the Introduction to Scripting guide.For examples of scripts created specifically for use with Photoshop,see Chapter 3,“Scripting Photoshop”on page 21.For detailed information on Photoshop objects and commands,please use the reference information in the three reference manuals provided with this installation:Adobe Photoshop CS5 AppleScript Scripting Reference,Adobe Photoshop CS5 Visual Basic Scripting Reference,and Adobe Photoshop CS5 JavaScript Scripting Reference.NOTE:You can also view information about the Photoshop objects and commands through the object browsers for each of the three scripting languages.See“Viewing Photoshop Objects,Commands,and Methods”on page 21.Scripting OverviewA 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 they can be 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.If you are new to scripting,you should acquaint yourself with the basic scripting information provided in the Introduction to Scripting manual.Why use scripts instead of actions?If youve used Photoshop Actions,youre already familiar with the enormous benefits of automating repetitive tasks.Scripting allows you to extend those benefits by allowing you to add functionality that is not available for Photoshop Actions.For example,you can do the following with scripts and not with actions:You can add conditional logic,so that the script automatically makes“decisions”based on the current situation.For example,you could write a script that decides which color border to add depending on CHAPTER 2:Photoshop Scripting BasicsScripting Support in Photoshop 9the size of the selected area in an image:“If the selected area is smaller than 2 x 4 inches,add a green border;otherwise add a red border.”A single script can perform actions that involve multiple applications.For example,depending on the scripting language you are using,you could target both Photoshop and another Adobe Creative Suite 5 Application,such as Adobe Illustrator CS5,in the same script.You can open,save,and rename files using scripts.You can copy scripts from one computer to another.If you were using an Action and then switched computers,youd have to recreate the Action.Scripts provide more versatility for automatically opening files.When opening a file in an action,you must hard code the file location.In a script,you can use variables for file paths.NOTE:See Photoshop Help for more information on Photoshop Actions.Scripting Support in PhotoshopPhotoshop supports scripting in three scripting languages:AppleScript,VBScript,and JavaScript.AppleScript and JavaScript run on Mac OS,and JavaScript and VBScript run on Windows.For information about how to choose which scripting language to use,and for additional information about using these languages with Adobe applications,see Introduction to Scripting.See“Creating and running an AppleScript”on page 18,“Creating and running a VBScript”on page 19,and“Creating and running a JavaScript”on page 19.You can call JavaScript scripts from AppleScript and VBScript scripts.See“Executing JavaScripts from AS or VBS”on page 10.For a file to be recognized by Photoshop as a valid script file it must have the correct file name extension:JavaScript supportFor a JavaScript file to be recognized by Photoshop as a valid script file,it must use either a.js or a.jsx extension.On the Mac OS,there is no difference in the way scripts with the two extensions function.On Windows,if the script files is opened from inside Photoshop,there is no difference between using the.js and.jsx extension.However,if the script is launched by double-clicking on it,a script with the.js extension is interpreted with the Microsoft JScript engine,and it cannot launch Photoshop.For Windows,using the.jsx extension is preferable,since it interprets the script with the ExtendScript engine.Script typeFile type ExtensionPlatformAppleScriptcompiled script OSAS file.scpt(none)Mac OSJavaScriptExtendScripttext.js.jsxMac OS&WindowsVBScripttext.vbsWindowsVisual Basicexecutable.exeWindowsCHAPTER 2:Photoshop Scripting BasicsScripting Support in Photoshop 10Scripts written in JavaScript can be accessed from the Adobe Photoshop Scripts menu(File Scripts),which provides quick and easy access to your JavaScripts.By putting a JavaScript file into the appropriate location on disk,it can be accessed directly from the Photoshop menu.To install a JavaScript in the Scripts menu,place it in the Scripts folder(Photoshop CS5/Presets/Scripts).The names of the scripts in the Scripts folder,without the file name extension,are displayed in the Scripts menu.Any number of scripts may be installed in the Scripts menu.Scripts added to the Scripts folder while Photoshop is running do not appear in the Scripts menu until the next time you launch the application.All scripts found in the Scripts folder and sub-folders are displayed at the top level of the File Scripts menu.The addition of sub-folders does not add a hierarchical organization to the Scripts menu.Executing other scriptsThe Browse item at the end of the Scripts menu(File Scripts Browse)allows you to execute scripts that are not installed in the Scripts folder.You can also use Browse to select scripts installed in the Scripts folder after the application was last launched.Selecting Browse displays a file browser dialog which allows you to select a script file for execution.Only.js or.jsx files are displayed in the browse dialog.When you select a script file,it is executed the same way as an installed script.Startup scriptsOn startup,Photoshop executes all.jsx files that it finds in the startup folders.On Windows,the startup folder for user-defined scripts is:C:Program FilesCommon FilesAdobeStartup Scripts CS5Adobe PhotoshopOn Mac OS,the startup folder for user-defined scripts is:/Library/Application Support/Adobe/Startup Scripts CS5/Adobe PhotoshopIf your script is in this main startup folder,it is also executed by all other Adobe Creative Suite 5 applications at startup.If such a script is meant to be executed only by Photoshop,it must include code such as the following:if(BridgeTalk.appName=photoshop)/continue executing scriptFor additional details,see the JavaScript Tools Guide.Executing JavaScripts from AS or VBSYou can take advantage of JavaScripts platform-independence by running scripts from AppleScript or VBScript.You can execute either a single JavaScript statement or a complete JavaScript file.For more information,please refer to Introduction to Scripting.CHAPTER 2:Photoshop Scripting BasicsPhotoshop Object Model 11Photoshop Object ModelA document object model(D