Macromedia Illustrator - CS4 Scripting Guide

ADOBE® ILLUSTRATOR® CS4

ADOBE ILLUSTRATOR CS4

SCRIPTING GUIDE

Adobe Illustrator CS4 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

Script support in Adobe Illustrator CS4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

ExtendScript features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

ExtendScript tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Script file extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Viewing sample scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Viewing the object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Viewing the JavaScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Viewing the AppleScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Viewing the VBScript object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Executing scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Installing scripts in the Scripts menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Executing scripts from the Other Scripts menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Startup scripts (.jsx scripts only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Changes since CS3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Known issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

2 The Illustrator Scripting Object Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Object-naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Top-level (containing) objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

The artwork tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Art styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Color objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Text objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Objects that represent text content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Text styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Dynamic objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Contents 4

3 Scripting Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Launching and quitting Illustrator from a script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Launching and activating Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Quitting Illustrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Working with objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Getting the frontmost document or layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Collection objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Notes on renaming objects stored in the application’s panels . . . . . . . . . . . . . . . . . . . . . . . . 28

Measurement units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Em space units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Page-item positioning and dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Art item bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

User-interaction levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Printing Illustrator documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

4 Scripting with AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Obtaining objects from documents and layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5 Scripting with JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Working with methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Accessing and referencing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Referencing the application object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Accessing objects in collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Contents 5

Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6 Scripting with VBScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

For more information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Accessing and referencing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Obtaining objects from collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

Working with text frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Threaded frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Creating paths and shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

Shapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Working with enumeration values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Introduction

This guide describes the scripting interface to Adobe® Illustrator® CS4.

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:

➤ 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.

➤ 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.

➤ A script can execute an action, but actions cannot execute scripts.

CHAPTER 1: Introduction Script support in Adobe Illustrator CS4 7

Script support in Adobe Illustrator CS4

Illustrator scripting supports VBScript and JavaScript scripts for Windows, and AppleScript and JavaScript scripts for Mac OS.

NOTE: Also, Adobe scripting-enabled applications, including Illustrator, support ExtendScript, Adobe’s extended implementation of ECMA JavaScript. ExtendScript files are distinguished by the Giving your JavaScript files a tools.

ExtendScript features

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.

The ESTK includes an Object Model Viewer that contains complete documentation of the methods and properties of JavaScript objects.

.jsx extension allows you to take advantage of ExtendScript features and

.jsx extension.

For information on accessing the ESTK and the Object Model Viewer, see “

model” on page 8.

ExtendScript tools

ExtendScript also provides various tools and utilities, including the following:

➤ A localization utility

➤ Tools that allow you to combine scripts and direct them to particular applications

➤ Platform-independent file and folder representation

➤ Tools for building user interfaces to your scripts

➤ A messaging framework that allows you to send and receive scripts and data among

scripting-enabled Adobe applications

For details of these and other features, see JavaScript Tools Guide.

Script file extensions

For a file to be recognized by Adobe Illustrator CS4 as a valid script file, the file must have the correct file name extension:

Viewing the JavaScript object

Script type File type Extension Platforms

AppleScript compiled script

OSAS file

JavaScript ExtendScript

VBScript text

text

.scpt

(none)

.js .jsx

.vbs

Mac OS

Windows Mac OS

Windows

CHAPTER 1: Introduction Viewing sample scripts 8

Viewing sample scripts

Adobe provides sample scripts for many objects, properties, and methods in the Illustrator CS4 DOM. You can view script samples in two locations:

➤ In the /Scripting/Sample Scripts folder in your Illustrator CS4 installation directory

➤ In the Adobe Illustrator CS4 scripting reference for your scripting language, located in the

/Scripting/Documentation folder in your Illustrator CS4 installation directory

Viewing the object model

Each of the supported scripting languages provides a facility for viewing the scripting objects defined by Illustrator, with reference details.

Viewing the JavaScript object model

To view the Java S cript object model for Illustrator, follow these steps:

1. Start the ESTK.

In a default Adobe installation, the ESTK is in the following location:

➣ Windows:

system drive\Program Files\Adobe\Adobe Utilities\ExtendScript Toolkit CS4

➣ Mac OS:

system drive:Applications:Utilities:Adobe Utilities:ExtendScript Toolkit CS4

2. In the ESTK, choose Help > Object Model Viewer.

3. In the Object Model Viewer window, select Adobe Illustrator CS4 Type Library from the Browser drop-down list.

Several extended sample scripts are available in the CS4 installation directory.

You also can view script samples and information about individual classes, objects, properties, methods, and parameters in Adobe Illustrator CS4 Scripting Reference: JavaScript, located in the

/Scripting/Documentation folder in your Illustrator CS4 installation directory.

/Scripting/Sample Scripts folder in your Illustrator

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

Editor

CD.

. If you cannot find the Script Editor application, you must reinstall it from your Mac OS system

CHAPTER 1: Introduction Executing scripts 9

2. Choose File > Open Dictionary. Script Editor displays an Open Dictionary dialog.

3. In the Open Dictionary dialog, find and select Adobe Illustrator CS4, 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.

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 CS4 Scripting Reference: AppleScript, located in the

:Scripting:Documentation folder in your Illustrator CS4 installation directory.

:Scripting:Sample Scripts folder in your Illustrator CS4

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 CS4 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.

/Scripting/Sample Scripts folder in your Illustrator CS4

You also can view script samples and information about individual classes, objects, properties, methods, and parameters in Adobe Illustrator CS4 Scripting Reference: VBScript, located in the

/Scripting/Documentation folder in your Illustrator CS4 installation directory.

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 10.

You also can have JavaScript scripts with a application. For information, see “

Installing scripts in the

Executing

.jsx extension start automatically when you launch the

Startup scripts (.jsx scripts only)” on page 10.

CHAPTER 1: Introduction Executing scripts 10

Installing scripts in the Scripts menu

To include a script in the Scripts menu (File > Scripts), save the script in the Scripts folder, located in the

/Illustrator CS4/Presets folder in your Illustrator CS4 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.

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

Script support in Adobe Illustrator CS4” 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:

➤ An application-specific startup scripts folder, which contains scripts for Illustrator CS4

➤ A general startup scripts folder, which contains scripts that run automatically when you start any

Creative Suite 4 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 CS4 is installed to its default location, you would create the

Startup Scripts folder at the following location:

➤ Windows: C:\Program Files\Adobe\Adobe Illustrator CS4\Startup Scripts\

➤ Mac OS: /Applications/Adobe Illustrator CS4/Startup Scripts/

JavaScript scripts with a

➤ The application is launched.

➤ Any JavaScript file is selected from the Scripts menu (File > Scripts).

.jsx extension placed in the Startup Scripts folder run automatically when:

CHAPTER 1: Introduction Changes since CS3 11

General startup scripts folder

The general startup scripts folder contains scripts that run automatically when you start any Creative Suite 4 application. You create the folder in the following location:

➤ Windows: Program Files/Common Files/Adobe/Startup Scripts CS4/Illustrator

➤ Mac OS: :Library:Application Support:Adobe:Startup Scripts CS4:Illustrator

If a script in the general startup folder is meant to be executed only by Illustrator, the script must include the ExtendScript #target directive (#target illustrator) or code like the following:

if( BridgeTalk.appName == "illustrator" ) {

//continue executing script

}

For details, see JavaScript Tools Guide.

Changes since CS3

This section lists changes made to the scripting object model to support features in Illustrator CS4.

➤ A new type, DocumentArtboardLayout, sets the layout of artboards in a document. It is used by the

DocumentPreset class and the Add method in the Document class. Possible layouts are GridByRow, GridByCol, Row, Column, RLGridByRow, RLGridByCol, and RLRow; for example:

➣ AppleScript — artboardLayout: grid by row

➣ JavaScript — DocumentArtboardLayout.GridByRow

➣ VBScript — AiDocumentArtboardLayout.aiGridByRow

➤ Five new properties in the Add method of the Documents collection — NumArtboards,

ArtboardLayout, ArtboardSpacing, ArtboardRowsOrCols, and MaxCanvasSizeEnabled — support

the new, multiple-artboard feature.

➤ Five new properties in the DocumentPreset class — NumArtboards, ArtboardLayout,

ArtboardSpacing, ArtboardRowsOrCols, and MaxCanvasSizeEnabled — support the new

multiple-artboard feature.

➤ Two new properties — ArtboardRange and SaveMultipleArtboards — support the new

multiple-artboards feature. They apply to several classes:

ExportOptionsPhotoshop, EPSSaveOptions, MXGSaveOptions, and PDFSaveOptions

ArtboardRange only).

(

➤ A new class, NonNativeItem, represents a non-native item in an Illustrator document. This is another

subclass of

PageItem. Its parent can be a Document, Group, or Layer.

ExportOptionsFlash,

➣ AppleScript — non native item

➣ JavaScript — nonNativeItem

➣ VBScript — NonNativeItem

CHAPTER 1: Introduction Changes since CS3 12

➤

A new collection, NonNativeItems, contains a collection of NonNativeItem objects.

➣ AppleScript — non native items of document 1

JavaScript — app.activeDocument.nonNativeItems

➣

➣ VBScript — App.ActiveDocument.NonNativeItems

➤ A new FXG file format supports designer-developer workflow, by allowing an Illustrator document to

be saved as an FXG file containing XML-style descriptions of Illustrator graphical items, which can then be used in other FXG/XML-based applications.

➣ AppleScript — fxg

➣ JavaScript — DocumentType.FXG

➣ VBScript — AiDocumentType.aiFXG

➤ Two new PDFX standards were added, PDFX32002 and PDFX42007.

➤ A new type, FXGVersion, for setting the FXG file format version. There is only one option,

FXG version 1.0.

➣ AppleScript — version: version 1.0

➣ JavaScript — FXGVersion.VERSION1.0

➣ VBScript — AiFXGVersion.aiVersion1.0

➤ A new type, FiltersPreservePolicy, which defines whether to preserve appearance and editability

of filters when saving to FXG. Available options are

KeepFiltersEditable.

➣ AppleScript — filters policy: keep filters editable

➣ JavaScript — FiltersPreservePolicy.KEEPFILTERSEDITABLE

➣ VBScript — AiFiltersPreservePolicy.aiKeepFiltersEditable

➤ A new type, GradientsPreservePolicy, which defines whether to preserve appearance and

editability of gradients when saving to FXG. Available options are

KeepGradientsEditable.

➣ AppleScript — gradients policy: keep gradients editable

➣ JavaScript — GradientsPreservePolicy.KEEPGRADIENTSEDITABLE

➣ VBScript — AiGradientsPreservePolicy.aiKeepGradientsEditable

➤ A new type, TextPreservePolicy, which defines whether to preserve appearance and editability of

text when saving to FXG. Available options are

KeepTextEditable.

ExpandFilters, RasterizeFilters, and

RasterizeGradients and

OutlineText, RasterizeText, and

➣ AppleScript — text policy: keep text editable

➣ JavaScript — TextPreservePolicy.KEEPTEXTEDITABLE

➣ VBScript — AiTextPreservePolicy.aiKeepTextEditable

CHAPTER 1: Introduction Changes since CS3 13

➤

A new AutoKernType, MetricsRomanOnly, specifies metrics-Roman-only kerning.

➣ AppleScript — character: MetricsRomanOnly, character style: MetricsRomanOnly,

line: MetricsRomanOnly, paragraph: MetricsRomanOnly, paragraph style: MetricsRomanOnly, word: MetricsRomanOnly

➣

JavaScript — AutoKernType.METRICSROMANONLY

➣ VBScript — AiAutoKernType.aiMetricsRomanOnly

➤ A new FlashExportStyle, ArtBoardsToFiles, enables each artboard in a document to be exported

to a separate SWF file.

➣ AppleScript — export style: Artboards to Files

➣ JavaScript — FlashExportStyle.ARTBOARDSTOFILES

➣ VBScript — AiFlashExportStyle.aiArtboardsToFiles

➤ The CropBounds PrintingBounds constant has become obsolete, with the modification of artboards

to support the new, multiple-artboard feature.

➤ Support for JIS90 and JIS04 glyph encoding/forms was added to AlternateGlyphsForm; for example:

➣ AppleScript — alternate glyphs: jis90

➣ JavaScript — AlternateGlyphsForm.JIS90

➣ VBScript — AiAlternateGlyphsForm.aiJIS90Form

➤ New properties were added to the Application class: build number and locale; for example:

➣ AppleScript — build number of application

➣ JavaScript — app.buildNumber

➣ VBScript — App.BuildNumber

➤ A new property in the Document class, RasterEffectSettings, contains a document’s raster effect

settings.

➣ AppleScript — raster effect settings of document 1

➣ JavaScript — app.activeDocument.rasterEffectSettings

➣ VBScript — App.ActiveDocument.RasterEffectSettings

➤ A new method was added to the Application class, ConvertSampleColors, which converts a color

from one color space to another.

➣ AppleScript — Set cmykColor to convert sample color source color space RGB source color

rgbColor destination color space CMYK color conversion purpose default purpose

➣ JavaScript — var cmykColor = app.convertSampleColor(ImageColorSpace.RGB,

new Array(93, 32, 10), ImageColorSpace.CMYK, ColorConvertPurpose.defaultpurpose);

➣ VBScript — cmykColor = appRef.ConvertSampleColor(2, Array(93, 32, 10), 3, 0)

CHAPTER 1: Introduction Changes since CS3 14

➤

Two new methods were added to the Document class. WindowCapture captures the current document to a TIFF image.

➣ AppleScript — capture document 1, rasterize document 1

JavaScript — app.activeDocument.windowCapture, app.activeDocument.rasterize

➣

VBScript — App.ActiveDocument.WindowCapture, App.ActiveDocument.Rasterize

A new method in the Swatches collection, GetSelected, returns a SwatchList of Swatch objects

➤

Rasterize rasterizes the source art within a specified clip bounds.

currently selected.

➣ AppleScript — get selected swatches of document 1

➣ JavaScript — app.activeDocument.swatches.getSelected

➣ VBScript — App.ActiveDocument.Swatches.GetSelected

➤ A new class, SwatchGroup, contains a group of Swatch objects. It has two methods: GetAllSwatches

AddSwatch.

and

➣ AppleScript — swatch group 1 of document 1

➣ JavaScript — app.activeDocument.swatchGroups[0]

➣ VBScript — App.ActiveDocument.SwatchGroups(1)

➤ A new collection, SwatchGroups, contains all SwatchGroup objects in a document. It has two

methods:

➣ AppleScript — swatch groups in document 1

➣ JavaScript — app.activeDocument.swatchGroups

➣ VBScript — App.ActiveDocument.SwatchGroups

➤ A new type, SwatchList, defines a collection of Swatch objects. It is used by the SwatchGroup object

and

➤ A new property in the GradientStop class, opacity, allows each stop to define its own degree of

Remove and Add.

Swatches collection.

transparency. Alpha blending occurs between stops.

➣ AppleScript — stop opacity of gradient stop

➣ JavaScript — gradientStop.opacity

➣ VBScript — GradientStop.Opacity

➤ A new property in the OpenOptionsAutoCAD class, MergeLayers, defines whether the layers in the

AutoCAD file being opened should be merged into a single layer in the Illustrator document.

➣ AppleScript — merge layers: true

➣ JavaScript — mergeLayers = true

➣ VBScript — MergeLayers = true

CHAPTER 1: Introduction Changes since CS3 15

➤

A new class, Artboard, defines an artboard object or artboard in a CS4 document. It has the following properties:

ShowScreenEdge.

and

➣ JavaScript — app.activeDocument.artboards[0]

➣ AppleScript — artboard 1 of document 1

➣ VBScript — App.ActiveDocument.Artboards(1)

➤ A new collection, Artboards, contains all Artboard objects in a document. It has the following

methods:

➣ AppleScript — artboards of document 1

➣ JavaScript — app.activeDocument.artboards

➣ VBScript — App.ActiveDocument.Artboards

➤ Two new properties in the PrintJobOptions class, PrintAllArtboards and ArtboardRange,

ArtboardRect, RulerPAR, ShowRulers, ShowCenter, ShowCrossHairs, ShowSafeAreas,

Remove, Add, GetActiveArtboardIndex, and SetActiveArtboardIndex.

support printing of multiple artboards.

➤ A new type, RasterizationColorModel, enables the color model to be specified as default,

grayscale, or bitmap; for example:

➣ AppleScript — color model: grayscale rasterization

➣ JavaScript — RasterizationColorModel.GRAYSCALE

➣ VBScript — AiRasterizationColorModel.aiGrayscale

➤ A new type, AntiAliasingMethod, controls the type of rasterization method used in the rasterization:

none, art optimized, and type optimized; for example:

➣ AppleScript — antialiasing method: art optimized

➣ JavaScript — AntiAliasingMethod.ARTOPTIMIZED

➣ VBScript — AiAntiAliasingMethod.aiArtOptimized

➤ A new class, RasterEffectOptions, specifies a document’s raster-effect settings. Its properties are

ColorModel, Resolution, Transparency, AntiAliasing, ClippingMask, ConvertSpotColors, and Padding.

➣ AppleScript — raster effect settings of document 1

➣

JavaScript — app.activeDocument.rasterEffectSettings

➣ VBScript — App.ActiveDocument.RasterEffectSettings

➤ A new class, RasterizeOptions, specifies options that may be used when rasterizing artwork. Its

properties are

ConvertSpotColors, ConvertTextToOutlines, IncludeLayers, BackgroundBlack, and Padding.

ColorModel, Resolution, Transparency, AntiAliasing, ClippingMask,

➣ AppleScript — rasterize document 1 uses rasterize options

➣ JavaScript — app.activeDocument.rasterize uses rasterizeOptions

➣ VBScript — App.ActiveDocument.Rasterize uses RasterizeOptions

CHAPTER 1: Introduction Known issues 16

Known issues

➤ 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:

➣ Windows 500 files

➣ Mac OS 1000 files

For more information on quitting and relaunching Illustrator, see “

Launching and activating

Illustrator” on page 25 and “Quitting Illustrator” on page 26.

➤ 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.

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:

➣ Reading uninitialized variables.

➣ Global namespace conflicts, such as when two globals from different scripts are clobbering each

other.

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.

CHAPTER 2: The Illustrator Scripting Object Model Object-naming conventions 18

Object-naming conventions

There is one object model for the Illustrator scripting interface, but actual object names vary slightly in the different scripting languages:

➤ AppleScript names are lower case, and individual words are separated by a space; for example:

graphic style

➤

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 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:

➤ User preferences, which a user sets interactively in the Illustrator application by using the

Preferences dialog (Edit > Preferences).

➤ 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:

➤ Application information like the installation path, version, and whether Illustrator is visible.

➤ The current active document; that is, the art canvas that is displayed and accepting user input.

➤ All open documents.

monospaced font.

The

application object’s methods or commands allow your script to perform application-wide actions;

for example:

➤ Open files

➤ Undo and redo transactions

➤ Quit Illustrator

+ 39 hidden pages