Scripting Guide ® ® bc Adobe Photoshop cs2 © Copyright 2005 Adobe Systems Incorporated. All rights reserved. Adobe® Creative Suite 2 Photoshop® Scripting Guide for Windows® and Macintosh®. NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Adobe Systems Incorporated. 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. This publication and the information herein is furnished AS IS, 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, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights. Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization. Adobe, the Adobe logo, Illustrator, and Photoshop are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. Apple, Mac, and Macintosh 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. UNIX is a registered trademark of The Open Group. All other trademarks are the property of their respective owners. All other trademarks are the property of their respective owners. If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement. The content of this guide 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 the informational content contained in this guide. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Contents 1 Introduction ................................................................................................................................. 1 About this manual.......................................................................................................................................................................... 1 What is scripting? ........................................................................................................................................................................... 2 Why use scripting? ......................................................................................................................................................................... 2 Why use scripts instead of Actions?......................................................................................................................................... 2 System requirements.................................................................................................................................................................... 3 Choosing a scripting language ................................................................................................................................................. 4 New Features ................................................................................................................................................................................... 5 2 Scripting basics ............................................................................................................................ 6 Introducing Objects....................................................................................................................................................................... 6 Writing Script Statements ........................................................................................................................................................... 7 Object Model Concepts ............................................................................................................................................................... 7 Photoshop CS2's Object Model................................................................................................................................................. 8 Object Elements and Collections.............................................................................................................................................. 9 Object References ........................................................................................................................................................................11 Using Commands and Methods .............................................................................................................................................12 Using Variables..............................................................................................................................................................................13 Using Object Properties .............................................................................................................................................................18 Understanding Object Classes and Inheritance................................................................................................................19 Using Arrays ...................................................................................................................................................................................19 Documenting Scripts ..................................................................................................................................................................20 Using Long Script Lines..............................................................................................................................................................21 Creating a Sample Hello World Script...................................................................................................................................21 Using Operators............................................................................................................................................................................25 Using Conditional Statements.................................................................................................................................................26 Using Subroutines, Handlers and Functions ......................................................................................................................29 Executing JavaScripts from AS or VBS ..................................................................................................................................31 Passing AS or VBS Arguments to JavaScript.......................................................................................................................31 Testing and Troubleshooting ..................................................................................................................................................32 Bibliography...................................................................................................................................................................................34 3 Scripting Photoshop CS2 .......................................................................................................... 36 Viewing Photoshop CS2 Objects, Commands and Methods .......................................................................................36 Targeting and Referencing the Application Object.........................................................................................................37 Creating New Objects in a Script ............................................................................................................................................37 Setting the Active Object ..........................................................................................................................................................39 Opening a Document .................................................................................................................................................................42 Saving a Document .....................................................................................................................................................................44 Setting Application Preferences ............................................................................................................................................46 Allowing or Preventing Dialogs ..............................................................................................................................................46 Working with the Photoshop CS2 Object Model..............................................................................................................47 Working with Color Objects .....................................................................................................................................................63 Working with Filters ....................................................................................................................................................................65 Understanding Clipboard Interaction ..................................................................................................................................66 Working with Units ......................................................................................................................................................................68 iii Adobe Illustrator CS2 Visual Basic Scripting Reference Contents iv Sample Workflow Automation JavaScripts.........................................................................................................................71 Advanced Scripting .....................................................................................................................................................................72 Index ........................................................................................................................................... 85 1 Introduction About this manual This manual provides an introduction to scripting Adobe® Photoshop CS2® on Mac OS® and Windows®. Chapter one covers the basic conventions used in this manual and provides an overview of requirements for scripting Photoshop CS2. Chapter two covers the Photoshop CS2 object model as well as generic scripting terminology, concepts and techniques. Code examples are provided in three languages: AppleScript VBScript 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 CS2-specific objects and components and describes advanced techniques for scripting the Photoshop CS2 application. Note: Please review the README file shipped with Photoshop CS2 for late-breaking news, sample scripts, and information about outstanding issues. 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, VBScript and JavaScript. Please note the following shortcut notations: AS stands for AppleScript VBS stands for VBScript JS stands for JavaScript The 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 ...