Macromedia Illustrator - CS5 Scripting Guide
ADOBE® ILLUSTRATOR® CS5
ADOBE ILLUSTRATOR CS5
SCRIPTING GUIDE
© 2010 Adobe Systems Incorporated. All rights reserved.
Adobe Illustrator CS5 Scripting Guide
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.
Please remember that existing artwork or images that you may want to include in your project may be protected under
copyright law. The unauthorized incorporation of such material into your new work could be a violation of the rights of
the copyright owner. Please be sure to obtain any permission required from the copyright owner.
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, Photoshop, and InDesign are either registered trademarks or trademarks of Adobe
Systems Incorporated in the United States and/or other countries.
Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States
and/or other countries. Apple, Mac, Macintosh, and Mac OS are trademarks of Apple Computer, Incorporated, registered
in the United States and other countries. JavaScript and all Java-related marks are trademarks or registered trademarks of
Sun Microsystems, Incorporated 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.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA. Notice to U.S. Government End Users.
The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101, consisting of
“Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48
C.F.R. §12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through
227.7202-4, as applicable, the Commercial Computer Software and Commercial Computer Software Documentation are
being licensed to U.S. Government end users (a) only as Commercial Items and (b) with only those rights as are granted
to all other end users pursuant to the terms and conditions herein. Unpublished-rights reserved under the copyright
laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA 95110-2704, USA. For U.S.
Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if appropriate, the
provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act
of 1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR
Parts 60-1 through 60-60, 60-250, and 60-741. The affirmative action clause and regulations contained in the preceding
sentence shall be incorporated by reference.
Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What is scripting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Why use scripting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What about actions? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Scripting language support in Adobe Illustrator CS5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Script file extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
JavaScript development options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Viewing sample scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Viewing the object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Viewing the JavaScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Viewing the AppleScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Viewing the VBScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Executing scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installing scripts in the Scripts menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Executing scripts from the Other Scripts menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Startup scripts (.jsx scripts only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Changes in CS5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Ruler origin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Enumeration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Data class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2 The Illustrator Scripting Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Object-naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Top-level (containing) objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
The artwork tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Art styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Color objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Text objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Objects that represent text content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Text styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Dynamic objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3
Contents 4
3 Scripting Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Launching and quitting Illustrator from a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Launching and activating Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Quitting Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Working with objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Getting the frontmost document or layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Collection objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Notes on renaming objects stored in the application’s panels . . . . . . . . . . . . . . . . . . . . . . . . 29
Measurement units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Em space units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Page-item positioning and dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Art item bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
User-interaction levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Printing Illustrator documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4 Scripting with AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Obtaining objects from documents and layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Working with the perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Use perspective presets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Show or hide the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Set the active plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Draw on a perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Bring objects into perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5 Scripting with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Working with methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Accessing and referencing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Referencing the application object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Contents 5
Accessing objects in collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Working with the perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Use perspective presets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Show or hide the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Set the active plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Draw on a perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Bring objects into perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6 Scripting with VBScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Accessing and referencing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Obtaining objects from collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Working with enumeration values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Working with the perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Use perspective presets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Show or hide the grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Set the active plane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Draw on a perspective grid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Bring objects into perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
1
Introduction
This guide describes the scripting interface to Adobe® Illustrator® CS5.
If you are new to scripting or want basic information about scripting and how to use the different scripting
languages, see Adobe Introduction to Scripting.
What is scripting?
A script is a series of commands that tells Illustrator to perform one or more tasks. These tasks can be
simple, affecting only one object in the current document, or complex, affecting objects in all your
Illustrator documents. The tasks might even involve other applications, like word processors, spreadsheets,
and database management programs.
For the most part, the building blocks of scripting correspond to the Illustrator tools, menus, panels, and
dialog boxes with which you are already an expert. If you know what you want Illustrator to do, you can
write a script to do it.
Why use scripting?
Graphic design is a field characterized by creativity, but aspects of the work are anything but creative. In
fact, you probably notice that the time you spend placing and replacing images, correcting errors in text,
and preparing files for printing at an image-setting service provider often reduces the time you have
available for doing creative work.
With a small investment of time and effort, you can learn to write short, simple scripts that perform
repetitive tasks for you. As your scripting skills grow, you can move on to more complex scripts.
Scripting also can enhance your creativity, by quickly performing tasks you might not have time to try. For
example, you could write a script to systematically create a series of objects, modifying the new objects’
position, stroke, and fill properties along the way. You also could write a script that accesses built-in
transformation matrix functions to stretch, scale, and distort a series of objects. Without scripting, you
would likely miss out on the creative potential of such labor-intensive techniques.
What about actions?
Both actions and scripts are ways of automating repetitive tasks, but they work very differently:
X Actions use a program’s user interface to do their work. As an action runs, menu choices are executed,
objects are selected, and recorded paths are created. Scripts do not use a program’s user interface to
perform tasks, and scripts can execute faster than actions.
X Actions have very limited facilities for getting and responding to information. You cannot add
conditional logic to an action; therefore, actions cannot make decisions based on the current
situation, like changing the stroke type of rectangles but not ellipses. Scripts can get information and
make decisions and calculations based on the information they receive from Illustrator.
X A script can execute an action, but actions cannot execute scripts.
6
CHAPTER 1: Introduction Scripting language support in Adobe Illustrator CS5 7
Scripting language support in Adobe Illustrator CS5
Illustrator scripting supports VBScript and JavaScript scripts for Windows, and AppleScript and JavaScript
scripts for Mac OS.
Script file extensions
For a file to be recognized by Adobe Illustrator CS5 as a valid script file, the file must have the correct file
name extension:
Script type File type (extension) Platforms
AppleScript compiled script (
OSAS file (no extension)
JavaScript or ExtendScript text (
VBScript text (
.js or.jsx) Windows
.vbs)Windows
JavaScript development options
You can use the ExtendScript Toolkit to create JavaScript scripts explicitly for Illustrator, or you can use the
Creative Suite Extension Builder and the Creative Suite SDK to develop CS extensions in ActionScript. CS
extensions are Flash-based (SWF) and can potentially work in a variety of Creative Suite applications.
Developing a CS5 extension using ActionScript
In Creative Suite 5, the applications have an extensibility infrastructure that allows developers to extend
the capabilities of the applications; the infrastructure is based on Flash/Flex technology, and each CS5
extension is delivered as compiled Flash (SWF) file. Creative Suite 5 includes the Extension Manager to
enable installation of CS5 extensions.
An example of a CS5 extension that ships with the point products is Adobe Kuler. Kuler has a consistent
user interface across the different suite applications, but has different logic in each, adapted to the host
application.
.scpt)
Mac OS
Mac OS
The user interface for an extension is written in ActionScript, using the Flex framework. A C5S extension is
typically accessed through its own menu item in the application’s Extensions menu. CS Extension Builder
allows you to design the user interface interactively using the Design view of FlashBuilder. The Creative
Suite SDK also allows you to develop all of the application logic for your CS5 extension in ActionScript; you
can develop and debug your extension in the familiar FlashBuilder environment.
To develop your application logic, we recommend using the Creative Suite ActionScript Wrapper Library
(
CSAWLib), which exposes the scripting DOM of each host application as an ActionScript library. This is
tightly integrated with the CS Extension Builder environment, which includes wizards to help you build
your extension’s basic structure, and run and debug your code against suite applications such as Adobe
InDesign, Photoshop and Illustrator.
The methods, properties, and behavior of the scripting DOM is as described in the JavaScript Scripting
Reference for the host application. For details of how to use CS Extension Builder and the wrapper libraries,
CHAPTER 1: Introduction Viewing sample scripts 8
see the Creative Suite SDK documentation, which is accessible from within the Flash Builder or Eclipse
Help system when you have installed CSIDE.
ExtendScript features
If you write Illustrator-specific scripts that use the Illustrator JavaScript DOM directly, you will create
ExtendScript files, which are distinguished by the
extension (rather than the standard
ExtendScript features and tools.
ExtendScript offers all standard JavaScript features, plus a development and debugging environment, the
ExtendScript Toolkit (ESTK). The ESTK is installed with all scriptable Adobe applications, and is the default
editor for JSX files. The ESTK includes an Object Model Viewer that contains complete documentation of
the methods and properties of JavaScript objects. For information on accessing the ESTK and the Object
Model Viewer, see “
ExtendScript also provides various tools and utilities, including the following:
X A localization utility
X Tools that allow you to combine scripts and direct them to particular applications
Viewing the JavaScript object model” on page 9.
.js extension for a JavaScript file) allows you to take advantage of
.jsx extension. Giving your JavaScript files a .jsx
X Platform-independent file and folder representation
X Tools for building user interfaces to your scripts
X A messaging framework that allows you to send and receive scripts and data among scripting-enabled
Adobe applications
All of these features are available whether you use the DOM directly with a JSX file, or indirectly through
the ActionScript wrapper library and CSIDE. For details of these and other features, see JavaScript Tools
Guide.
Viewing sample scripts
Adobe provides sample scripts for many objects, properties, and methods in the Illustrator CS5 DOM. You
can view script samples in two locations:
X In the /Scripting/Sample Scripts folder in your Illustrator CS5 installation directory
X In the Adobe Illustrator CS5 scripting reference for your scripting language, which you can download
from http://www.adobe.com/devnet/illustrator/scripting/
Viewing the object model
Each of the supported scripting languages provides a facility for viewing the scripting objects defined by
Illustrator, with reference details.
CHAPTER 1: Introduction Viewing the object model 9
Viewing the JavaScript object model
To view the JavaScript object model for Illustrator, follow these steps:
1. Start the ESTK.
In a default Adobe installation, the ESTK is in the following location:
Z Windows:
system drive\Program Files\Adobe\Adobe Utilities CS5\ExtendScript Toolkit CS5
Z Mac OS:
system drive:Applications:Utilities:Adobe Utilities CS5:ExtendScript Toolkit CS5
2. In the ESTK, choose Help > Object Model Viewer.
3. In the Object Model Viewer window, select Adobe Illustrator CS5 Type Library from the Browser
drop-down list.
Several extended sample scripts are available in the
/Scripting/Sample Scripts folder in your Illustrator
CS5 installation directory.
You also can view script samples and information about individual classes, objects, properties, methods,
and parameters in Adobe Illustrator CS5 Scripting Reference: JavaScript, which you can download from
http://www.adobe.com/devnet/illustrator/scripting/
Viewing the AppleScript object model
Apple provides a Script Editor with all Mac OS systems. You can use Script Editor to view the AppleScript
dictionary that describes Illustrator objects and commands.
For details of how to use Script Editor, see Script Editor Help.
1. Start Script Editor.
OTE: In a default Mac OS installation, Script Editor is in Applications:AppleScript:Script
N
Editor
CD.
2. Choose File > Open Dictionary. Script Editor displays an Open Dictionary dialog.
3. In the Open Dictionary dialog, find and select Adobe Illustrator CS5, and click Open.
Script Editor displays a list of the Illustrator objects and commands, which include the properties and
elements associated with each object and the parameters for each command.
. If you cannot find the Script Editor application, you must reinstall it from your Mac OS system
.
Several extended sample scripts are in the
:Scripting:Sample Scripts folder in your Illustrator CS5
installation directory.
You also can view script samples and information about individual classes, objects, properties, methods
and parameters in Adobe Illustrator CS5 Scripting Reference: AppleScript, which you can download from
http://www.adobe.com/devnet/illustrator/scripting/
.
CHAPTER 1: Introduction Executing scripts 10
Viewing the VBScript object model
VBScript provides a type library you can use to view Illustrator object properties and methods. This
procedure explains how to view the type library through any Microsoft Office program. Your VBScript
editor probably provides access to the library. For information see your editor’s Help.
1. In any Microsoft Office application, choose Tools > Macro > Visual Basic Editor.
2. In the Visual Basic Editor, choose Tools > References.
3. In the dialog that appears, select the check box for Adobe Illustrator CS5 Type Library, and click OK.
4. Choose View > Object Browser, to display the Object Browser window.
5. Choose “Illustrator” from the list of open libraries in the top-left pull-down menu of the Object
Browser window.
Several extended sample scripts are in the
installation directory.
You also can view script samples and information about individual classes, objects, properties, methods,
and parameters in Adobe Illustrator CS5 Scripting Reference: VBScript, which you can download from
http://www.adobe.com/devnet/illustrator/scripting/
Executing scripts
The Illustrator interface includes a Scripts menu (File > Scripts) that provides quick and easy access to your
scripts.
Scripts can be listed directly as menu items that run when you select them. See “
Scripts menu” on page 10.
You can navigate from the menu to any script in your file system and then run the script. See “
scripts from the Other Scripts menu item” on page 11.
You also can have JavaScript scripts with a
application. For information, see “
Installing scripts in the Scripts menu
Startup scripts (.jsx scripts only)” on page 11.
/Scripting/Sample Scripts folder in your Illustrator CS5
.
Installing scripts in the
Executing
.jsx extension start automatically when you launch the
To include a script in the Scripts menu (File > Scripts), save the script in the Scripts folder, located in the
/Illustrator CS5/Presets folder in your Illustrator CS5 installation directory. The script’s filename,
minus the file extension, appears in the Scripts menu.
Scripts that you add to the Scripts folder while Illustrator is running do not appear in the Scripts menu until
the next time you launch Illustrator.
Any number of scripts can be installed in the Scripts menu. If you have many scripts, use subfolders in the
Scripts folder to help organize the scripts in the Scripts menu. Each subfolder is displayed as a separate
submenu containing the scripts in that subfolder.
CHAPTER 1: Introduction Executing scripts 11
Executing scripts from the Other Scripts menu item
The Other Scripts item at the end of the Scripts menu (File > Scripts > Other Scripts) allows you to execute
scripts that are not installed in the Scripts folder.
Selecting Other Scripts displays a Browse dialog, which you use to navigate to a script file. When you select
the file, the script is executed.
Only files that are of one of the supported file types are displayed in the browse dialog. For details, see
“
Scripting language support in Adobe Illustrator CS5” on page 7.
Startup scripts (.jsx scripts only)
JavaScript scripts with a .jsx file extension can be installed in one of two folders, so the scripts run
automatically when you launch Illustrator and each time you run a script. The folders are:
X An application-specific startup scripts folder, which contains scripts for Illustrator CS5
X A general startup scripts folder, which contains scripts that run automatically when you start any
Creative Suite 5 application
Application-specific startup scripts folder
You must place application-specific startup scripts in a folder named Startup Scripts, which you create
in the Illustrator installation directory.
For example, when Illustrator CS5 is installed to its default location, you would create the
Startup Scripts folder at the following location:
X Windows: C:\Program Files\Adobe\Adobe Illustrator CS5\Startup Scripts\
X Mac OS: /Applications/Adobe Illustrator CS5/Startup Scripts/
JavaScript scripts with a
X The application is launched.
X Any JavaScript file is selected from the Scripts menu (File > Scripts).
.jsx extension placed in the Startup Scripts folder run automatically when:
General startup scripts folder
The general startup scripts folder contains scripts that run automatically when you start any Creative
Suite 5 application. You create the folder in the following location:
X Windows: Program Files/Common Files/Adobe/Startup Scripts CS5/Illustrator
X Mac OS: :Library:Application Support:Adobe:Startup Scripts CS5:Illustrator
If a script in the general startup folder is meant to be executed only by Illustrator, the script must include
the ExtendScript
if( BridgeTalk.appName == "illustrator" ) {
//continue executing script
}
#target directive (#target illustrator) or code like the following:
CHAPTER 1: Introduction Changes in CS5 12
For details, see JavaScript Tools Guide.
Changes in CS5
This section lists changes made to the scripting object model to support features in Illustrator CS5.
Ruler origin
In previous releases, the artboard origin, the position with coordinates (0,0), was in the bottom left corner,
with positive X increments going left to right, and positive Y increments going bottom to top.
In Illustrator CS5, the artboard origin is defined to be the top left corner of the artboard. Positive X
increments still go left to right, but positive Y increments now go top to bottom.
To show rulers, choose View > Rulers > Show Rulers. Use the Info panel (Windows > Info) to inspect the
X/Y coordinates of a position.
To avoid breaking existing scripts, Illustrator scripting still uses the legacy coordinate system; that is, all
documents created through scripts use the legacy coordinate system. Documents that you create directly
in the UI use the new coordinate system. If your script operates on such a document, then in order for the
script to behave as it did in CS4, the script must translate the Y coordinate value for any position to -Y, and
the reverse when interpreting coordinate values from the document.
Enumeration
X A new enumeration for coordinate system used by Illustrator:
Z AppleScript — artboard coordinate system/document coordinate system
JavaScript — CoordinateSystem
Z
VBScript — AiCoordinateSystem
Z
A new enumeration for registration points for symbols:
X
Z AppleScript — N/A
CHAPTER 1: Introduction Changes in CS5 13
JavaScript — SymbolRegistrationPoint
Z
Z VBScript — AiSymbolRegistrationPoint
X A new enumeration for perspective grid plane type:
Z AppleScript — floorplane/leftplane/noplane/rightplane
Z JavaScript — PerspectiveGridPlaneType
Z VBScript — AiPerspectiveGridPlaneType
X A new enumeration for the type of text anti-aliasing:
Z AppleScript — crisp/none/sharp/strong
Z JavaScript — TextAntiAlias
Z VBScript — AiTextAntialias
X A new enumeration value for artwork printing orientation:
Z AppleScript — auto rotate
Class
JavaScript — PrintOrientation.AUTOROTATE
Z
Z VBScript — AiAutoRotate
X A new enumeration value for the FXG file format version:
Z AppleScript — version 2.0
JavaScript — FXGVersion.VERSION2PT0
Z
Z VBScript — AiVersion2Pt0
X A new enumeration value for the text preservation policy used by the FXG file format:
Z AppleScript — autoConvert text
JavaScript — TextPreservePolicy.AUTOMATICALLYCONVERTTEXT
Z
Z VBScript — AiAutomaticallyConvertText
X New property for the coordinate system in Application class:
Z AppleScript — coordinate system
Z JavaScript — coordinateSystem
Z VBScript — CoordinateSystem
X New properties in the Artboard class for setting the ruler origin, relative to (0,0) in the top left corner,
and for the artboard name:
Z AppleScript
CHAPTER 1: Introduction Changes in CS5 14
ruler origin of artboard 1 of document 1
name of artboard 1 of document 1
Z JavaScript
activeDocument.artboards[0].rulerOrigin
activeDocument.artboards[0].name
Z VBScript
ActiveDocument.Artboards[1].RulerOrigin
ActiveDocument.Artboards[1].Name
New method/command in Document class for working with different coordinate systems:
X
Z AppleScript — convert coordinate
Z JavaScript — app.activeDocument.convertCoordinate()
Z VBScript — App.ActiveDocument.ConvertCoordinate()
X New methods/commands in the Document class for working with multiple artboards:
Z AppleScript
select objects on active artboard
fit artboard to selected art
rearrange artboards
JavaScript
Z
activeDocument.selectObjectsOnActiveArtboard()
activeDocument.fitArtboardToSelectedArt()
activeDocument.rearrangeArtboards()
VBScript
Z
ActiveDocument.SelectObjectsOnActiveArtboard()
ActiveDocument.FitArtboardToSelectedArt()
ActiveDocument.RearrangeArtboards()
New methods/commands in the Document class for working with Perspective Grids:
X
Z AppleScript
import perspective grid preset
export perspective grid preset
select perspective preset
show perspective grid
hide perspective grid
get perspective active plane
set perspective active plane
JavaScript
Z
app.activeDocument.importPerspectiveGridPreset()
app.activeDocument.exportPerspectiveGridPreset()
app.activeDocument.selectPerspectiveGrid()
app.activeDocument.showPerspectiveGrid()
app.activeDocument.hidePerspectiveGrid()
app.activeDocument.getPerspectiveActivePlane()
app.activeDocument.setPerspectiveActivePlane()
CHAPTER 1: Introduction Changes in CS5 15
VBScript
Z
App.ActiveDocument.ImportPerspectiveGridPreset()
App.ActiveDocument.ExportPerspectiveGridPreset()
App.ActiveDocument.SelectPerspectiveGrid()
App.ActiveDocument.ShowPerspectiveGrid()
App.ActiveDocument.HidePerspectiveGrid()
App.ActiveDocument.GetPerspectiveActivePlane()
App.ActiveDocument.SetPerspectiveActivePlane()
New method in PageItem class for working with Perspective Grids:
X
Z AppleScript — bring in perspective
Z JavaScript — bringInPerspective()
Z VBScript — BringInPerspective()
X New property in PageItem class for pixel alignment:
Z AppleScript — pixel aligned
JavaScript — pixelAligned
Z
VBScript — PixelAligned
Z
X A new , optional creation argument for the Add method of the Symbols collection that allows you to
set the registration point of new symbols —
X New property in the TextFrameItem class for the type of text anti-aliasing:
Z AppleScript — antialias
Z
Z
Data class
X The class PrintFLOptions is renamed to PrintFlattenerOptions in JavaScript and VBScript. In
AppleScript,
X Changes to properties in the FXGSaveOptions data class:
Z AppleScript
RegistrationPoint.
JavaScript — antialias
VBScript — Antialias
flattening options remains unchanged.
Added:
blends policy
Removed: clip content
Changed defaults:
version: from version 1.0 to version 2.0
text policy: from keep text editable to autoConvert text
gradients policy
: from keep gradients editable to autoConvert gradients
JavaScript
Z
Added:
blendsPolicy
Removed: clipContent
Changed defaults:
CHAPTER 1: Introduction Known issues 16
: from FXGVersion.VERSION1PT0 to FXGVersion.VERSION2PT0
: from textPolicy.KEEPTEXTEDITABLE to AUTOMATICALLYCONVERTTEXT
AUTOMATICALLYCONVERTGRADIENTS
BlendsPolicy
Z
version
textPolicy
gradientsPolicy: from gradientsPolicy.KEEPGRADIENTSEDITABLE to
VBScript
Added:
Removed: ClipContent
Changed defaults:
Version: from FXGVersion.VERSION1PT0 to FXGVersion.VERSION2PT0
TextPolicy
GradientsPolicy
aiAutomaticallyConvertGradients
New properties in the OpenOptions data class for dealing with artboards:
X
Z AppleScript
convert crop area to artboard
convert tiles to artboard
create artboard with artwork bounding box
preserve legacy artboard
JavaScript
Z
: from aiKeepTextEditable to aiAutomaticallyConvertText
: from aiKeepGradientsEditable to
convertCropAreaToArtboard
convertTilesToArtboard
createArtboardWithArtworkBoundingBox
preserveLegacyArtboard
VBScript
Z
ConvertCropAreaToArtboard
ConvertTilesToArtboard
CreateArtboardWithArtworkBoundingBox
PreserveLegacyArtboard
Known issues
X Scripts that create, save, and close many Illustrator files should periodically quit and relaunch
Illustrator. The recommended maximum number of files to process before quitting and relaunching
Illustrator is:
Z Windows 500 files
Z Mac OS 1000 files
For more information on quitting and relaunching Illustrator, see “
Illustrator” on page 26 and “Quitting Illustrator” on page 27.
Launching and activating
X The “An Illustrator error occurred: 1346458189 (“PARM”)” alert may be popped when badly written
scripts are repeatedly run in Illustrator from the ESTK.
Scripters need to be very careful about variable initialization and namespace conflict when pushing a
batch of Illustrator scripts repeatedly for execution in Illustrator via the ESTK in one Illustrator session.
Each script run is executed within the same persistent ExtendScript engine within Illustrator.
CHAPTER 1: Introduction Known issues 17
The ESTK debugger uses BridgeTalk to communicate with Illustrator. A single global, persistent,
ExtendScript engine inside Illustrator handles all BridgeTalk communications. The net effect is that the
state of the ExtendScript engine is cumulative to all scripts that ran previously. Issues with script code
that may cause this problem are:
Z Reading uninitialized variables.
Z Global namespace conflicts, such as when two globals from different scripts are clobbering each
other.
X If you create more than one art object in AppleScript and assign each one to a variable, all the
variables are set to the last item. This means that the previously created items are not accessible.
2
The Illustrator Scripting Object Model
A good understanding of the Illustrator object model will improve your scripting abilities. The following
figure shows the containment hierarchy of the object model, starting with the
that the
contain additional nested objects.
layer and group item classes can contain nested objects of the same class which can, in turn,
application object. Note
In addition to this application-specific object model, JavaScript provides certain utility objects, such as the
File and Folder objects, which give you operating-system-independent access to the file system. For
details, see JavaScript Tools Guide.
18
CHAPTER 2: The Illustrator Scripting Object Model Object-naming conventions 19
Object-naming conventions
There is one object model for the Illustrator scripting interface, but actual object names vary slightly in the
different scripting languages:
X AppleScript names are lower case, and individual words are separated by a space; for example:
graphic style
X
VBScript names are capitalized, and additional words in the name are indicated by uppercase initial
letters; for example:
GraphicStyle
JavaScript names begin with lowercase letters, and additional words in the name are indicated by
X
uppercase initial letters; for example:
graphicStyle
This chapter uses generic object and property names, but you can easily apply these conventions to
determine the corresponding language-specific names.
Throughout this document, names of properties, methods, and object are in a
Top-level (containing) objects
Use these objects to access global information about the Illustrator application or an individual document.
Application
The properties of the application object give your script access to global values, such as:
X User preferences, which a user sets interactively in the Illustrator application by using the
Preferences dialog (Edit > Preferences).
X System information like installed fonts (the text fonts property) and printers (the printer list
property).
Also, there are properties that provide application-specific information and higher-level information about
any open documents:
X Application information like the installation path, version, and whether Illustrator is visible.
X The current active document; that is, the art canvas that is displayed and accepting user input.
X All open documents.
monospaced font.
application object’s methods or commands allow your script to perform application-wide actions;
The
for example:
X Open files
X Undo and redo transactions
X Quit Illustrator
CHAPTER 2: The Illustrator Scripting Object Model The artwork tree 20
Document
The document object, which your scripts can create or access through the application object, represents
an art canvas or loaded Illustrator file. The
content; for example:
X The current selection, or art objects that the user selected in the document
X All contained art objects, called page items, that make up the artwork tree
X Art objects of particular types, like symbols and text frames
X All layers and the currently active layer
Document properties also tell you about the state of the document itself; for example:
X User settings for the document, such as ruler units
X Whether the document was saved since the last alteration of content
X The path of the associated file
document object’s methods allow your scripts to act on the document; for example:
The
document object’s properties give you access to the document’s
X Save to an Illustrator file or save as the various supported file formats
X Activate or close a document
X Print the document. Your scripts can select a printer by referencing a print options object, or they
can reference available printers through the application object’s
Layer
The layer object provides access to the contents, or artwork tree, of a specific layer. You access the layer
object through the
the layer, such as:
X Whether the layer is visible or locked.
X The layer’s opacity (overall transparency) and z order position (position in the stacking order).
X Art-creation preferences for the layer, like artwork knockout and blending mode.
The artwork tree
The content of an Illustrator document is called the artwork tree. Artwork is represented by the following
objects:
printer list property.
document object. The layer object properties provide access to, or information about,
X compound path item
X graph item
X group item
X legacy text item
CHAPTER 2: The Illustrator Scripting Object Model The artwork tree 21
X mesh
X non native item
X path item
X placed item
X plugin item
X raster item
X symbol item (see “Dynamic objects” on page 25)
X text frame
Your scripts can access and manipulate art objects through collections in the
item
document and layer objects.
There are two types of art-object collections:
X Collection objects that correspond to each individual artwork object type, such as the graph items
object or the
X The page items object, which includes art objects of all types.
Also, you can use the
You can create new art objects using the
collection object. For example, to create a new
mesh items object.
group item object to reference a grouped set of art items.
make command (AppleScript) or add method of an artwork item
path item object:
AppleScript set myPathItem to make new path item in current document
JavaScript var myPathItem = activeDocument.pathItems.add();
VBScript Set myPathItem = appRef.ActiveDocument.PathItems.Add()
The following artwork collections do not allow the creation of new objects using the make command or
add method:
X graph items object
X mesh items object
X plugin items object
X legacy text items object
For details on creating objects of these types, see the Adobe Illustrator CS5 Scripting Reference for your
language.
Art styles
Your script can apply a graphic style to artwork using the graphic style object. To apply a graphic style,
use the
style object.
graphic styles property of the document object to access the apply to method of the graphic
Similarly, the
through the
brush object allows you to specify the brush to apply to artwork. You access any brush
brushes collection object, which is a property of the document object.
Loading...