Download - Illustrator CS2 JavaScript Scripting Reference · · 2018-04-28AdobeÆ Illustrator ® CS2 JavaScript ... Application properties ... activeDocument

bbc

Adobe® Ill

ustr

ator

® cs2

JavaScript Reference

© 2005 Adobe Systems Incorporated. All rights reserved.

AdobeÆ Illustrator® CS2 JavaScript Reference for Windows® and Mac OS®.

NOTICE: All information contained herein is the property of Adobe Systems Incorporated. No part of this publication (whether in hardcopy or electronic form) may be reproduced or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Adobe Systems Incorporated. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license.

This publication and the information herein is furnished AS IS, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies, makes no warranty of any kind (express, implied, or statutory) with respect to this publication, and expressly disclaims any and all warranties of merchantability, fitness for particular purposes, and noninfringement of third party rights.

Any references to company names in sample templates are for demonstration purposes only and are not intended to refer to any actual organization.

Adobe, the Adobe logo, Acrobat, and Illustrator are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries.

Apple, Mac, Macintosh, and Mac OS are trademarks of Apple Computer, Inc., registered in the United States and other countries. Microsoft, and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and other countries. JavaScript and all Java-related marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group.

All other trademarks are the property of their respective owners.

If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected under copyright law even if it is not distributed with software that includes an end user license agreement.

The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or inaccuracies that may appear in the informational content contained in this guide.

Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

Contents

1 Introduction ............................................................................................................................... 47What is scripting? .........................................................................................................................................................................47

Why use scripting?.................................................................................................................................................................48What about actions? .............................................................................................................................................................48

Script Support in Adobe Illustrator CS2 ...............................................................................................................................49JavaScript support .................................................................................................................................................................49Executing scripts ....................................................................................................................................................................49

Installing scripts ...............................................................................................................................................................49Executing other scripts ..................................................................................................................................................50

Startup scripts .........................................................................................................................................................................50Changes Since Earlier Versions................................................................................................................................................50

2 Scripting Basics .......................................................................................................................... 52Object model concepts..............................................................................................................................................................52

Object classes and containers ...........................................................................................................................................53Object inheritance .................................................................................................................................................................53Object elements or collections .........................................................................................................................................53Object references...................................................................................................................................................................53

Scripting concepts .......................................................................................................................................................................54Comments ................................................................................................................................................................................54Long script lines......................................................................................................................................................................54Case sensitivity........................................................................................................................................................................54Value types ...............................................................................................................................................................................54Variables ....................................................................................................................................................................................55

Declaring variables and assigning values ...............................................................................................................55Variable naming ...............................................................................................................................................................56

Operators ..................................................................................................................................................................................56Functions...................................................................................................................................................................................57Conditional statements .......................................................................................................................................................57Control structures ..................................................................................................................................................................57Including Other Script Files ................................................................................................................................................58

Testing and troubleshooting ...................................................................................................................................................58About error handling............................................................................................................................................................59

JavaScript Resources ...................................................................................................................................................................59

3 Scripting Illustrator ................................................................................................................... 60The Illustrator object model .....................................................................................................................................................60

Referencing and Creating Objects in JavaScript.........................................................................................................61Working with the Selection Object .................................................................................................................................62Working with paths ...............................................................................................................................................................62Working with color ................................................................................................................................................................63Working with symbols and symbol items.....................................................................................................................63

Working with Methods...............................................................................................................................................................63Working with Text and Printing ..............................................................................................................................................64

Content of a Text Range ......................................................................................................................................................65Character Style, Character Attributes, Local Character Attributes .......................................................................65

3

Adobe Illustrator CS2JavaScript Scripting Reference 4

Printing Illustrator Documents..........................................................................................................................................65Measurement units......................................................................................................................................................................66

Em Space Units .......................................................................................................................................................................67Page item positioning and dimensions .........................................................................................................................67

4 Using File and Folder Objects ................................................................................................... 69Overview .........................................................................................................................................................................................69Specifying Paths............................................................................................................................................................................69

Absolute and relative path names...................................................................................................................................69Character interpretation in paths.....................................................................................................................................70The home directory...............................................................................................................................................................70Volume and drive names ....................................................................................................................................................71

Mac OS volumes...............................................................................................................................................................71Windows drives ................................................................................................................................................................71

Aliases.........................................................................................................................................................................................72Portability issues.....................................................................................................................................................................72

Unicode I/O ....................................................................................................................................................................................72File Error Handling ......................................................................................................................................................................73

5 JavaScript Object Reference ..................................................................................................... 74Application .....................................................................................................................................................................................75

Application properties .........................................................................................................................................................75activeDocument.....................................................................................................................................................................75browserAvailable ...................................................................................................................................................................75documents ...............................................................................................................................................................................75flattenerPresetsList................................................................................................................................................................75freeMemory..............................................................................................................................................................................75name...........................................................................................................................................................................................75path .............................................................................................................................................................................................75PDFPresetsList .........................................................................................................................................................................75PPDFileList ................................................................................................................................................................................75preferences...............................................................................................................................................................................75printerList..................................................................................................................................................................................75printPresetsList .......................................................................................................................................................................75scriptingVersion......................................................................................................................................................................75selection ....................................................................................................................................................................................75textFonts ...................................................................................................................................................................................75tracingPresetList.....................................................................................................................................................................75typename..................................................................................................................................................................................75userInteractionLevel .............................................................................................................................................................75version........................................................................................................................................................................................76visible..........................................................................................................................................................................................76Application methods ............................................................................................................................................................76beep............................................................................................................................................................................................76concatenateMatrix.................................................................................................................................................................76concatenateRotationMatrix ...............................................................................................................................................76concatenateScaleMatrix ......................................................................................................................................................76concatenateTranslationMatrix ..........................................................................................................................................76getIdentityMatrix ...................................................................................................................................................................76getRotationMatrix..................................................................................................................................................................76getScaleMatrix ........................................................................................................................................................................76getTranslationMatrix ............................................................................................................................................................76


invertMatrix..............................................................................................................................................................................76isEqualMatrix ...........................................................................................................................................................................76isSingularMatrix......................................................................................................................................................................76open............................................................................................................................................................................................77quit ..............................................................................................................................................................................................77redraw ........................................................................................................................................................................................77showPresets .............................................................................................................................................................................77translatePlaceholderText ....................................................................................................................................................77

Brush .................................................................................................................................................................................................79Brush properties .....................................................................................................................................................................79name...........................................................................................................................................................................................79parent .........................................................................................................................................................................................79typename..................................................................................................................................................................................79Brush methods........................................................................................................................................................................79applyTo ......................................................................................................................................................................................79

Brushes.............................................................................................................................................................................................80Brushes properties.................................................................................................................................................................80length .........................................................................................................................................................................................80parent .........................................................................................................................................................................................80typename..................................................................................................................................................................................80Brushes methods....................................................................................................................................................................80getByName...............................................................................................................................................................................80index ...........................................................................................................................................................................................80

CharacterAttributes .....................................................................................................................................................................81CharacterAttributes properties.........................................................................................................................................81akiLeft .........................................................................................................................................................................................81akiRight......................................................................................................................................................................................81alignment..................................................................................................................................................................................81alternateGlyphs ......................................................................................................................................................................81autoLeading.............................................................................................................................................................................81baselineDirection...................................................................................................................................................................81baselinePosition .....................................................................................................................................................................81baselineShift ............................................................................................................................................................................81capitalization ...........................................................................................................................................................................81connectionForms...................................................................................................................................................................81contextualLigature ................................................................................................................................................................81discretionaryLigature ...........................................................................................................................................................81figureStyle.................................................................................................................................................................................81fillColor.......................................................................................................................................................................................81fractions.....................................................................................................................................................................................82horizontalScale .......................................................................................................................................................................82italics...........................................................................................................................................................................................82kerningMethod.......................................................................................................................................................................82language ...................................................................................................................................................................................82leading .......................................................................................................................................................................................82ligature.......................................................................................................................................................................................82noBreak......................................................................................................................................................................................82openTypePosition..................................................................................................................................................................82ordinals ......................................................................................................................................................................................82ornaments ................................................................................................................................................................................82overprintFill ..............................................................................................................................................................................82


overprintStroke.......................................................................................................................................................................82parent .........................................................................................................................................................................................82proportionalMetrics ..............................................................................................................................................................82rotation ......................................................................................................................................................................................82size...............................................................................................................................................................................................82strikeThrough ..........................................................................................................................................................................82strokeColor ...............................................................................................................................................................................82strokeWeight ...........................................................................................................................................................................82stylisticAlternates...................................................................................................................................................................82swash..........................................................................................................................................................................................83tateChuYokoHorizontal .......................................................................................................................................................83tateChuYokoVertical .............................................................................................................................................................83textFont .....................................................................................................................................................................................83titling ..........................................................................................................................................................................................83tracking......................................................................................................................................................................................83Tsume.........................................................................................................................................................................................83typename..................................................................................................................................................................................83underline...................................................................................................................................................................................83verticalScale .............................................................................................................................................................................83wariChuCharactersAfterBreak ...........................................................................................................................................83wariChuCharactersBeforeBreak........................................................................................................................................83wariChuEnabled .....................................................................................................................................................................83wariChuJustification .............................................................................................................................................................83wariChuLineGap.....................................................................................................................................................................83wariChuLines ...........................................................................................................................................................................83wariChuScale ...........................................................................................................................................................................83

Characters .......................................................................................................................................................................................85Characters properties ...........................................................................................................................................................85length .........................................................................................................................................................................................85parent .........................................................................................................................................................................................85typename..................................................................................................................................................................................85Characters methods..............................................................................................................................................................85add...............................................................................................................................................................................................85addBefore .................................................................................................................................................................................85index ...........................................................................................................................................................................................85removeAll..................................................................................................................................................................................85

CharacterStyle ...............................................................................................................................................................................86CharacterStyle properties ...................................................................................................................................................86characterAttributes ...............................................................................................................................................................86name...........................................................................................................................................................................................86parent .........................................................................................................................................................................................86typename..................................................................................................................................................................................86CharacterStyle methods ......................................................................................................................................................86applyTo ......................................................................................................................................................................................86remove.......................................................................................................................................................................................86

CharacterStyles .............................................................................................................................................................................87CharacterStyles properties .................................................................................................................................................87length .........................................................................................................................................................................................87parent .........................................................................................................................................................................................87typename..................................................................................................................................................................................87CharacterStyles methods ....................................................................................................................................................87


add...............................................................................................................................................................................................87getByName...............................................................................................................................................................................87index ...........................................................................................................................................................................................87removeAll..................................................................................................................................................................................87

CMYKColor......................................................................................................................................................................................89CMYKColor properties..........................................................................................................................................................89black............................................................................................................................................................................................89cyan.............................................................................................................................................................................................89magenta ....................................................................................................................................................................................89typename..................................................................................................................................................................................89yellow .........................................................................................................................................................................................89

CompoundPathItem ...................................................................................................................................................................90CompoundPathItem properties .......................................................................................................................................90artworkKnockout ...................................................................................................................................................................90blendingMode ........................................................................................................................................................................90controlBounds.........................................................................................................................................................................90editable......................................................................................................................................................................................90geometricBounds ..................................................................................................................................................................90height .........................................................................................................................................................................................90hidden........................................................................................................................................................................................90isIsolated ...................................................................................................................................................................................90layer.............................................................................................................................................................................................90left................................................................................................................................................................................................90locked .........................................................................................................................................................................................90name...........................................................................................................................................................................................90opacity .......................................................................................................................................................................................90parent .........................................................................................................................................................................................90pathItems..................................................................................................................................................................................90position......................................................................................................................................................................................90selected......................................................................................................................................................................................91sliced...........................................................................................................................................................................................91tags..............................................................................................................................................................................................91top ...............................................................................................................................................................................................91typename..................................................................................................................................................................................91uRL...............................................................................................................................................................................................91visibilityVariable .....................................................................................................................................................................91visibleBounds ..........................................................................................................................................................................91width...........................................................................................................................................................................................91wrapInside ................................................................................................................................................................................91wrapOffset ................................................................................................................................................................................91wrapped ....................................................................................................................................................................................91zOrderPosition ........................................................................................................................................................................91CompoundPathItem methods..........................................................................................................................................91duplicate ...................................................................................................................................................................................91move...........................................................................................................................................................................................91remove.......................................................................................................................................................................................91resize...........................................................................................................................................................................................92rotate ..........................................................................................................................................................................................92transform...................................................................................................................................................................................92translate.....................................................................................................................................................................................92zOrder.........................................................................................................................................................................................92


CompoundPathItems .................................................................................................................................................................94CompoundPathItem methods..........................................................................................................................................94length .........................................................................................................................................................................................94parent .........................................................................................................................................................................................94typename..................................................................................................................................................................................94CompoundPathItem methods..........................................................................................................................................94add...............................................................................................................................................................................................94getByName...............................................................................................................................................................................94index ...........................................................................................................................................................................................94removeAll..................................................................................................................................................................................94

Dataset .............................................................................................................................................................................................95Dataset properties .................................................................................................................................................................95name...........................................................................................................................................................................................95parent .........................................................................................................................................................................................95typename..................................................................................................................................................................................95Dataset methods....................................................................................................................................................................95display ........................................................................................................................................................................................95remove.......................................................................................................................................................................................95update........................................................................................................................................................................................95

Datasets ...........................................................................................................................................................................................97Datasets properties ...............................................................................................................................................................97length .........................................................................................................................................................................................97parent .........................................................................................................................................................................................97typename..................................................................................................................................................................................97Datasets methods..................................................................................................................................................................97add...............................................................................................................................................................................................97getByName...............................................................................................................................................................................97index ...........................................................................................................................................................................................97removeAll..................................................................................................................................................................................97

Document .......................................................................................................................................................................................98Document properties ...........................................................................................................................................................98activeDataset ...........................................................................................................................................................................98activeLayer ...............................................................................................................................................................................98activeView.................................................................................................................................................................................98brushes ......................................................................................................................................................................................98characterStyles........................................................................................................................................................................98compoundPathItems............................................................................................................................................................98cropBox......................................................................................................................................................................................98cropStyle ...................................................................................................................................................................................98dataSets .....................................................................................................................................................................................98defaultFillColor .......................................................................................................................................................................98defaultFilled .............................................................................................................................................................................98defaultFillOverprint...............................................................................................................................................................98defaultStrokeCap ...................................................................................................................................................................98defaultStrokeColor ................................................................................................................................................................98defaultStroked ........................................................................................................................................................................98defaultStrokeDashes.............................................................................................................................................................99defaultStrokeDashOffset .....................................................................................................................................................99defaultStrokeJoin...................................................................................................................................................................99defaultStrokeMiterLimit ......................................................................................................................................................99defaultStrokeOverprint........................................................................................................................................................99


defaultStrokeWidth...............................................................................................................................................................99documentColorSpace...........................................................................................................................................................99fullName ....................................................................................................................................................................................99geometricBounds ..................................................................................................................................................................99gradients ...................................................................................................................................................................................99graphicStyles ...........................................................................................................................................................................99graphItems ...............................................................................................................................................................................99groupItems...............................................................................................................................................................................99height .........................................................................................................................................................................................99inkList .........................................................................................................................................................................................99kinsokuSet ................................................................................................................................................................................99layers........................................................................................................................................................................................ 100legacyTextItems................................................................................................................................................................... 100meshItems ............................................................................................................................................................................. 100mojikumiSet.......................................................................................................................................................................... 100name........................................................................................................................................................................................ 100outputResolution................................................................................................................................................................ 100pageItems .............................................................................................................................................................................. 100pageOrigin............................................................................................................................................................................. 100paragraphStyles................................................................................................................................................................... 100parent ...................................................................................................................................................................................... 100path .......................................................................................................................................................................................... 100pathItems............................................................................................................................................................................... 100patterns .................................................................................................................................................................................. 100placedItems........................................................................................................................................................................... 100pluginItems ........................................................................................................................................................................... 100printTiles................................................................................................................................................................................. 100rasterItems............................................................................................................................................................................. 100rulerOrigin ............................................................................................................................................................................. 100rulerUnits................................................................................................................................................................................ 101saved........................................................................................................................................................................................ 101selection ................................................................................................................................................................................. 101showPlacedImages............................................................................................................................................................. 101splitLongPaths ..................................................................................................................................................................... 101spots......................................................................................................................................................................................... 101stationery ............................................................................................................................................................................... 101stories ...................................................................................................................................................................................... 101swatches................................................................................................................................................................................. 101symbolItems ......................................................................................................................................................................... 101symbols................................................................................................................................................................................... 101tags........................................................................................................................................................................................... 101textFrames............................................................................................................................................................................. 101tileFullPages.......................................................................................................................................................................... 101typename............................................................................................................................................................................... 101useDefaultScreen................................................................................................................................................................ 101variables ................................................................................................................................................................................. 101variablesLocked................................................................................................................................................................... 102views ........................................................................................................................................................................................ 102visibleBounds ....................................................................................................................................................................... 102width........................................................................................................................................................................................ 102Document methods........................................................................................................................................................... 102


activate ................................................................................................................................................................................... 102close ......................................................................................................................................................................................... 102exportFile ............................................................................................................................................................................... 102exportPDFPreset ................................................................................................................................................................. 102exportPrintPreset ................................................................................................................................................................ 102exportVariables.................................................................................................................................................................... 102importCharacterStyles ...................................................................................................................................................... 102importParagraphStyles ..................................................................................................................................................... 102importPDFPreset ................................................................................................................................................................. 103importPrintPreset................................................................................................................................................................ 103importVariables ................................................................................................................................................................... 103print.......................................................................................................................................................................................... 103save .......................................................................................................................................................................................... 103saveAs ..................................................................................................................................................................................... 103

Documents .................................................................................................................................................................................. 104Documents properties ...................................................................................................................................................... 104length ...................................................................................................................................................................................... 104parent ...................................................................................................................................................................................... 104typename............................................................................................................................................................................... 104Documents methods......................................................................................................................................................... 104add............................................................................................................................................................................................ 104getByName............................................................................................................................................................................ 104index ........................................................................................................................................................................................ 104

EPSSaveOptions......................................................................................................................................................................... 105EPSSaveOptions properties............................................................................................................................................. 105cmykPostScript .................................................................................................................................................................... 105compatibility......................................................................................................................................................................... 105compatibleGradientPrinting........................................................................................................................................... 105embedAllFonts..................................................................................................................................................................... 105embedLinkedFiles............................................................................................................................................................... 105flattenOuput ......................................................................................................................................................................... 105includeDocumentThumbnails ....................................................................................................................................... 105overprint................................................................................................................................................................................. 105postScript............................................................................................................................................................................... 105preview ................................................................................................................................................................................... 105typename............................................................................................................................................................................... 105

ExportOptionsFlash .................................................................................................................................................................. 107ExportOptionsFlash properties...................................................................................................................................... 107artBoardClipping................................................................................................................................................................. 107backgroundColor ................................................................................................................................................................ 107backgroundLayers .............................................................................................................................................................. 107blendAnimation .................................................................................................................................................................. 107compressed........................................................................................................................................................................... 107convertTextToOutlines ..................................................................................................................................................... 107curveQuality.......................................................................................................................................................................... 107exportStyle ............................................................................................................................................................................ 107flattenOutput........................................................................................................................................................................ 107frameRate............................................................................................................................................................................... 107generateHTML ..................................................................................................................................................................... 107imageFormat ........................................................................................................................................................................ 107jpegMethod .......................................................................................................................................................................... 107


jpegQuality............................................................................................................................................................................ 107layerOrder .............................................................................................................................................................................. 107looping.................................................................................................................................................................................... 108readOnly................................................................................................................................................................................. 108replacing ................................................................................................................................................................................ 108resolution............................................................................................................................................................................... 108typename............................................................................................................................................................................... 108

ExportOptionsGIF...................................................................................................................................................................... 109ExportOptionsGIF properties.......................................................................................................................................... 109antiAliasing............................................................................................................................................................................ 109artBoardClipping................................................................................................................................................................. 109colorCount............................................................................................................................................................................. 109colorDither............................................................................................................................................................................. 109colorReduction..................................................................................................................................................................... 109ditherPercent........................................................................................................................................................................ 109horizontalScale .................................................................................................................................................................... 109infoLossPercent ................................................................................................................................................................... 109interlaced ............................................................................................................................................................................... 109matte ....................................................................................................................................................................................... 109matteColor............................................................................................................................................................................. 109saveAsHTML.......................................................................................................................................................................... 109transparency ......................................................................................................................................................................... 109typename............................................................................................................................................................................... 109verticalScale .......................................................................................................................................................................... 110webSnap ................................................................................................................................................................................ 110

ExportOptionsJPEG................................................................................................................................................................... 111ExportOptionsJPEG properties ...................................................................................................................................... 111antiAliasing............................................................................................................................................................................ 111artBoardClipping................................................................................................................................................................. 111blurAmount........................................................................................................................................................................... 111horizontalScale .................................................................................................................................................................... 111matte ....................................................................................................................................................................................... 111matteColor............................................................................................................................................................................. 111optimization.......................................................................................................................................................................... 111qualitySetting ....................................................................................................................................................................... 111saveAsHTML.......................................................................................................................................................................... 111typename............................................................................................................................................................................... 111verticalScale .......................................................................................................................................................................... 111

ExportOptionsPhotoshop ...................................................................................................................................................... 112ExportOptionsPhotoshop properties .......................................................................................................................... 112antiAliasing............................................................................................................................................................................ 112compatibility......................................................................................................................................................................... 112editableText .......................................................................................................................................................................... 112embedICCProfile ................................................................................................................................................................. 112imageColorSpace................................................................................................................................................................ 112maximumEditability........................................................................................................................................................... 112resolution............................................................................................................................................................................... 112typename............................................................................................................................................................................... 112warnings................................................................................................................................................................................. 112writeLayers ............................................................................................................................................................................ 112

ExportOptionsPNG8 ................................................................................................................................................................. 113


ExportOptionsPNG8 properties ..................................................................................................................................... 113antiAliasing............................................................................................................................................................................ 113artBoardClipping................................................................................................................................................................. 113colorCount............................................................................................................................................................................. 113colorDither............................................................................................................................................................................. 113colorReduction..................................................................................................................................................................... 113ditherPercent........................................................................................................................................................................ 113horizontalScale .................................................................................................................................................................... 113interlaced ............................................................................................................................................................................... 113matte ....................................................................................................................................................................................... 113matteColor............................................................................................................................................................................. 113saveAsHTML.......................................................................................................................................................................... 113transparency ......................................................................................................................................................................... 113typename............................................................................................................................................................................... 113verticalScale .......................................................................................................................................................................... 113webSnap ................................................................................................................................................................................ 113

ExportOptionsPNG24............................................................................................................................................................... 115ExportOptionsPNG24 properties .................................................................................................................................. 115antiAliasing............................................................................................................................................................................ 115artBoardClipping................................................................................................................................................................. 115horizontalScale .................................................................................................................................................................... 115matte ....................................................................................................................................................................................... 115matteColor............................................................................................................................................................................. 115saveAsHTML.......................................................................................................................................................................... 115transparency ......................................................................................................................................................................... 115typename............................................................................................................................................................................... 115verticalScale .......................................................................................................................................................................... 115

ExportOptionsSVG .................................................................................................................................................................... 116ExportOptionsSVG properties ........................................................................................................................................ 116compressed........................................................................................................................................................................... 116coordinatePrecision ........................................................................................................................................................... 116cssProperties......................................................................................................................................................................... 116documentEncoding ........................................................................................................................................................... 116DTD........................................................................................................................................................................................... 116embedRasterImages .......................................................................................................................................................... 116fontSubsetting ..................................................................................................................................................................... 116fontType ................................................................................................................................................................................. 116includeFileInfo ..................................................................................................................................................................... 116includeVariablesAndDatasets ........................................................................................................................................ 116optimizeForSVGViewer ..................................................................................................................................................... 116preserveEditability.............................................................................................................................................................. 116slices......................................................................................................................................................................................... 117sVGAutoKerning.................................................................................................................................................................. 117sVGTextOnPath.................................................................................................................................................................... 117typename............................................................................................................................................................................... 117

Gradient ........................................................................................................................................................................................ 118Gradient properties ............................................................................................................................................................ 118gradientStops....................................................................................................................................................................... 118name........................................................................................................................................................................................ 118parent ...................................................................................................................................................................................... 118type .......................................................................................................................................................................................... 118


typename............................................................................................................................................................................... 118Gradient methods............................................................................................................................................................... 118remove.................................................................................................................................................................................... 118

GradientColor ............................................................................................................................................................................. 120GradientColor properties ................................................................................................................................................. 120angle ........................................................................................................................................................................................ 120gradient .................................................................................................................................................................................. 120hiliteAngle ............................................................................................................................................................................. 120hiliteLength........................................................................................................................................................................... 120length ...................................................................................................................................................................................... 120matrix ...................................................................................................................................................................................... 120origin ....................................................................................................................................................................................... 120typename............................................................................................................................................................................... 120

Gradients ...................................................................................................................................................................................... 121Gradients properties .......................................................................................................................................................... 121length ...................................................................................................................................................................................... 121parent ...................................................................................................................................................................................... 121typename............................................................................................................................................................................... 121Gradients methods............................................................................................................................................................. 121add............................................................................................................................................................................................ 121getByName............................................................................................................................................................................ 121index ........................................................................................................................................................................................ 121removeAll............................................................................................................................................................................... 121

GradientStop............................................................................................................................................................................... 122GradientStop properties................................................................................................................................................... 122color ......................................................................................................................................................................................... 122midPoint................................................................................................................................................................................. 122parent ...................................................................................................................................................................................... 122rampPoint .............................................................................................................................................................................. 122typename............................................................................................................................................................................... 122GradientStop methods ..................................................................................................................................................... 122remove.................................................................................................................................................................................... 122

GradientStops............................................................................................................................................................................. 123GradientStops properties................................................................................................................................................. 123length ...................................................................................................................................................................................... 123parent ...................................................................................................................................................................................... 123typename............................................................................................................................................................................... 123GradientStops methods ................................................................................................................................................... 123add............................................................................................................................................................................................ 123index ........................................................................................................................................................................................ 123removeAll............................................................................................................................................................................... 123

GraphicStyle ................................................................................................................................................................................ 124GraphicStyle properties .................................................................................................................................................... 124name........................................................................................................................................................................................ 124parent ...................................................................................................................................................................................... 124typename............................................................................................................................................................................... 124GraphicStyle methods....................................................................................................................................................... 124applyTo ................................................................................................................................................................................... 124remove.................................................................................................................................................................................... 124

GraphicStyles .............................................................................................................................................................................. 125GraphicStyles properties .................................................................................................................................................. 125


length ...................................................................................................................................................................................... 125parent ...................................................................................................................................................................................... 125typename............................................................................................................................................................................... 125GraphicStyles methods..................................................................................................................................................... 125getByName............................................................................................................................................................................ 125index ........................................................................................................................................................................................ 125removeAll............................................................................................................................................................................... 125

GraphItem .................................................................................................................................................................................... 126GraphItem properties........................................................................................................................................................ 126artworkKnockout ................................................................................................................................................................ 126blendingMode ..................................................................................................................................................................... 126contentVariable ................................................................................................................................................................... 126controlBounds...................................................................................................................................................................... 126editable................................................................................................................................................................................... 126geometricBounds ............................................................................................................................................................... 126height ...................................................................................................................................................................................... 126hidden..................................................................................................................................................................................... 126isIsolated ................................................................................................................................................................................ 126layer.......................................................................................................................................................................................... 126left............................................................................................................................................................................................. 126locked ...................................................................................................................................................................................... 126name........................................................................................................................................................................................ 126opacity .................................................................................................................................................................................... 126parent ...................................................................................................................................................................................... 126position................................................................................................................................................................................... 126selected................................................................................................................................................................................... 126sliced........................................................................................................................................................................................ 126tags........................................................................................................................................................................................... 126top ............................................................................................................................................................................................ 126typename............................................................................................................................................................................... 126uRL............................................................................................................................................................................................ 127visibilityVariable .................................................................................................................................................................. 127visibleBounds ....................................................................................................................................................................... 127width........................................................................................................................................................................................ 127wrapInside ............................................................................................................................................................................. 127wrapOffset ............................................................................................................................................................................. 127wrapped ................................................................................................................................................................................. 127zOrderPosition ..................................................................................................................................................................... 127GraphItem methods........................................................................................................................................................... 127duplicate ................................................................................................................................................................................ 127move........................................................................................................................................................................................ 127remove.................................................................................................................................................................................... 127resize........................................................................................................................................................................................ 127rotate ....................................................................................................................................................................................... 128transform................................................................................................................................................................................ 128translate.................................................................................................................................................................................. 128zOrder...................................................................................................................................................................................... 128

GraphItems .................................................................................................................................................................................. 129GraphItems properties ...................................................................................................................................................... 129length ...................................................................................................................................................................................... 129parent ...................................................................................................................................................................................... 129


typename............................................................................................................................................................................... 129GraphItems methods......................................................................................................................................................... 129getByName............................................................................................................................................................................ 129index ........................................................................................................................................................................................ 129removeAll............................................................................................................................................................................... 129

GrayColor...................................................................................................................................................................................... 130GrayColor properties ......................................................................................................................................................... 130gray .......................................................................................................................................................................................... 130typename............................................................................................................................................................................... 130

GroupItem.................................................................................................................................................................................... 131GroupItem properties........................................................................................................................................................ 131artworkKnockout ................................................................................................................................................................ 131blendingMode ..................................................................................................................................................................... 131clipped .................................................................................................................................................................................... 131compoundPathItems......................................................................................................................................................... 131controlBounds...................................................................................................................................................................... 131editable................................................................................................................................................................................... 131geometricBounds ............................................................................................................................................................... 131graphItems ............................................................................................................................................................................ 131groupItems............................................................................................................................................................................ 131height ...................................................................................................................................................................................... 131hidden..................................................................................................................................................................................... 131isIsolated ................................................................................................................................................................................ 131layer.......................................................................................................................................................................................... 131left............................................................................................................................................................................................. 131legacyTextItems................................................................................................................................................................... 131locked ...................................................................................................................................................................................... 131meshItems ............................................................................................................................................................................. 131name........................................................................................................................................................................................ 131opacity .................................................................................................................................................................................... 131pageItems .............................................................................................................................................................................. 132parent ...................................................................................................................................................................................... 132pathItems............................................................................................................................................................................... 132placedItems........................................................................................................................................................................... 132pluginItems ........................................................................................................................................................................... 132position................................................................................................................................................................................... 132rasterItems............................................................................................................................................................................. 132selected................................................................................................................................................................................... 132sliced........................................................................................................................................................................................ 132symbolItems ......................................................................................................................................................................... 132tags........................................................................................................................................................................................... 132textFrames............................................................................................................................................................................. 132top ............................................................................................................................................................................................ 132typename............................................................................................................................................................................... 132uRL............................................................................................................................................................................................ 132visibilityVariable .................................................................................................................................................................. 132visibleBounds ....................................................................................................................................................................... 132width........................................................................................................................................................................................ 132wrapInside ............................................................................................................................................................................. 132wrapOffset ............................................................................................................................................................................. 132wrapped ................................................................................................................................................................................. 132


zOrderPosition ..................................................................................................................................................................... 132GroupItem methods .......................................................................................................................................................... 133duplicate ................................................................................................................................................................................ 133move........................................................................................................................................................................................ 133remove.................................................................................................................................................................................... 133resize........................................................................................................................................................................................ 133rotate ....................................................................................................................................................................................... 133transform................................................................................................................................................................................ 133translate.................................................................................................................................................................................. 133zOrder...................................................................................................................................................................................... 133

GroupItems.................................................................................................................................................................................. 135GroupItems properties...................................................................................................................................................... 135length ...................................................................................................................................................................................... 135parent ...................................................................................................................................................................................... 135typename............................................................................................................................................................................... 135GroupItems methods ........................................................................................................................................................ 135add............................................................................................................................................................................................ 135createFromFile ..................................................................................................................................................................... 135getByName............................................................................................................................................................................ 135index ........................................................................................................................................................................................ 135removeAll............................................................................................................................................................................... 135

IllustratorSaveOptions............................................................................................................................................................. 136IllustratorSaveOptions properties................................................................................................................................. 136compatibility......................................................................................................................................................................... 136compressed........................................................................................................................................................................... 136embedICCProfile ................................................................................................................................................................. 136embedLinkedFiles............................................................................................................................................................... 136flattenOutput........................................................................................................................................................................ 136fontSubsetThreshold ......................................................................................................................................................... 136overprint................................................................................................................................................................................. 136pdfCompatible..................................................................................................................................................................... 136typename............................................................................................................................................................................... 136

Ink.................................................................................................................................................................................................... 137Ink properties ....................................................................................................................................................................... 137inkInfo ..................................................................................................................................................................................... 137name........................................................................................................................................................................................ 137typename............................................................................................................................................................................... 137

InkInfo............................................................................................................................................................................................ 137InkInfo properties................................................................................................................................................................ 137angle ........................................................................................................................................................................................ 137customColor ......................................................................................................................................................................... 137density..................................................................................................................................................................................... 137dotShape................................................................................................................................................................................ 137frequency ............................................................................................................................................................................... 137kind........................................................................................................................................................................................... 137printingStatus....................................................................................................................................................................... 137trapping.................................................................................................................................................................................. 137trappingOrder ...................................................................................................................................................................... 137typename............................................................................................................................................................................... 137

InsertionPoint ............................................................................................................................................................................. 139InsertionPoints ........................................................................................................................................................................... 139


InsertionPoints properties ............................................................................................................................................... 139length ...................................................................................................................................................................................... 139parent ...................................................................................................................................................................................... 139typename............................................................................................................................................................................... 139InsertionPoints methods.................................................................................................................................................. 139index ........................................................................................................................................................................................ 139

LabColor ....................................................................................................................................................................................... 140LabColor properties ........................................................................................................................................................... 140a ................................................................................................................................................................................................. 140b................................................................................................................................................................................................. 140l .................................................................................................................................................................................................. 140typename............................................................................................................................................................................... 140

Layer............................................................................................................................................................................................... 141Layer properties................................................................................................................................................................... 141artworkKnockout ................................................................................................................................................................ 141blendingMode ..................................................................................................................................................................... 141color ......................................................................................................................................................................................... 141compoundPathItems......................................................................................................................................................... 141dimPlacedImages................................................................................................................................................................ 141graphItems ............................................................................................................................................................................ 141groupItems............................................................................................................................................................................ 141hasSelectedArtwork ........................................................................................................................................................... 141isIsolated ................................................................................................................................................................................ 141layers........................................................................................................................................................................................ 141legacyTextItems................................................................................................................................................................... 141locked ...................................................................................................................................................................................... 141meshItems ............................................................................................................................................................................. 141name........................................................................................................................................................................................ 141opacity .................................................................................................................................................................................... 141pageItems .............................................................................................................................................................................. 141parent ...................................................................................................................................................................................... 141pathItems............................................................................................................................................................................... 142placedItems........................................................................................................................................................................... 142pluginItems ........................................................................................................................................................................... 142preview ................................................................................................................................................................................... 142printable ................................................................................................................................................................................. 142rasterItems............................................................................................................................................................................. 142sliced........................................................................................................................................................................................ 142symbolItems ......................................................................................................................................................................... 142textFrames............................................................................................................................................................................. 142typename............................................................................................................................................................................... 142visible....................................................................................................................................................................................... 142zOrderPosition ..................................................................................................................................................................... 142Layer methods ..................................................................................................................................................................... 142move........................................................................................................................................................................................ 142remove.................................................................................................................................................................................... 142zOrder...................................................................................................................................................................................... 142

Layers............................................................................................................................................................................................. 144Layers properties................................................................................................................................................................. 144length ...................................................................................................................................................................................... 144parent ...................................................................................................................................................................................... 144


typename............................................................................................................................................................................... 144Layers methods.................................................................................................................................................................... 144add............................................................................................................................................................................................ 144getByName............................................................................................................................................................................ 144index ........................................................................................................................................................................................ 144removeAll............................................................................................................................................................................... 144

LegacyTextItem.......................................................................................................................................................................... 145LegacyTextItem properties ............................................................................................................................................. 145artworkKnockout ................................................................................................................................................................ 145blendingMode ..................................................................................................................................................................... 145controlBounds...................................................................................................................................................................... 145converted............................................................................................................................................................................... 145editable................................................................................................................................................................................... 145geometricBounds ............................................................................................................................................................... 145height ...................................................................................................................................................................................... 145hidden..................................................................................................................................................................................... 145isIsolated ................................................................................................................................................................................ 145layer.......................................................................................................................................................................................... 145left............................................................................................................................................................................................. 145locked ...................................................................................................................................................................................... 145name........................................................................................................................................................................................ 145opacity .................................................................................................................................................................................... 145parent ...................................................................................................................................................................................... 145position................................................................................................................................................................................... 145selected................................................................................................................................................................................... 145sliced........................................................................................................................................................................................ 145tags........................................................................................................................................................................................... 145top ............................................................................................................................................................................................ 145typename............................................................................................................................................................................... 145uRL............................................................................................................................................................................................ 145visibilityVariable .................................................................................................................................................................. 145visibleBounds ....................................................................................................................................................................... 146width........................................................................................................................................................................................ 146wrapInside ............................................................................................................................................................................. 146wrapOffset ............................................................................................................................................................................. 146wrapped ................................................................................................................................................................................. 146zOrderPosition ..................................................................................................................................................................... 146LegacyTextItem methods ................................................................................................................................................ 146convertToNative.................................................................................................................................................................. 146duplicate ................................................................................................................................................................................ 146move........................................................................................................................................................................................ 146remove.................................................................................................................................................................................... 146resize........................................................................................................................................................................................ 146rotate ....................................................................................................................................................................................... 146transform................................................................................................................................................................................ 147translate.................................................................................................................................................................................. 147zOrder...................................................................................................................................................................................... 147

LegacyTextItems........................................................................................................................................................................ 148LegacyTextItems properties............................................................................................................................................ 148length ...................................................................................................................................................................................... 148parent ...................................................................................................................................................................................... 148


typename............................................................................................................................................................................... 148LegacyTextItems methods .............................................................................................................................................. 148convertToNative.................................................................................................................................................................. 148getByName............................................................................................................................................................................ 148index ........................................................................................................................................................................................ 148removeAll............................................................................................................................................................................... 148

Lines ............................................................................................................................................................................................... 149Lines properties ................................................................................................................................................................... 149length ...................................................................................................................................................................................... 149parent ...................................................................................................................................................................................... 149typename............................................................................................................................................................................... 149Lines methods...................................................................................................................................................................... 149index ........................................................................................................................................................................................ 149removeAll............................................................................................................................................................................... 149

Matrix ............................................................................................................................................................................................. 150Matrix properties................................................................................................................................................................. 150mValueA ................................................................................................................................................................................. 150mValueB ................................................................................................................................................................................. 150mValueC ................................................................................................................................................................................. 150mValueD................................................................................................................................................................................. 150mValueTX............................................................................................................................................................................... 150mValueTY ............................................................................................................................................................................... 150typename............................................................................................................................................................................... 150

MeshItem...................................................................................................................................................................................... 151MeshItem properties ......................................................................................................................................................... 151artworkKnockout ................................................................................................................................................................ 151blendingMode ..................................................................................................................................................................... 151controlBounds...................................................................................................................................................................... 151editable................................................................................................................................................................................... 151geometricBounds ............................................................................................................................................................... 151height ...................................................................................................................................................................................... 151hidden..................................................................................................................................................................................... 151isIsolated ................................................................................................................................................................................ 151layer.......................................................................................................................................................................................... 151left............................................................................................................................................................................................. 151locked ...................................................................................................................................................................................... 151name........................................................................................................................................................................................ 151opacity .................................................................................................................................................................................... 151parent ...................................................................................................................................................................................... 151position................................................................................................................................................................................... 151selected................................................................................................................................................................................... 151sliced........................................................................................................................................................................................ 151tags........................................................................................................................................................................................... 151top ............................................................................................................................................................................................ 151typename............................................................................................................................................................................... 151uRL............................................................................................................................................................................................ 151visibilityVariable .................................................................................................................................................................. 151visibleBounds ....................................................................................................................................................................... 151width........................................................................................................................................................................................ 152wrapInside ............................................................................................................................................................................. 152wrapOffset ............................................................................................................................................................................. 152


wrapped ................................................................................................................................................................................. 152zOrderPosition ..................................................................................................................................................................... 152MeshItem methods ............................................................................................................................................................ 152duplicate ................................................................................................................................................................................ 152move........................................................................................................................................................................................ 152remove.................................................................................................................................................................................... 152resize........................................................................................................................................................................................ 152rotate ....................................................................................................................................................................................... 152transform................................................................................................................................................................................ 152translate.................................................................................................................................................................................. 153zOrder...................................................................................................................................................................................... 153

MeshItems.................................................................................................................................................................................... 154MeshItems properties........................................................................................................................................................ 154length ...................................................................................................................................................................................... 154parent ...................................................................................................................................................................................... 154typename............................................................................................................................................................................... 154MeshItems methods .......................................................................................................................................................... 154getByName............................................................................................................................................................................ 154index ........................................................................................................................................................................................ 154removeAll............................................................................................................................................................................... 154

NoColor ......................................................................................................................................................................................... 155NoColor properties............................................................................................................................................................. 155typename............................................................................................................................................................................... 155

OpenOptions .............................................................................................................................................................................. 156OpenOptions properties .................................................................................................................................................. 156typename............................................................................................................................................................................... 156updateLegacyText .............................................................................................................................................................. 156

PageItems..................................................................................................................................................................................... 157PageItems properties ........................................................................................................................................................ 157length ...................................................................................................................................................................................... 157parent ...................................................................................................................................................................................... 157typename............................................................................................................................................................................... 157PageItems methods ........................................................................................................................................................... 157getByName............................................................................................................................................................................ 157index ........................................................................................................................................................................................ 157removeAll............................................................................................................................................................................... 157

Paper .............................................................................................................................................................................................. 159Paper properties.................................................................................................................................................................. 159name........................................................................................................................................................................................ 159paperInfo................................................................................................................................................................................ 159typename............................................................................................................................................................................... 159

PaperInfo ...................................................................................................................................................................................... 159PaperInfo properties .......................................................................................................................................................... 159customPaper......................................................................................................................................................................... 159height ...................................................................................................................................................................................... 159imageableArea..................................................................................................................................................................... 159typename............................................................................................................................................................................... 159width........................................................................................................................................................................................ 159

ParagraphAttributes................................................................................................................................................................. 161ParagraphAttributes properties .................................................................................................................................... 161autoLeadingAmount ......................................................................................................................................................... 161


bunriKinshi ............................................................................................................................................................................ 161burasagariType .................................................................................................................................................................... 161desiredGlyphScaling.......................................................................................................................................................... 161desiredLetterSpacing ........................................................................................................................................................ 161desiredWordSpacing ......................................................................................................................................................... 161everyLineComposer ........................................................................................................................................................... 161firstLineIndent ...................................................................................................................................................................... 161hyphenateCapitalizedWords .......................................................................................................................................... 161hyphenation ......................................................................................................................................................................... 161hyphenationPreference.................................................................................................................................................... 161hyphenationZone ............................................................................................................................................................... 161justification............................................................................................................................................................................ 161kinsoku.................................................................................................................................................................................... 161kinsokuOrder ........................................................................................................................................................................ 161kurikaeshiMojiShori............................................................................................................................................................ 161leadingType .......................................................................................................................................................................... 161leftIndent................................................................................................................................................................................ 161maximumConsecutiveHyphens .................................................................................................................................... 161maximumGlyphScaling .................................................................................................................................................... 161maximumLetterSpacing................................................................................................................................................... 162maximumWordSpacing.................................................................................................................................................... 162minimumAfterHyphen...................................................................................................................................................... 162minimumBeforeHyphen................................................................................................................................................... 162minimumGlyphScaling ..................................................................................................................................................... 162minimumHyphenatedWordSize.................................................................................................................................... 162minimumLetterSpacing.................................................................................................................................................... 162minimumWordSpacing .................................................................................................................................................... 162mojikumi ................................................................................................................................................................................ 162parent ...................................................................................................................................................................................... 162rightIndent ............................................................................................................................................................................ 162romanHanging..................................................................................................................................................................... 162singleWordJustification .................................................................................................................................................... 162spaceAfter.............................................................................................................................................................................. 162spaceBefore........................................................................................................................................................................... 162tabStops ................................................................................................................................................................................. 162typename............................................................................................................................................................................... 162

Paragraphs................................................................................................................................................................................... 164Paragraphs properties....................................................................................................................................................... 164length ...................................................................................................................................................................................... 164parent ...................................................................................................................................................................................... 164typename............................................................................................................................................................................... 164Paragraphs methods.......................................................................................................................................................... 164add............................................................................................................................................................................................ 164addBefore .............................................................................................................................................................................. 164index ........................................................................................................................................................................................ 164removeAll............................................................................................................................................................................... 164

ParagraphStyle ........................................................................................................................................................................... 165ParagraphStyle properties............................................................................................................................................... 165characterAttributes ............................................................................................................................................................ 165name........................................................................................................................................................................................ 165paragraphAttributes .......................................................................................................................................................... 165


parent ...................................................................................................................................................................................... 165typename............................................................................................................................................................................... 165ParagraphStyle methods.................................................................................................................................................. 165applyTo ................................................................................................................................................................................... 165remove.................................................................................................................................................................................... 165

ParagraphStyles ......................................................................................................................................................................... 166ParagraphStyles properties ............................................................................................................................................. 166length ...................................................................................................................................................................................... 166parent ...................................................................................................................................................................................... 166typename............................................................................................................................................................................... 166ParagraphStyles methods................................................................................................................................................ 166add............................................................................................................................................................................................ 166getByName............................................................................................................................................................................ 166index ........................................................................................................................................................................................ 166removeAll............................................................................................................................................................................... 166

PathItem ....................................................................................................................................................................................... 168PathItem properties ........................................................................................................................................................... 168area........................................................................................................................................................................................... 168artworkKnockout ................................................................................................................................................................ 168blendingMode ..................................................................................................................................................................... 168clipping................................................................................................................................................................................... 168closed ...................................................................................................................................................................................... 168controlBounds...................................................................................................................................................................... 168editable................................................................................................................................................................................... 168evenodd ................................................................................................................................................................................. 168fillColor.................................................................................................................................................................................... 168filled ......................................................................................................................................................................................... 168fillOverprint ........................................................................................................................................................................... 168geometricBounds ............................................................................................................................................................... 168guides...................................................................................................................................................................................... 168height ...................................................................................................................................................................................... 168hidden..................................................................................................................................................................................... 168isIsolated ................................................................................................................................................................................ 168layer.......................................................................................................................................................................................... 168left............................................................................................................................................................................................. 168locked ...................................................................................................................................................................................... 168name........................................................................................................................................................................................ 168note .......................................................................................................................................................................................... 169opacity .................................................................................................................................................................................... 169parent ...................................................................................................................................................................................... 169pathPoints ............................................................................................................................................................................. 169polarity.................................................................................................................................................................................... 169position................................................................................................................................................................................... 169resolution............................................................................................................................................................................... 169selected................................................................................................................................................................................... 169selectedPathPoints............................................................................................................................................................. 169sliced........................................................................................................................................................................................ 169strokeCap ............................................................................................................................................................................... 169strokeColor ............................................................................................................................................................................ 169stroked .................................................................................................................................................................................... 169strokeDashes ........................................................................................................................................................................ 169


strokeDashOffset................................................................................................................................................................. 169strokeJoin............................................................................................................................................................................... 169strokeMiterLimit .................................................................................................................................................................. 169strokeOverprint.................................................................................................................................................................... 169strokeWidth........................................................................................................................................................................... 169tags........................................................................................................................................................................................... 169top ............................................................................................................................................................................................ 169typename............................................................................................................................................................................... 169uRL............................................................................................................................................................................................ 169visibilityVariable .................................................................................................................................................................. 169visibleBounds ....................................................................................................................................................................... 170width........................................................................................................................................................................................ 170wrapInside ............................................................................................................................................................................. 170wrapOffset ............................................................................................................................................................................. 170wrapped ................................................................................................................................................................................. 170zOrderPosition ..................................................................................................................................................................... 170PathItem methods.............................................................................................................................................................. 170duplicate ................................................................................................................................................................................ 170move........................................................................................................................................................................................ 170remove.................................................................................................................................................................................... 170resize........................................................................................................................................................................................ 170rotate ....................................................................................................................................................................................... 170setEntirePath ........................................................................................................................................................................ 170transform................................................................................................................................................................................ 171translate.................................................................................................................................................................................. 171zOrder...................................................................................................................................................................................... 171

PathItems ..................................................................................................................................................................................... 172PathItems properties ......................................................................................................................................................... 172length ...................................................................................................................................................................................... 172parent ...................................................................................................................................................................................... 172typename............................................................................................................................................................................... 172PathItems methods ............................................................................................................................................................ 172add............................................................................................................................................................................................ 172ellipse ...................................................................................................................................................................................... 172getByName............................................................................................................................................................................ 172index ........................................................................................................................................................................................ 172polygon .................................................................................................................................................................................. 172rectangle ................................................................................................................................................................................ 172removeAll............................................................................................................................................................................... 172roundedRectangle.............................................................................................................................................................. 173star ............................................................................................................................................................................................ 173

PathPoint...................................................................................................................................................................................... 174PathPoint properties.......................................................................................................................................................... 174anchor ..................................................................................................................................................................................... 174leftDirection .......................................................................................................................................................................... 174parent ...................................................................................................................................................................................... 174pointType............................................................................................................................................................................... 174rightDirection ....................................................................................................................................................................... 174selected................................................................................................................................................................................... 174typename............................................................................................................................................................................... 174PathPoint methods ............................................................................................................................................................ 174


remove.................................................................................................................................................................................... 174PathPoints .................................................................................................................................................................................... 175

PathPoints properties........................................................................................................................................................ 175length ...................................................................................................................................................................................... 175parent ...................................................................................................................................................................................... 175typename............................................................................................................................................................................... 175PathPoints methods........................................................................................................................................................... 175add............................................................................................................................................................................................ 175index ........................................................................................................................................................................................ 175removeAll............................................................................................................................................................................... 175

Pattern........................................................................................................................................................................................... 176Pattern properties............................................................................................................................................................... 176name........................................................................................................................................................................................ 176parent ...................................................................................................................................................................................... 176typename............................................................................................................................................................................... 176Pattern methods.................................................................................................................................................................. 176remove.................................................................................................................................................................................... 176toString ................................................................................................................................................................................... 176

Patterns ......................................................................................................................................................................................... 176Patterns properties............................................................................................................................................................. 176length ...................................................................................................................................................................................... 176parent ...................................................................................................................................................................................... 176typename............................................................................................................................................................................... 176Patterns methods................................................................................................................................................................ 176add............................................................................................................................................................................................ 176getByName............................................................................................................................................................................ 176index ........................................................................................................................................................................................ 177removeAll............................................................................................................................................................................... 177

PatternColor ................................................................................................................................................................................ 178PatternColor properties .................................................................................................................................................... 178matrix ...................................................................................................................................................................................... 178pattern .................................................................................................................................................................................... 178reflect....................................................................................................................................................................................... 178reflectAngle........................................................................................................................................................................... 178rotation ................................................................................................................................................................................... 178scaleFactor............................................................................................................................................................................. 178shearAngle............................................................................................................................................................................. 178shearAxis ................................................................................................................................................................................ 178shiftAngle............................................................................................................................................................................... 178shiftDistance ......................................................................................................................................................................... 178typename............................................................................................................................................................................... 178

PDFFileOptions .......................................................................................................................................................................... 180PDFFileOptions properties .............................................................................................................................................. 180pageToOpen......................................................................................................................................................................... 180parent ...................................................................................................................................................................................... 180pDFCropToBox..................................................................................................................................................................... 180typename............................................................................................................................................................................... 180

PDFSaveOptions ........................................................................................................................................................................ 181PDFSaveOptions properties............................................................................................................................................ 181acrobatLayers ....................................................................................................................................................................... 181bleedLink................................................................................................................................................................................ 181


bleedOffsetRect ................................................................................................................................................................... 181colorBars................................................................................................................................................................................. 181colorCompression............................................................................................................................................................... 181colorConversionID.............................................................................................................................................................. 181colorDestinationID ............................................................................................................................................................. 181colorDownsampling .......................................................................................................................................................... 181colorDownsamplingImageThreshold.......................................................................................................................... 181colorDownsamplingMethod .......................................................................................................................................... 181colorProfileID........................................................................................................................................................................ 181colorTileSize .......................................................................................................................................................................... 181compatibility......................................................................................................................................................................... 181compressArt.......................................................................................................................................................................... 182documentPassword ........................................................................................................................................................... 182enableAccess ........................................................................................................................................................................ 182enableCopy ........................................................................................................................................................................... 182enableCopyAccess.............................................................................................................................................................. 182enablePlainText ................................................................................................................................................................... 182flattenerOptions .................................................................................................................................................................. 182flattenerPreset...................................................................................................................................................................... 182fontSubsetThreshold ......................................................................................................................................................... 182generateThumbnails ......................................................................................................................................................... 182grayscaleCompression...................................................................................................................................................... 182grayscaleDownsampling.................................................................................................................................................. 182grayscaleDownsamplingImageThreshold................................................................................................................. 182grayscaleDownsamplingMethod.................................................................................................................................. 183grayscaleTileSize ................................................................................................................................................................. 183monochromeCompression ............................................................................................................................................. 183monochromeDownsampling ......................................................................................................................................... 183monochromeDownsamplingImageThreshold ........................................................................................................ 183monochromeDownsamplingMethod ......................................................................................................................... 183offset........................................................................................................................................................................................ 183optimization.......................................................................................................................................................................... 183outputCondition ................................................................................................................................................................. 183outputConditionID............................................................................................................................................................. 183pageInformation ................................................................................................................................................................. 183pageMarksType ................................................................................................................................................................... 183pDFAllowPrinting................................................................................................................................................................ 183pDFChangesAllowed......................................................................................................................................................... 183pDFPreset............................................................................................................................................................................... 184pDFXStandard...................................................................................................................................................................... 184pDFXStandardDescription............................................................................................................................................... 184permissionPassword.......................................................................................................................................................... 184preserveEditability.............................................................................................................................................................. 184printerResolution ................................................................................................................................................................ 184registrationMarks ................................................................................................................................................................ 184requireDocumentPassword ............................................................................................................................................ 184requirePermissionPassword............................................................................................................................................ 184trapped ................................................................................................................................................................................... 184trimMarks ............................................................................................................................................................................... 184trimMarkWeight .................................................................................................................................................................. 184typename............................................................................................................................................................................... 184


viewAfterSaving .................................................................................................................................................................. 184PhotoshopFileOptions ............................................................................................................................................................ 186

PhotoshopFileOptions properties ................................................................................................................................ 186parent ...................................................................................................................................................................................... 186pixelAspectRatioCorrection ............................................................................................................................................ 186preserveImageMaps .......................................................................................................................................................... 186preserveLayers ..................................................................................................................................................................... 186preserveSlices....................................................................................................................................................................... 186typename............................................................................................................................................................................... 186

PlacedItem ................................................................................................................................................................................... 187PlacedItem properties ....................................................................................................................................................... 187artworkKnockout ................................................................................................................................................................ 187blendingMode ..................................................................................................................................................................... 187boundingBox........................................................................................................................................................................ 187contentVariable ................................................................................................................................................................... 187controlBounds...................................................................................................................................................................... 187editable................................................................................................................................................................................... 187file ............................................................................................................................................................................................. 187geometricBounds ............................................................................................................................................................... 187height ...................................................................................................................................................................................... 187hidden..................................................................................................................................................................................... 187isIsolated ................................................................................................................................................................................ 187layer.......................................................................................................................................................................................... 187left............................................................................................................................................................................................. 187locked ...................................................................................................................................................................................... 187matrix ...................................................................................................................................................................................... 187name........................................................................................................................................................................................ 187opacity .................................................................................................................................................................................... 187parent ...................................................................................................................................................................................... 187position................................................................................................................................................................................... 187selected................................................................................................................................................................................... 187sliced........................................................................................................................................................................................ 187tags........................................................................................................................................................................................... 188top ............................................................................................................................................................................................ 188typename............................................................................................................................................................................... 188uRL............................................................................................................................................................................................ 188visibilityVariable .................................................................................................................................................................. 188visibleBounds ....................................................................................................................................................................... 188width........................................................................................................................................................................................ 188wrapInside ............................................................................................................................................................................. 188wrapOffset ............................................................................................................................................................................. 188wrapped ................................................................................................................................................................................. 188zOrderPosition ..................................................................................................................................................................... 188PlacedItem methods.......................................................................................................................................................... 188duplicate ................................................................................................................................................................................ 188embed ..................................................................................................................................................................................... 188move........................................................................................................................................................................................ 188remove.................................................................................................................................................................................... 188resize........................................................................................................................................................................................ 189rotate ....................................................................................................................................................................................... 189trace ......................................................................................................................................................................................... 189


transform................................................................................................................................................................................ 189translate.................................................................................................................................................................................. 189zOrder...................................................................................................................................................................................... 189

PlacedItems ................................................................................................................................................................................. 191PlacedItems properties ..................................................................................................................................................... 191length ...................................................................................................................................................................................... 191parent ...................................................................................................................................................................................... 191typename............................................................................................................................................................................... 191PlacedItems methods........................................................................................................................................................ 191add............................................................................................................................................................................................ 191getByName............................................................................................................................................................................ 191index ........................................................................................................................................................................................ 191removeAll............................................................................................................................................................................... 191

PluginItem.................................................................................................................................................................................... 192PluginItem properties ....................................................................................................................................................... 192artworkKnockout ................................................................................................................................................................ 192blendingMode ..................................................................................................................................................................... 192controlBounds...................................................................................................................................................................... 192editable................................................................................................................................................................................... 192geometricBounds ............................................................................................................................................................... 192height ...................................................................................................................................................................................... 192hidden..................................................................................................................................................................................... 192isIsolated ................................................................................................................................................................................ 192isTracing ................................................................................................................................................................................. 192layer.......................................................................................................................................................................................... 192left............................................................................................................................................................................................. 192locked ...................................................................................................................................................................................... 192name........................................................................................................................................................................................ 192opacity .................................................................................................................................................................................... 192parent ...................................................................................................................................................................................... 192position................................................................................................................................................................................... 192selected................................................................................................................................................................................... 192sliced........................................................................................................................................................................................ 192tags........................................................................................................................................................................................... 192top ............................................................................................................................................................................................ 192tracing ..................................................................................................................................................................................... 193typename............................................................................................................................................................................... 193uRL............................................................................................................................................................................................ 193visibilityVariable .................................................................................................................................................................. 193visibleBounds ....................................................................................................................................................................... 193width........................................................................................................................................................................................ 193wrapInside ............................................................................................................................................................................. 193wrapOffset ............................................................................................................................................................................. 193wrapped ................................................................................................................................................................................. 193zOrderPosition ..................................................................................................................................................................... 193PluginItem methods .......................................................................................................................................................... 193duplicate ................................................................................................................................................................................ 193move........................................................................................................................................................................................ 193remove.................................................................................................................................................................................... 193resize........................................................................................................................................................................................ 193rotate ....................................................................................................................................................................................... 194


transform................................................................................................................................................................................ 194translate.................................................................................................................................................................................. 194zOrder...................................................................................................................................................................................... 194

PluginItems.................................................................................................................................................................................. 195PluginItems properties...................................................................................................................................................... 195length ...................................................................................................................................................................................... 195parent ...................................................................................................................................................................................... 195typename............................................................................................................................................................................... 195PluginItems methods ........................................................................................................................................................ 195getByName............................................................................................................................................................................ 195index ........................................................................................................................................................................................ 195removeAll............................................................................................................................................................................... 195

PPDFile .......................................................................................................................................................................................... 196PPDFile properties .............................................................................................................................................................. 196name........................................................................................................................................................................................ 196pPDInfo................................................................................................................................................................................... 196typename............................................................................................................................................................................... 196

PPDFileInfo .................................................................................................................................................................................. 196PPDFileInfo properties ...................................................................................................................................................... 196languageLevel...................................................................................................................................................................... 196PPDFilePath........................................................................................................................................................................... 196screenList ............................................................................................................................................................................... 196screenSpotFunctionList .................................................................................................................................................... 196typename............................................................................................................................................................................... 196

Preferences .................................................................................................................................................................................. 199Preferences properties ...................................................................................................................................................... 199parent ...................................................................................................................................................................................... 199PDFFileOptions .................................................................................................................................................................... 199photoshopFileOptions ...................................................................................................................................................... 199typename............................................................................................................................................................................... 199

PrintColorManagementOptions .......................................................................................................................................... 200PrintColorManagementOptions properties .............................................................................................................. 200colorProfileMode................................................................................................................................................................. 200intent ....................................................................................................................................................................................... 200name........................................................................................................................................................................................ 200typename............................................................................................................................................................................... 200

PrintColorSeparationOptions ............................................................................................................................................... 201PrintColorSeparationOptions properties ................................................................................................................... 201colorSeparationMode........................................................................................................................................................ 201convertSpotColors.............................................................................................................................................................. 201inkList ...................................................................................................................................................................................... 201overPrintBlack ...................................................................................................................................................................... 201typename............................................................................................................................................................................... 201

PrintCoordinateOptions ......................................................................................................................................................... 202PrintCoordinateOptions properties ............................................................................................................................. 202emulsion................................................................................................................................................................................. 202fitToPage ................................................................................................................................................................................ 202horizontalScale .................................................................................................................................................................... 202orientation............................................................................................................................................................................. 202position................................................................................................................................................................................... 202tiling......................................................................................................................................................................................... 202


typename............................................................................................................................................................................... 202verticalScale .......................................................................................................................................................................... 202

Printer ............................................................................................................................................................................................ 203Printer properties ................................................................................................................................................................ 203name........................................................................................................................................................................................ 203printerInfo.............................................................................................................................................................................. 203typename............................................................................................................................................................................... 203

PrinterInfo .................................................................................................................................................................................... 203PrinterInfo properties ........................................................................................................................................................ 203binaryPrintingSupport ...................................................................................................................................................... 203colorSupport......................................................................................................................................................................... 203customPaperSupport ........................................................................................................................................................ 203customPaperTransverseSupport................................................................................................................................... 203deviceResolution................................................................................................................................................................. 203inRIPSeparationSupport ................................................................................................................................................... 203maxDeviceResolution........................................................................................................................................................ 203maxPaperHeight ................................................................................................................................................................. 203maxPaperHeightOffset ..................................................................................................................................................... 203maxPaperWidth................................................................................................................................................................... 203maxPaperWidthOffset....................................................................................................................................................... 203minPaperHeight .................................................................................................................................................................. 204minPaperHeightOffset ...................................................................................................................................................... 204minPaperWidth.................................................................................................................................................................... 204minPaperWidthOffset........................................................................................................................................................ 204paperSizes.............................................................................................................................................................................. 204postScriptLevel .................................................................................................................................................................... 204printerType............................................................................................................................................................................ 204typename............................................................................................................................................................................... 204

PrintFlattenerOptions .............................................................................................................................................................. 205PrintFlattenerOptions properties.................................................................................................................................. 205clipComplexRegions .......................................................................................................................................................... 205convertStrokesToOutlines ............................................................................................................................................... 205convertTextToOutlines ..................................................................................................................................................... 205flatteningBalance................................................................................................................................................................ 205gradientResolution............................................................................................................................................................. 205overprint................................................................................................................................................................................. 205rasterizationResolution..................................................................................................................................................... 205typename............................................................................................................................................................................... 205

PrintFontOptions....................................................................................................................................................................... 206PrintFontOptions properties........................................................................................................................................... 206downloadFonts.................................................................................................................................................................... 206fontSubstitution .................................................................................................................................................................. 206typename............................................................................................................................................................................... 206

PrintJobOptions......................................................................................................................................................................... 207PrintJobOptions properties............................................................................................................................................. 207bitmapResolution ............................................................................................................................................................... 207collate...................................................................................................................................................................................... 207copies ...................................................................................................................................................................................... 207designation ........................................................................................................................................................................... 207file ............................................................................................................................................................................................. 207name........................................................................................................................................................................................ 207


printArea ................................................................................................................................................................................ 207printAsBitmap ...................................................................................................................................................................... 207reversePages......................................................................................................................................................................... 207typename............................................................................................................................................................................... 207

PrintOptions ................................................................................................................................................................................ 209PrintOptions properties .................................................................................................................................................... 209colorManagementOptions .............................................................................................................................................. 209colorSeparationOptions ................................................................................................................................................... 209coordinateOptions ............................................................................................................................................................. 209flattenerOptions .................................................................................................................................................................. 209flattenerPreset...................................................................................................................................................................... 209fontOptions ........................................................................................................................................................................... 209jobOptions............................................................................................................................................................................. 209pageMarksOptions ............................................................................................................................................................. 209paperOptions ....................................................................................................................................................................... 209postScriptOptions............................................................................................................................................................... 209PPDName ............................................................................................................................................................................... 209printerName.......................................................................................................................................................................... 209printPreset ............................................................................................................................................................................. 209typename............................................................................................................................................................................... 209

PrintPageMarksOptions .......................................................................................................................................................... 211PrintPageMarksOptions properties .............................................................................................................................. 211bleedOffsetRect ................................................................................................................................................................... 211colorBars................................................................................................................................................................................. 211marksOffsetRect .................................................................................................................................................................. 211pageInfoMarks ..................................................................................................................................................................... 211pageMarksType ................................................................................................................................................................... 211registrationMarks ................................................................................................................................................................ 211trimMarks ............................................................................................................................................................................... 211trimMarksWeight ................................................................................................................................................................ 211typename............................................................................................................................................................................... 211

PrintPaperOptions .................................................................................................................................................................... 212PrintPaperOptions properties ........................................................................................................................................ 212height ...................................................................................................................................................................................... 212name........................................................................................................................................................................................ 212offset........................................................................................................................................................................................ 212transverse............................................................................................................................................................................... 212typename............................................................................................................................................................................... 212width........................................................................................................................................................................................ 212

PrintPostScriptOptions............................................................................................................................................................ 213PrintPostScriptOptions properties................................................................................................................................ 213binaryPrinting....................................................................................................................................................................... 213compatibleShading............................................................................................................................................................ 213forceContinuousTone........................................................................................................................................................ 213imageCompression ............................................................................................................................................................ 213negativePrinting.................................................................................................................................................................. 213postScriptLevel .................................................................................................................................................................... 213shadingResolution.............................................................................................................................................................. 213typename............................................................................................................................................................................... 213

RasterItem .................................................................................................................................................................................... 214RasterItem properties........................................................................................................................................................ 214


artworkKnockout ................................................................................................................................................................ 214blendingMode ..................................................................................................................................................................... 214boundingBox........................................................................................................................................................................ 214contentVariable ................................................................................................................................................................... 214controlBounds...................................................................................................................................................................... 214editable................................................................................................................................................................................... 214embedded ............................................................................................................................................................................. 214file ............................................................................................................................................................................................. 214geometricBounds ............................................................................................................................................................... 214height ...................................................................................................................................................................................... 214hidden..................................................................................................................................................................................... 214imageColorSpace................................................................................................................................................................ 214isIsolated ................................................................................................................................................................................ 214layer.......................................................................................................................................................................................... 214left............................................................................................................................................................................................. 214locked ...................................................................................................................................................................................... 214matrix ...................................................................................................................................................................................... 214name........................................................................................................................................................................................ 214opacity .................................................................................................................................................................................... 214parent ...................................................................................................................................................................................... 214position................................................................................................................................................................................... 214selected................................................................................................................................................................................... 214sliced........................................................................................................................................................................................ 214status ....................................................................................................................................................................................... 215tags........................................................................................................................................................................................... 215top ............................................................................................................................................................................................ 215typename............................................................................................................................................................................... 215uRL............................................................................................................................................................................................ 215visibilityVariable .................................................................................................................................................................. 215visibleBounds ....................................................................................................................................................................... 215width........................................................................................................................................................................................ 215wrapInside ............................................................................................................................................................................. 215wrapOffset ............................................................................................................................................................................. 215wrapped ................................................................................................................................................................................. 215zOrderPosition ..................................................................................................................................................................... 215RasterItem methods........................................................................................................................................................... 215colorize.................................................................................................................................................................................... 215duplicate ................................................................................................................................................................................ 215move........................................................................................................................................................................................ 215remove.................................................................................................................................................................................... 215resize........................................................................................................................................................................................ 216rotate ....................................................................................................................................................................................... 216trace ......................................................................................................................................................................................... 216transform................................................................................................................................................................................ 216translate.................................................................................................................................................................................. 216zOrder...................................................................................................................................................................................... 216

RasterItems .................................................................................................................................................................................. 217RasterItems properties ...................................................................................................................................................... 217length ...................................................................................................................................................................................... 217parent ...................................................................................................................................................................................... 217typename............................................................................................................................................................................... 217


RasterItems methods......................................................................................................................................................... 217add............................................................................................................................................................................................ 217getByName............................................................................................................................................................................ 217index ........................................................................................................................................................................................ 217removeAll............................................................................................................................................................................... 217

RGBColor....................................................................................................................................................................................... 218RGBColor properties .......................................................................................................................................................... 218blue .......................................................................................................................................................................................... 218green........................................................................................................................................................................................ 218red............................................................................................................................................................................................. 218typename............................................................................................................................................................................... 218

Screen ............................................................................................................................................................................................ 219Screen properties................................................................................................................................................................ 219name........................................................................................................................................................................................ 219screenInfo .............................................................................................................................................................................. 219typename............................................................................................................................................................................... 219

ScreenInfo .................................................................................................................................................................................... 219ScreenInfo properties ........................................................................................................................................................ 219angle ........................................................................................................................................................................................ 219defaultScreen ....................................................................................................................................................................... 219frequency ............................................................................................................................................................................... 219typename............................................................................................................................................................................... 219

ScreenSpotFunction................................................................................................................................................................. 221ScreenSpotFunction properties..................................................................................................................................... 221name........................................................................................................................................................................................ 221spotFunction......................................................................................................................................................................... 221typename............................................................................................................................................................................... 221

Spot ................................................................................................................................................................................................ 222Spot properties .................................................................................................................................................................... 222color ......................................................................................................................................................................................... 222colorType ............................................................................................................................................................................... 222name........................................................................................................................................................................................ 222parent ...................................................................................................................................................................................... 222typename............................................................................................................................................................................... 222Spot methods....................................................................................................................................................................... 222remove.................................................................................................................................................................................... 222

SpotColor ..................................................................................................................................................................................... 223SpotColor properties ......................................................................................................................................................... 223spot .......................................................................................................................................................................................... 223tint ............................................................................................................................................................................................ 223typename............................................................................................................................................................................... 223

Spots .............................................................................................................................................................................................. 224Spots properties .................................................................................................................................................................. 224length ...................................................................................................................................................................................... 224parent ...................................................................................................................................................................................... 224typename............................................................................................................................................................................... 224Spots methods ..................................................................................................................................................................... 224add............................................................................................................................................................................................ 224getByName............................................................................................................................................................................ 224index ........................................................................................................................................................................................ 224removeAll............................................................................................................................................................................... 224


Story ............................................................................................................................................................................................... 226Story properties ................................................................................................................................................................... 226characters............................................................................................................................................................................... 226insertionPoints ..................................................................................................................................................................... 226length ...................................................................................................................................................................................... 226lines .......................................................................................................................................................................................... 226paragraphs ............................................................................................................................................................................ 226parent ...................................................................................................................................................................................... 226textFrames............................................................................................................................................................................. 226textRange............................................................................................................................................................................... 226textRanges............................................................................................................................................................................. 226textSelection......................................................................................................................................................................... 226typename............................................................................................................................................................................... 226words....................................................................................................................................................................................... 226

Stories ............................................................................................................................................................................................ 228Stories properties................................................................................................................................................................ 228length ...................................................................................................................................................................................... 228parent ...................................................................................................................................................................................... 228typename............................................................................................................................................................................... 228Stories methods................................................................................................................................................................... 228index ........................................................................................................................................................................................ 228

Swatch........................................................................................................................................................................................... 229Swatch properties............................................................................................................................................................... 229color ......................................................................................................................................................................................... 229name........................................................................................................................................................................................ 229parent ...................................................................................................................................................................................... 229typename............................................................................................................................................................................... 229Swatch methods.................................................................................................................................................................. 229remove.................................................................................................................................................................................... 229

Swatches....................................................................................................................................................................................... 230Swatches properties .......................................................................................................................................................... 230length ...................................................................................................................................................................................... 230parent ...................................................................................................................................................................................... 230typename............................................................................................................................................................................... 230Swatches methods ............................................................................................................................................................. 230add............................................................................................................................................................................................ 230getByName............................................................................................................................................................................ 230index ........................................................................................................................................................................................ 230removeAll............................................................................................................................................................................... 230

Symbol .......................................................................................................................................................................................... 231Symbol properties .............................................................................................................................................................. 231name........................................................................................................................................................................................ 231parent ...................................................................................................................................................................................... 231typename............................................................................................................................................................................... 231Symbol methods ................................................................................................................................................................. 231duplicate ................................................................................................................................................................................ 231remove.................................................................................................................................................................................... 231

Symbols......................................................................................................................................................................................... 232Symbols properties ............................................................................................................................................................ 232length ...................................................................................................................................................................................... 232parent ...................................................................................................................................................................................... 232


typename............................................................................................................................................................................... 232Symbols methods ............................................................................................................................................................... 232add............................................................................................................................................................................................ 232index ........................................................................................................................................................................................ 232getByName............................................................................................................................................................................ 232removeAll............................................................................................................................................................................... 232

SymbolItem ................................................................................................................................................................................. 234SymbolItem properties ..................................................................................................................................................... 234artworkKnockout ................................................................................................................................................................ 234blendingMode ..................................................................................................................................................................... 234controlBounds...................................................................................................................................................................... 234editable................................................................................................................................................................................... 234geometricBounds ............................................................................................................................................................... 234height ...................................................................................................................................................................................... 234hidden..................................................................................................................................................................................... 234isIsolated ................................................................................................................................................................................ 234layer.......................................................................................................................................................................................... 234left............................................................................................................................................................................................. 234locked ...................................................................................................................................................................................... 234name........................................................................................................................................................................................ 234opacity .................................................................................................................................................................................... 234parent ...................................................................................................................................................................................... 234position................................................................................................................................................................................... 234selected................................................................................................................................................................................... 234sliced........................................................................................................................................................................................ 234symbol..................................................................................................................................................................................... 234tags........................................................................................................................................................................................... 234top ............................................................................................................................................................................................ 234typename............................................................................................................................................................................... 234uRL............................................................................................................................................................................................ 234visibilityVariable .................................................................................................................................................................. 234visibleBounds ....................................................................................................................................................................... 235width........................................................................................................................................................................................ 235wrapInside ............................................................................................................................................................................. 235wrapOffset ............................................................................................................................................................................. 235wrapped ................................................................................................................................................................................. 235zOrderPosition ..................................................................................................................................................................... 235SymbolItem methods........................................................................................................................................................ 235duplicate ................................................................................................................................................................................ 235move........................................................................................................................................................................................ 235remove.................................................................................................................................................................................... 235resize........................................................................................................................................................................................ 235rotate ....................................................................................................................................................................................... 235transform................................................................................................................................................................................ 236translate.................................................................................................................................................................................. 236zOrder...................................................................................................................................................................................... 236

SymbolItems ............................................................................................................................................................................... 237SymbolItems properties ................................................................................................................................................... 237length ...................................................................................................................................................................................... 237parent ...................................................................................................................................................................................... 237typename............................................................................................................................................................................... 237


SymbolItems methods...................................................................................................................................................... 237add............................................................................................................................................................................................ 237getByName............................................................................................................................................................................ 237index ........................................................................................................................................................................................ 237removeAll............................................................................................................................................................................... 237

TabStopInfo................................................................................................................................................................................. 238TabStopInfo properties..................................................................................................................................................... 238alignment............................................................................................................................................................................... 238decimalCharacter ................................................................................................................................................................ 238leader....................................................................................................................................................................................... 238position................................................................................................................................................................................... 238typename............................................................................................................................................................................... 238

Tag .................................................................................................................................................................................................. 239Tag properties ...................................................................................................................................................................... 239name........................................................................................................................................................................................ 239parent ...................................................................................................................................................................................... 239typename............................................................................................................................................................................... 239value ........................................................................................................................................................................................ 239Tag methods......................................................................................................................................................................... 239remove.................................................................................................................................................................................... 239

Tags ................................................................................................................................................................................................ 240Tags properties .................................................................................................................................................................... 240length ...................................................................................................................................................................................... 240parent ...................................................................................................................................................................................... 240typename............................................................................................................................................................................... 240Tags methods....................................................................................................................................................................... 240add............................................................................................................................................................................................ 240getByName............................................................................................................................................................................ 240index ........................................................................................................................................................................................ 240removeAll............................................................................................................................................................................... 240

TextFont........................................................................................................................................................................................ 241TextFont properties............................................................................................................................................................ 241family ....................................................................................................................................................................................... 241name........................................................................................................................................................................................ 241parent ...................................................................................................................................................................................... 241style .......................................................................................................................................................................................... 241typename............................................................................................................................................................................... 241

TextFonts...................................................................................................................................................................................... 242TextFonts properties.......................................................................................................................................................... 242length ...................................................................................................................................................................................... 242parent ...................................................................................................................................................................................... 242typename............................................................................................................................................................................... 242TextFonts methods ............................................................................................................................................................ 242index ........................................................................................................................................................................................ 242getByName............................................................................................................................................................................ 242

TextFrame .................................................................................................................................................................................... 243TextFrame properties ........................................................................................................................................................ 243anchor ..................................................................................................................................................................................... 243artworkKnockout ................................................................................................................................................................ 243blendingMode ..................................................................................................................................................................... 243characters............................................................................................................................................................................... 243


columnCount........................................................................................................................................................................ 243columnGutter ....................................................................................................................................................................... 243contents.................................................................................................................................................................................. 243contentVariable ................................................................................................................................................................... 243controlBounds...................................................................................................................................................................... 243editable................................................................................................................................................................................... 243endTValue.............................................................................................................................................................................. 243flowLinksHorizontally ........................................................................................................................................................ 243geometricBounds ............................................................................................................................................................... 243height ...................................................................................................................................................................................... 243hidden..................................................................................................................................................................................... 243insertionPoints ..................................................................................................................................................................... 243isIsolated ................................................................................................................................................................................ 243kind........................................................................................................................................................................................... 243layer.......................................................................................................................................................................................... 243left............................................................................................................................................................................................. 243lines .......................................................................................................................................................................................... 243locked ...................................................................................................................................................................................... 243matrix ...................................................................................................................................................................................... 244name........................................................................................................................................................................................ 244nextFrame.............................................................................................................................................................................. 244opacity .................................................................................................................................................................................... 244opticalAlignment ................................................................................................................................................................ 244orientation............................................................................................................................................................................. 244paragraphs ............................................................................................................................................................................ 244parent ...................................................................................................................................................................................... 244position................................................................................................................................................................................... 244previousFrame ..................................................................................................................................................................... 244rowCount ............................................................................................................................................................................... 244rowGutter............................................................................................................................................................................... 244selected................................................................................................................................................................................... 244sliced........................................................................................................................................................................................ 244spacing.................................................................................................................................................................................... 244startTValue............................................................................................................................................................................. 244story ......................................................................................................................................................................................... 244tags........................................................................................................................................................................................... 244textPath .................................................................................................................................................................................. 244textRange............................................................................................................................................................................... 244textRanges............................................................................................................................................................................. 244textSelection......................................................................................................................................................................... 244top ............................................................................................................................................................................................ 244typename............................................................................................................................................................................... 244uRL............................................................................................................................................................................................ 244visibilityVariable .................................................................................................................................................................. 244visibleBounds ....................................................................................................................................................................... 245width........................................................................................................................................................................................ 245words....................................................................................................................................................................................... 245wrapInside ............................................................................................................................................................................. 245wrapOffset ............................................................................................................................................................................. 245wrapped ................................................................................................................................................................................. 245zOrderPosition ..................................................................................................................................................................... 245


TextFrame methods........................................................................................................................................................... 245createOutline........................................................................................................................................................................ 245duplicate ................................................................................................................................................................................ 245move........................................................................................................................................................................................ 245remove.................................................................................................................................................................................... 245resize........................................................................................................................................................................................ 245rotate ....................................................................................................................................................................................... 245transform................................................................................................................................................................................ 246translate.................................................................................................................................................................................. 246zOrder...................................................................................................................................................................................... 246

TextFrames .................................................................................................................................................................................. 247TextFrames properties ...................................................................................................................................................... 247length ...................................................................................................................................................................................... 247parent ...................................................................................................................................................................................... 247typename............................................................................................................................................................................... 247TextFrames methods ......................................................................................................................................................... 247add............................................................................................................................................................................................ 247areaText .................................................................................................................................................................................. 247getByName............................................................................................................................................................................ 247index ........................................................................................................................................................................................ 247pathText ................................................................................................................................................................................. 247pointText................................................................................................................................................................................ 247removeAll............................................................................................................................................................................... 247

TextPath........................................................................................................................................................................................ 249TextPath properties............................................................................................................................................................ 249area........................................................................................................................................................................................... 249blendingMode ..................................................................................................................................................................... 249clipping................................................................................................................................................................................... 249editable................................................................................................................................................................................... 249evenodd ................................................................................................................................................................................. 249fillColor.................................................................................................................................................................................... 249filled ......................................................................................................................................................................................... 249fillOverprint ........................................................................................................................................................................... 249guides...................................................................................................................................................................................... 249height ...................................................................................................................................................................................... 249left............................................................................................................................................................................................. 249note .......................................................................................................................................................................................... 249opacity .................................................................................................................................................................................... 249parent ...................................................................................................................................................................................... 249pathPoints ............................................................................................................................................................................. 249polarity.................................................................................................................................................................................... 249position................................................................................................................................................................................... 249resolution............................................................................................................................................................................... 249selectedPathPoints............................................................................................................................................................. 249strokeCap ............................................................................................................................................................................... 249strokeColor ............................................................................................................................................................................ 249stroked .................................................................................................................................................................................... 249strokeDashes ........................................................................................................................................................................ 250strokeDashOffset................................................................................................................................................................. 250strokeJoin............................................................................................................................................................................... 250strokeMiterLimit .................................................................................................................................................................. 250


strokeOverprint.................................................................................................................................................................... 250strokeWidth........................................................................................................................................................................... 250top ............................................................................................................................................................................................ 250typename............................................................................................................................................................................... 250width........................................................................................................................................................................................ 250TextPath methods .............................................................................................................................................................. 250setEntirePath ........................................................................................................................................................................ 250

TextRange .................................................................................................................................................................................... 251TextRange properties ........................................................................................................................................................ 251characterAttributes ............................................................................................................................................................ 251characterOffset .................................................................................................................................................................... 251characters............................................................................................................................................................................... 251characterStyles..................................................................................................................................................................... 251contents.................................................................................................................................................................................. 251insertionPoints ..................................................................................................................................................................... 251kerning.................................................................................................................................................................................... 251length ...................................................................................................................................................................................... 251lines .......................................................................................................................................................................................... 251paragraphAttributes .......................................................................................................................................................... 251paragraphs ............................................................................................................................................................................ 251paragraphStyles................................................................................................................................................................... 251parent ...................................................................................................................................................................................... 251story ......................................................................................................................................................................................... 251textRanges............................................................................................................................................................................. 251textSelection......................................................................................................................................................................... 251typename............................................................................................................................................................................... 251words....................................................................................................................................................................................... 251TextRange methods........................................................................................................................................................... 252changeCaseTo...................................................................................................................................................................... 252deSelect .................................................................................................................................................................................. 252duplicate ................................................................................................................................................................................ 252move........................................................................................................................................................................................ 252remove.................................................................................................................................................................................... 252select........................................................................................................................................................................................ 252

TextRanges .................................................................................................................................................................................. 253TextRanges properties ...................................................................................................................................................... 253length ...................................................................................................................................................................................... 253parent ...................................................................................................................................................................................... 253typename............................................................................................................................................................................... 253TextRanges methods ......................................................................................................................................................... 253index ........................................................................................................................................................................................ 253removeAll............................................................................................................................................................................... 253

TracingObject ............................................................................................................................................................................. 254TracingObject properties ................................................................................................................................................. 254anchorCount......................................................................................................................................................................... 254areaCount .............................................................................................................................................................................. 254imageResolution ................................................................................................................................................................. 254parent ...................................................................................................................................................................................... 254pathCount.............................................................................................................................................................................. 254sourceArt................................................................................................................................................................................ 254tracingOptions ..................................................................................................................................................................... 254


typename............................................................................................................................................................................... 254usedColorCount .................................................................................................................................................................. 254TracingObject methods.................................................................................................................................................... 255expandTracing ..................................................................................................................................................................... 255releaseTracing ...................................................................................................................................................................... 255

TracingOptions........................................................................................................................................................................... 256TracingOptions properties .............................................................................................................................................. 256cornerAngle .......................................................................................................................................................................... 256fills............................................................................................................................................................................................. 256livePaintOutput ................................................................................................................................................................... 256maxColors .............................................................................................................................................................................. 256maxStrokeWeight ............................................................................................................................................................... 256minArea .................................................................................................................................................................................. 256minStrokeLength ................................................................................................................................................................ 256outputToSwatches ............................................................................................................................................................. 256palette ..................................................................................................................................................................................... 256parent ...................................................................................................................................................................................... 256pathFitting............................................................................................................................................................................. 256preprocessBlur ..................................................................................................................................................................... 257preset....................................................................................................................................................................................... 257resample................................................................................................................................................................................. 257resampleResolution ........................................................................................................................................................... 257strokes ..................................................................................................................................................................................... 257threshold................................................................................................................................................................................ 257tracingMode ......................................................................................................................................................................... 257typename............................................................................................................................................................................... 257viewRaster ............................................................................................................................................................................. 257viewVector............................................................................................................................................................................. 257TracingOptions methods ................................................................................................................................................. 257loadFromPreset ................................................................................................................................................................... 257storeToPreset........................................................................................................................................................................ 257

Variable ......................................................................................................................................................................................... 258Variable properties ............................................................................................................................................................. 258kind........................................................................................................................................................................................... 258name........................................................................................................................................................................................ 258pageItems .............................................................................................................................................................................. 258parent ...................................................................................................................................................................................... 258typename............................................................................................................................................................................... 258Variable methods................................................................................................................................................................ 258remove.................................................................................................................................................................................... 258

Variables ....................................................................................................................................................................................... 259Variables properties ........................................................................................................................................................... 259length ...................................................................................................................................................................................... 259parent ...................................................................................................................................................................................... 259typename............................................................................................................................................................................... 259Variables methods .............................................................................................................................................................. 259add............................................................................................................................................................................................ 259getByName............................................................................................................................................................................ 259index ........................................................................................................................................................................................ 259removeAll............................................................................................................................................................................... 259

View................................................................................................................................................................................................ 260


View properties.................................................................................................................................................................... 260bounds.................................................................................................................................................................................... 260centerPoint............................................................................................................................................................................ 260parent ...................................................................................................................................................................................... 260screenMode .......................................................................................................................................................................... 260typename............................................................................................................................................................................... 260zoom........................................................................................................................................................................................ 260

Views.............................................................................................................................................................................................. 261Views properties.................................................................................................................................................................. 261length ...................................................................................................................................................................................... 261parent ...................................................................................................................................................................................... 261typename............................................................................................................................................................................... 261Views methods..................................................................................................................................................................... 261index ........................................................................................................................................................................................ 261

Words............................................................................................................................................................................................. 262Words properties................................................................................................................................................................. 262length ...................................................................................................................................................................................... 262parent ...................................................................................................................................................................................... 262typename............................................................................................................................................................................... 262Words methods ................................................................................................................................................................... 262add............................................................................................................................................................................................ 262addBefore .............................................................................................................................................................................. 262index ........................................................................................................................................................................................ 262removeAll............................................................................................................................................................................... 262

6 File and Folder Object Reference ...........................................................................................264Overview ...................................................................................................................................................................................... 264File Object .................................................................................................................................................................................... 264

File object constructors .................................................................................................................................................... 264File class properties ............................................................................................................................................................ 265fs ................................................................................................................................................................................................ 265File class functions.............................................................................................................................................................. 265decode .................................................................................................................................................................................... 265encode .................................................................................................................................................................................... 265isEncodingAvailable........................................................................................................................................................... 265openDialog............................................................................................................................................................................ 266saveDialog ............................................................................................................................................................................. 266File object properties......................................................................................................................................................... 267absoluteURI ........................................................................................................................................................................... 267alias........................................................................................................................................................................................... 267created .................................................................................................................................................................................... 267creator ..................................................................................................................................................................................... 267encoding ................................................................................................................................................................................ 267eof............................................................................................................................................................................................. 267error.......................................................................................................................................................................................... 267exists ........................................................................................................................................................................................ 267fsName .................................................................................................................................................................................... 267hidden..................................................................................................................................................................................... 267length ...................................................................................................................................................................................... 267lineFeed .................................................................................................................................................................................. 267modified ................................................................................................................................................................................. 267


name........................................................................................................................................................................................ 267parent ...................................................................................................................................................................................... 267path .......................................................................................................................................................................................... 268readonly.................................................................................................................................................................................. 268relativeURI.............................................................................................................................................................................. 268type .......................................................................................................................................................................................... 268File object functions........................................................................................................................................................... 268close ......................................................................................................................................................................................... 268copy.......................................................................................................................................................................................... 268createAlias ............................................................................................................................................................................. 268execute ................................................................................................................................................................................... 268getRelativeURI...................................................................................................................................................................... 268open......................................................................................................................................................................................... 269openDlg.................................................................................................................................................................................. 270read .......................................................................................................................................................................................... 270readch ..................................................................................................................................................................................... 270readln ...................................................................................................................................................................................... 270remove.................................................................................................................................................................................... 270rename.................................................................................................................................................................................... 271resolve..................................................................................................................................................................................... 271saveDlg ................................................................................................................................................................................... 271seek .......................................................................................................................................................................................... 271tell ............................................................................................................................................................................................. 271write ......................................................................................................................................................................................... 272writeln ..................................................................................................................................................................................... 272

Folder Object ............................................................................................................................................................................. 273Folder object constructors............................................................................................................................................... 273Folder class properties ...................................................................................................................................................... 273appData .................................................................................................................................................................................. 273commonFiles ........................................................................................................................................................................ 273current..................................................................................................................................................................................... 273fs ................................................................................................................................................................................................ 273myDocuments...................................................................................................................................................................... 273startup..................................................................................................................................................................................... 273system ..................................................................................................................................................................................... 274temp......................................................................................................................................................................................... 274trash ......................................................................................................................................................................................... 274userData ................................................................................................................................................................................. 274Folder class functions ........................................................................................................................................................ 274decode .................................................................................................................................................................................... 274encode .................................................................................................................................................................................... 274isEncodingAvailable........................................................................................................................................................... 274selectDialog........................................................................................................................................................................... 275Folder object properties................................................................................................................................................... 275absoluteURI ........................................................................................................................................................................... 275alias........................................................................................................................................................................................... 275created .................................................................................................................................................................................... 275error.......................................................................................................................................................................................... 275exists ........................................................................................................................................................................................ 275fsName .................................................................................................................................................................................... 275modified ................................................................................................................................................................................. 275


name........................................................................................................................................................................................ 275parent ...................................................................................................................................................................................... 275path .......................................................................................................................................................................................... 275relativeURI.............................................................................................................................................................................. 275Folder object functions..................................................................................................................................................... 276create....................................................................................................................................................................................... 276execute ................................................................................................................................................................................... 276getFiles.................................................................................................................................................................................... 276getRelativeURI...................................................................................................................................................................... 276remove.................................................................................................................................................................................... 276rename.................................................................................................................................................................................... 276resolve..................................................................................................................................................................................... 276selectDlg................................................................................................................................................................................. 277

File and Folder Error Messages ............................................................................................................................................ 278File and Folder Supported Encoding Names .................................................................................................................. 279

Additional encodings ........................................................................................................................................................ 279

7 Scripting Constants .................................................................................................................281AlternateGlyphsForm ........................................................................................................................................................ 281AutoKernType ...................................................................................................................................................................... 281AutoLeadingType ............................................................................................................................................................... 281BaselineDirectionType ...................................................................................................................................................... 281BlendAnimationType......................................................................................................................................................... 281BlendModes .......................................................................................................................................................................... 281BurasagariTypeEnum......................................................................................................................................................... 281CaseChangeType ................................................................................................................................................................ 281ColorConversion.................................................................................................................................................................. 282ColorDestination ................................................................................................................................................................. 282ColorDitherMethod............................................................................................................................................................ 282ColorModel............................................................................................................................................................................ 282ColorProfile............................................................................................................................................................................ 282ColorReductionMethod.................................................................................................................................................... 282ColorType............................................................................................................................................................................... 282Compatibility ........................................................................................................................................................................ 282CompressionQuality .......................................................................................................................................................... 283CropOptions.......................................................................................................................................................................... 283DocumentColorSpace ....................................................................................................................................................... 283DocumentType .................................................................................................................................................................... 283DownsampleMethod......................................................................................................................................................... 283ElementPlacement ............................................................................................................................................................. 283EPSPostScriptLevelEnum ................................................................................................................................................. 283EPSPreview ............................................................................................................................................................................ 283ExportType ............................................................................................................................................................................ 284FigureStyleType................................................................................................................................................................... 284FlashExportStyle.................................................................................................................................................................. 284FlashImageFormat.............................................................................................................................................................. 284FlashJPEGMethod ............................................................................................................................................................... 284FontBaselineOption ........................................................................................................................................................... 284FontCapsOption .................................................................................................................................................................. 284FontOpenTypePositionOption....................................................................................................................................... 284FontSubstitutionPolicy ..................................................................................................................................................... 284


GradientType........................................................................................................................................................................ 284ImageColorSpace................................................................................................................................................................ 284InkPrintStatus ....................................................................................................................................................................... 284InkType ................................................................................................................................................................................... 284JavaScriptExecutionMode ............................................................................................................................................... 284Justification ........................................................................................................................................................................... 285KinsokuOrderEnum ............................................................................................................................................................ 285KnockoutState...................................................................................................................................................................... 285LanguageType ..................................................................................................................................................................... 285LayerOrderType................................................................................................................................................................... 285MonochromeCompression ............................................................................................................................................. 285OutputFlattening ................................................................................................................................................................ 286PageMarksTypes.................................................................................................................................................................. 286PathPointSelection............................................................................................................................................................. 286PDFBoxType.......................................................................................................................................................................... 286PDFChangesAllowedEnum ............................................................................................................................................. 286PDFCompatibility................................................................................................................................................................ 286PDFOverprint........................................................................................................................................................................ 286PDFPrintAllowedEnum ..................................................................................................................................................... 286PDFTrimMarkWeight ......................................................................................................................................................... 286PDFXStandard ...................................................................................................................................................................... 286PhotoshopCompatibility .................................................................................................................................................. 286PointType............................................................................................................................................................................... 286PolarityValues ....................................................................................................................................................................... 287PostScriptImageCompressionType .............................................................................................................................. 287PrintArtworkDesignation ................................................................................................................................................. 287PrintColorIntent................................................................................................................................................................... 287PrintColorProfile .................................................................................................................................................................. 287PrintColorSeparationMode ............................................................................................................................................. 287PrinterColorMode ............................................................................................................................................................... 287PrinterPostScriptLevelEnum ........................................................................................................................................... 287PrinterTypeEnum ................................................................................................................................................................ 287PrintFontDownloadMode................................................................................................................................................ 287PrintingBounds .................................................................................................................................................................... 287PrintOrientation................................................................................................................................................................... 287PrintPosition ......................................................................................................................................................................... 287PrintTiling............................................................................................................................................................................... 287RasterLinkState .................................................................................................................................................................... 288RulerUnits .............................................................................................................................................................................. 288SaveOptions.......................................................................................................................................................................... 288ScreenMode .......................................................................................................................................................................... 288StrokeCap............................................................................................................................................................................... 288StrokeJoin .............................................................................................................................................................................. 288StyleRunAlignmentType .................................................................................................................................................. 288SVGCSSPropertyLocation................................................................................................................................................. 288SVGDocumentEncoding................................................................................................................................................... 288SVGDTDVersion ................................................................................................................................................................... 288SVGFontSubsetting ............................................................................................................................................................ 288SVGFontType ........................................................................................................................................................................ 288TabStopAlignment ............................................................................................................................................................. 289TextOrientation.................................................................................................................................................................... 289


TextType................................................................................................................................................................................. 289TracingModeType............................................................................................................................................................... 289Transformation .................................................................................................................................................................... 289TrappingType ....................................................................................................................................................................... 289UserInteractionLevel.......................................................................................................................................................... 289VariableKind.......................................................................................................................................................................... 289ViewRasterType ................................................................................................................................................................... 289ViewVectorType................................................................................................................................................................... 289WariChuJustificationType ................................................................................................................................................ 289ZOrderMethod ..................................................................................................................................................................... 290

8 ExtendScript Tools and Features............................................................................................291The ExtendScript Toolkit......................................................................................................................................................... 291

Configuring the Toolkit window ................................................................................................................................... 292Selecting a debugging target ........................................................................................................................................ 293Selecting scripts................................................................................................................................................................... 294Tracking data ........................................................................................................................................................................ 294The JavaScript console ..................................................................................................................................................... 295The call stack ........................................................................................................................................................................ 296The Script Editor .................................................................................................................................................................. 297

Mouse navigation and selection ............................................................................................................................. 297Keyboard navigation and selection ....................................................................................................................... 297Syntax checking ............................................................................................................................................................ 298

Debugging in the Toolkit ................................................................................................................................................. 298Evaluation in help tips................................................................................................................................................. 298Controlling code execution ...................................................................................................................................... 298Visual indication of execution states ..................................................................................................................... 299Setting breakpoints .................................................................................................................................................... 300

Profiling .................................................................................................................................................................................. 301Dollar ($) Object ........................................................................................................................................................................ 303

Dollar ($) object properties ............................................................................................................................................. 303build......................................................................................................................................................................................... 303buildDate ............................................................................................................................................................................... 303error.......................................................................................................................................................................................... 303flags.......................................................................................................................................................................................... 303global....................................................................................................................................................................................... 303level.......................................................................................................................................................................................... 303locale ....................................................................................................................................................................................... 303localize .................................................................................................................................................................................... 304memCache ............................................................................................................................................................................ 304objects..................................................................................................................................................................................... 304os............................................................................................................................................................................................... 304screens .................................................................................................................................................................................... 304strict ......................................................................................................................................................................................... 304version..................................................................................................................................................................................... 304Dollar ($) object functions ............................................................................................................................................... 304about ....................................................................................................................................................................................... 304bp.............................................................................................................................................................................................. 304clearbp .................................................................................................................................................................................... 304gc .............................................................................................................................................................................................. 304getenv ..................................................................................................................................................................................... 304


list.............................................................................................................................................................................................. 304setbp........................................................................................................................................................................................ 305sleep......................................................................................................................................................................................... 305summary................................................................................................................................................................................. 305write ......................................................................................................................................................................................... 305writeln ..................................................................................................................................................................................... 305

Object statistics ............................................................................................................................................................. 305ExtendScript Reflection Interface ........................................................................................................................................ 307

Reflection Object................................................................................................................................................................. 307Reflection object properties ..................................................................................................................................... 307

description............................................................................................................................................................................. 307help .......................................................................................................................................................................................... 307methods ................................................................................................................................................................................. 307name........................................................................................................................................................................................ 307properties............................................................................................................................................................................... 307

Reflection object functions ....................................................................................................................................... 307find ........................................................................................................................................................................................... 307ReflectionInfo Object......................................................................................................................................................... 308

ReflectionInfo object properties ............................................................................................................................. 308arguments ............................................................................................................................................................................. 308dataType................................................................................................................................................................................. 308defaultValue.......................................................................................................................................................................... 308description............................................................................................................................................................................. 308help .......................................................................................................................................................................................... 309isCollection............................................................................................................................................................................ 309max........................................................................................................................................................................................... 309min............................................................................................................................................................................................ 309name........................................................................................................................................................................................ 309type .......................................................................................................................................................................................... 309

Localizing ExtendScript Strings............................................................................................................................................ 310Variable values in localized strings ............................................................................................................................... 310Enabling automatic localization .................................................................................................................................... 310Locale names ........................................................................................................................................................................ 311Testing localization ............................................................................................................................................................ 312Global localize function .................................................................................................................................................... 313localize .................................................................................................................................................................................... 313

User Notification Helper Functions..................................................................................................................................... 314Global alert function .......................................................................................................................................................... 314alert .......................................................................................................................................................................................... 314Global confirm function.................................................................................................................................................... 315confirm.................................................................................................................................................................................... 315Global prompt function.................................................................................................................................................... 315prompt.................................................................................................................................................................................... 315

Specifying Measurement Values ........................................................................................................................................ 317UnitValue Object ................................................................................................................................................................. 317

UnitValue object constructor ................................................................................................................................... 317UnitValue object properties...................................................................................................................................... 318

baseUnit ................................................................................................................................................................................. 318type .......................................................................................................................................................................................... 318value ........................................................................................................................................................................................ 318

UnitValue object functions........................................................................................................................................ 318


as ............................................................................................................................................................................................... 318convert.................................................................................................................................................................................... 318Converting pixel and percentage values ................................................................................................................... 318Computing with unit values ........................................................................................................................................... 319

Modular Programming Support .......................................................................................................................................... 321Preprocessor directives..................................................................................................................................................... 321#engine name....................................................................................................................................................................... 321#include file ........................................................................................................................................................................... 321#includepath path .............................................................................................................................................................. 322#script name.......................................................................................................................................................................... 322#strict on................................................................................................................................................................................. 322#target name ........................................................................................................................................................................ 322Importing and exporting between scripts................................................................................................................. 322

Operator Overloading ............................................................................................................................................................ 324Application and Namespace Specifiers............................................................................................................................. 325

Application specifiers ........................................................................................................................................................ 325Namespace specifiers ........................................................................................................................................................ 326

Script Locations and Checking Application Installation ............................................................................................. 326

Index .........................................................................................................................................328

1
Introduction
This reference describes the objects and commands in the Adobe® Illustrator® CS2 JavaScript type library. It contains the following sections:

● This introduction, which describes scripting support in Adobe Illustrator CS2, and lists changes to the JavaScript interface since the previous release.

● Scripting Basics, which introduces the fundamental concepts of scripting with JavaScript. If you are new to scripting, be sure to read this chapter.

● Scripting Illustrator, which describes the Illustrator document object model and provides an overview of how to use JavaScript to program Adobe Illustrator CS2.

● Using File and Folder Objects, which describes ExtendScript’s platform-independent representation of files and folders.

● JavaScript Object Reference, which provides a complete reference for all Illustrator DOM objects and commands.

● File and Folder Object Reference, which provides a complete reference for the ExtendScript File and Folder classes.

● Scripting Constants, which lists all enumerations used in the Illustrator type library.

● ExtendScript Tools and Features, which describes ExtendScript’s debugging tools and programming utilities.

What is scripting?A script is a series of commands that tells Illustrator to perform a series of actions. These actions can be simple, and affect only a single, selected object in the current document; or complex, and affect all of the objects in all of your Illustrator documents. The actions might involve only Illustrator, or they might involve other applications, such as word processors, spreadsheets, and database management programs. Many of the tasks you can perform with the Illustrator tools, menus, palettes, and dialog boxes can be performed by a script (a notable exception is third-party plug-ins, which cannot be scripted at this time).

We naturally think of scripting as a way to automate repetitive tasks, but it can also be a creative tool. You can use scripts for creative tasks that would be too difficult or time consuming to do manually. 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 could also write a script that accessed built-in transformation matrix functions to stretch, scale and distort a series of objects. Without scripting, you’ll likely miss out on the creative potential of such labor-intensive techniques.

Scripting isn’t just for computer programmers—it’s for everybody. You don’t need a degree in computer science or mathematics to write scripts that can automate a wide variety of common tasks. If you can read this text, you can write scripts.

The language you use to write scripts depends on the operating system of the platform you’re using: AppleScript for Mac OS®; Visual Basic for Windows®; JavaScript for either platform. Each of these languages is described in a separate manual.

47

Adobe Illustrator CS2JavaScript Scripting Reference Introduction 48

Why use scripting?

Graphic design is a field characterized by creativity, but aspects of the actual work of illustration and page layout are anything but creative. When you think about the work that you do, chances are good you’ll find that you spend most of your time doing the same or similar production tasks, over and over again. In fact, you’ll 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 reduce the time you have available for doing creative work.

Wouldn’t it be great if you had an assistant—one that wouldn’t mind doing some or all of the boring, repetitive tasks for you? With that kind of help, you’d have more time to concentrate on the creative aspects of your work.

With a small investment of time, Illustrator scripting can be the assistant you need. You can start with short, simple scripts that save you a few seconds every day, and move on to scripts that work all night while you’re sleeping.

Think about your work—is there a repetitive task that’s driving you crazy? If so, you’ve identified a candidate for a script. What are the steps involved in performing the task? What are the conditions in which you need to do the task? Once you understand the process you go through to perform the task, you’ll be ready to turn it into a script.

What about actions?

Illustrator actions are different from scripts. An Illustrator action is a series of tasks you have recorded while using the application—menu choices, tool choices, object selection, and other commands. When you “play” an action, Illustrator performs all of the recorded commands.

You record, play, edit, and delete actions using the built-in Actions palette. The “Automating Tasks” chapter in the Adobe Illustrator User Guide covers actions in detail.

With the introduction of scripting for Illustrator, it is important to avoid any confusion about the difference between actions and scripting. Actions and scripts are both ways of automating repetitive tasks, but they work very differently. The following points summarize the key differences.

● 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 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. Scripts are capable of getting information and making decisions and calculations based on the information they receive from Illustrator.

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


Script Support in Adobe Illustrator CS2The Scripts menu supports AppleScript and JavaScript scripts for Mac OS, and VBScript, JavaScript, and Visual Basic for Windows.

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

JavaScript support

All of the Adobe Creative Suite 2 applications, including Adobe Illustrator CS2, use ExtendScript, Adobe’s extended implementation of JavaScript. ExtendScript files are distinguished by the .jsx extension. ExtendScript offers all standard JavaScript features, plus additional features and utilities, such as:

● A debugging environment (the ExtendScript Toolkit)

● A localization utility

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

● Platform-independent file and folder representation

For details of these and additional features, see Using File and Folder Objects and ExtendScript Tools and Features.

Executing scripts

Adobe Illustrator CS2’s interface includes a Scripts menu (File > Scripts) which provides quick and easy access to your scripts. Scripts can be listed directly as menu items, that run when you select them, or you can navigate to and run any script in your file system.

If Illustrator encounters an error during script execution, it displays the error message returned by the script in an error dialog.

Note: It is not possible to execute scripts that contain the do script command from the Scripts menu. Attempting to do so causes an error.

Installing scripts

To install a script in the Scripts menu, place it in the Scripts folder (Illustrator CS2 > Presets > Scripts). The names of the scripts in the Scripts folder, less any file name extension, will be displayed in the Scripts menu. Any number of scripts may be installed in the Scripts menu.

Script Type File Type Extension Platform

AppleScript compiled script OSAS file

.scpt (none)

Mac OS

JavaScript ExtendScript

text .js.jsx

Mac OS & Windows

VBScript text .vbs Windows

Visual Basic executable .exe Windows


Scripts added to the Scripts folder while Illustrator is running will not appear in the Scripts menu until the next time you launch Illustrator.

If you have a large collection of scripts you wish to use, you may use sub-folders in the Scripts folder to help organize the scripts in the Scripts menu. Each subfolder will be displayed as a separate submenu containing the scripts in that subfolder.

Executing other scripts

The Other Scripts item at the end of the Scripts menu (File > Scripts > Other Scripts) allows you to execute scripts which are not installed in the Scripts folder. Selecting Other Scripts displays a file browser dialog which allows you to select a script file for execution. Only files which are of one of the supported file types are displayed in the browse dialog. When you select a script file, it is executed the same way as an installed script.

Startup scripts

On startup,Adobe Illustrator CS2 executes all .jsx files that it finds in the startup folders.

● In Windows, the general startup folder for user-defined scripts is:

%APPDATA%\Adobe\StartupScripts

The Illustrator-specific startup folder is:

Illustrator_install_dir\Startup Scripts

● In Mac OS, the general startup folder for user-defined scripts is:

~/Library/Application Support/Adobe/StartupScripts/

The Illustrator-specific startup folder is:

Illustrator_install_dir/Startup Scripts/

If your script is in the general startup folder, it is also executed by all other Adobe Creative Suite 2 applications at startup. If such a script is meant to be executed only by Illustrator, it must include the ExtendScript #target directive (#target illustrator) or code such as the following:

if( BridgeTalk.appName == "illustrator" ) {//continue executing script

}

For additional details, see Script Locations and Checking Application Installation.

Changes Since Earlier VersionsThe following changes have been made to the JavaScript object model and language support in Adobe Illustrator CS2:

● Updates to PDFSaveOptions, SVGExportOptions, and FlashExportOptions to reflect new capabilities in the corresponding dialogs.

● In earlier version, a script used RasterItems.add() to place a raster file format into a document. In this version, use PlacedItems.add() instead. To embed the art in the document, use the PlacedItem.embed function, which converts it to an embedded RasterItem or art items.


● New scripting capability for converting raster art into vector art, called tracing. The tracing operation reorders the raster art into the source art of a plugin group, and converts it into a group of filled and/or stroked paths that resemble the original image.

● New methods PlacedItems.trace and RasterItems.trace initiate tracing, creating a new PluginItem for the new vector art.

● PluginItem.isTracing is true for the new item, and PluginItem.tracing contains a reference to a new TracingObject object.

● The TracingObject.tracingOption property references a TracingOptions object that collects the parameters used for the tracing operation. You can save tracing options to a preset file, and load previously saved tracing presets, using the TracingOptions.loadFromPreset and TracingOptions.storeToPreset methods.

● New scripting support for underline and strikethrough font styles.

● Support for interapplication communication among Adobe Creative Suite 2 applications through exported ExtendScript functions and interapplication messaging. For details, see the Creative Suite 2 Bridge JavaScript Reference.

● Support for the ExtendScript Toolkit and other ExtendScript features and utilities. See ExtendScript Tools and Features.

2
Scripting Basics
When you use Illustrator, you work with documents and their contents. You create documents, layers, colors, and design elements. You probably think of these things as objects, that you can look at and move around, and they are in fact represented by objects in the Illustrator object model. The Illustrator object model contains documents, layers, colors, and page items—objects that can appear in an Illustrator document.

Automating Illustrator with scripting uses the same object-oriented way of thinking. Each type of object has its own special properties, and the scripting language has ways to look at and change these properties.

This chapter provides a brief introduction to the basic concepts and syntax of the JavaScript scripting language. A bibliography at the end contains references to more complete language guides.

● For more information on the Illustrator object model and specific Illustrator concepts, see ‘Scripting Illustrator’ on page 60.

● For detailed information on the JavaScript Illustrator objects and methods, see ‘JavaScript Object Reference’ on page 74.

Object model conceptsIn object-oriented programming, objects belong to classes and have properties that describe them. You manipulate the objects and their properties using functions in JavaScript. (These are also called methods, and in some scripting languages, commands.) What do these terms mean in this context?

Here’s a way to think about objects and their properties. Imagine that you live in a house that responds to your commands (you can think of this house as technologically advanced, or magical, or both). The house is an object, and its properties might include the number of rooms, the color of the exterior paint, or the date of its construction.

Your house can also contain other objects. Similarly, the objects within the house can also contain smaller objects. Each room, for example, is an object in the house, while each window, door, or appliance is an object inside a room.

Each object can respond to various commands according to its capabilities. Windows and doors, for example, can open or close—but the floor and ceiling cannot. Using scripting, you can talk to each object directly, or you can talk to them as part of the container. You have to be very specific, though—you can’t tell your house to open a window without telling it which window you want to open. So windows, like all other objects, need names or at least a numbering system so you can refer to them specifically. For example, you might say “Tell the house to open the north window of the living room.”

Objects also have properties that describe specific details about them, like color and size. Imagine that the properties of objects in your house can be changed. You might say, “Door, paint yourself blue.” Because your door can respond to the command “paint,” you’ll soon have a door of a different color.

Now let’s apply this object model idea to Illustrator. The Illustrator application is the house, its documents are the rooms, and the objects in your documents are the windows and doors. You can tell Illustrator documents to add and remove objects. You can ask objects to get or change their properties.

52

Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 53

Object classes and containers

Objects with the same properties and behaviors are grouped into “classes.” In the house example, windows and doors belong to their own classes, since they have unique properties, like number of panes for windows or the door style for doors. In Illustrator, every type of graphic object—paths, text, meshes, and so on—belongs to its own class, each with its own set of properties and behaviors. Properties such as VisibleBounds, Width, and Height, for example, are common to all PageItems.

Some types of objects are containers: the house contains rooms. Similarly, a document object might contain text or image objects. There are hierarchies of containment; the house contains a room, which contains a door. In a document that contains text, the text object might further contain sentences, that contain words, that contain characters.

Object inheritance

Objects can share an overall set of properties, but specialize them in different ways. In our house example, houses have various types of openings, including doors and windows. They all share the property of being open or closed, for example, and of having hinges.

You can define a parent class for the most general set of shared properties in such a hierarchy. This is called a superclass. Each specialization can then be a child of that parent, or subclass. The child classes may inherit, or share, the properties of the parent. Windows and doors can be subclasses of an openings class, which contains properties that are common to all types of openings, such as open-state. In Illustrator, PathItems, for example, inherit geometric properties like Width and Height from the PageItem class.

Subclasses often have additional properties that are not shared with their superclass. In our house, both a window and door inherit an open-state property from the opening class, but a window has number-of-panes property which the opening class does not. In Illustrator, PathItems, for example, have the property StrokeColor which is not inherited from the PageItem class.

Object elements or collections

Object collections, in JavaScript, are objects contained within other objects. For example, rooms are elements (or collections) of our house, contained within the house object. In Illustrator, documents are elements of the application object, and page items are elements of a document object.

Object references

The objects in your documents are arranged in a hierarchy like the house object—page items are in layers, which are inside a document, which is inside Illustrator. When you send a message to an Illustrator object, you need to make sure you send it to the right object. To do this, you identify objects by their position in the hierarchy. You might, for example, write the following statement.

Documents(1).Layers(1).PageItems(1)

When you identify an object in this fashion, you’re creating an object reference, to give the script a way of finding the object you want to work with.


Scripting conceptsThis section discusses various basic programming and scripting features and how they are used in the JavaScript language. Adobe Illustrator CS2 uses ExtendScript, which is Adobe’s extended implementation of JavaScript. The terms ExtendScript and JavaScript are generally used interchangeably.

Comments

Comments are a way to add descriptive text to a script. Comments come in handy when you want to document the operation of a script (for yourself or for someone else). The use of comments is the most important technique for good scripting. Comments are where you should leave important notes about the specific operation of a script that might provide valuable help when the script is modified at a later date. The time you save later trying to figure out what the script does may be your own. Comments are ignored by the scripting system as the script executes and cause no run-time speed penalty.

In JavaScript, use // (double slash) to the left of a single-line comment.

// This is a comment

For a multiple-line comment, use /* at the beginning, and */ at the end:

/* This is a commentthat continues ontomore than one line */

Long script lines

In JavaScript, you use a semicolon (;) to separate one statement from another, but this is optional if there is only one statement on a line.

In some cases, individual script lines (single statements) are too long to print on a single line in this guide. JavaScript does not need a line continuation character (as some scripting languages do), so when this happens, the next line is simply indented for readability.

Case sensitivity

The JavaScript language is case sensitive. The name myField is considered different from myfield.

Value types

Values are the data your scripts use to do their work. Most of the time, the values used in your scripts will be numbers or text. The following table shows the basic JavaScript value types:


Variables

Variables are containers for data. A variable might contain a number, a string, a list (or array), or an object reference. Variables have names, and you refer to a variable by its name. To put data into a variable, we assign the data to the variable. The file name of the current Illustrator document or the current date are both examples of data that can be assigned to a variable.

Why not simply enter the value directly in the script rather than using a variable? When you use a value directly the flexibility of script is reduced. By using variables the scripts you write will be reusable in a wider variety of situations. As a script executes, it can assign data to the variables that reflect the state of the current document and selection, for example, and then make decisions based on the content of the variables.

Declaring variables and assigning values

In JavaScript, declare a variable with the keyword var:

var myString;

To assign a value, use the assignment operator, the equal sign. Typically you declare the variable and assign the initial value in the same statement:

var myString = "Hello, World!"

Value type What it is Example:

Boolean Logical true or false true, false

Number Used for all numeric values. JavaScript does not distinguish between integers and floating-point values. All numbers are represented internally a 64-bit IEEE floating-point values.

Do not write integers with leading zeroes. JavaScript interprets a leading 0 as indicating an octal number. A leading 0x indicates a hexadecimal number.

14, 13.9972, -5, 6.023e+23

String A series of text characters. Strings appear inside single or double quotation marks. You can use either type, as long as they match. One string can enclose another by using the opposite type.

"I am a string"’another string’"One string contains ’another string’ in single quotes"

Object A structure that holds a collection of name:value pairs. The names are called the properties of the object. The value of property can be a value of any type, including another object.

For object types defined in Illustrator, use the new function to create new objects. Use the assignment operator (=) to retrieve and change object properties.

Arrays and functions are special types of objects.

{name :"Jane", age: 37, sex: "F"}


Variables can store references to objects. In this case, the variable name is the name of the object, and you access the object’s properties through that name:

var person1 = {name :"Jane", age: 37, sex: "F"};var age1 = person1.age;

Variable naming

Try to use descriptive names for your variables—something like firstPage or corporateLogo, rather than x or c. While it will take a little more time to type the longer names, using them will make your scripts much easier to read. The length of a variable’s name has no effect on the execution speed of your script, so use descriptive names.

You can also give your variable names a standard prefix so that they’ll stand out from the objects, commands, and keywords of your scripting system.

Variable names must be a single word, but you can use internal capitalization (such as myFirstPage) or underscore characters (my_first_page) to create more readable names. Variable names cannot begin with a number, and they cannot contain punctuation or quotation marks.

Operators

Operators perform calculations (addition, subtraction, multiplication, and division) on variables or values and return a result. For example:

docWidth/2

This returns a value equal to half of the content of the variable docWidth. So if docWidth contained the number 20.5, the value returned would be 10.25.

You can also use operators to perform comparisons (equal to, not equal to, greater than, or less than). For example:

docWidth > docHeight

This returns the value true if docWidth is greater than docHeight, or false, if it is not.

Some operators differ between languages For example, JavaScript uses != as the non-equality symbol. The equality operator, ==, compares two values and returns true if they are equal.

The assignment operator, =, sets the value of the leftmost component to be the rightmost component. You can combine this with other arithmetic or logic operators. For example the following statement do the same thing:

a += 5;a = a + 5;

Use the ampersand (&) as the concatenation operator to join two strings.

"Pride " & "and Prejudice."

This returns the string “Pride and Prejudice.”


Functions

If objects are “nouns” and properties are “adjectives” in our scripting systems, then functions are the “verbs”—they’re the parts of the script that make things happen. The type of the object you’re working with determines which methods you can use to manipulate it.

To reuse a particular piece of code, make it a function, then call it by name. Some languages call such functions routines, subroutines, or handlers. In JavaScript, use the function keyword to define a new function (as shown in the example of a conditional statement below).

Conditional statements

If you could speak to Illustrator in the course of a work session, you might say, “If the selected object is a path, then set its stroke width to 12 points.” Conditional statements make decisions—they give your scripts a way to evaluate something (the color of the selected object, or the number of color swatches in the document, or the date) and then act according to the result. Conditional statements generally start with the word if.

The following example checks the number of currently open documents. If no documents are open, the function displays a message to that effect in a dialog box, and if any are open, the function shows the number.

function showDocCount(){var appRef = New Illustrator.Application;var documentCount = appRef.Documents.Count;if documentCount = 0

Window.alert("No Illustrator documents are open");else Window.alert("There are "+documentCount+" documents open.")

}

Control structures

If you could talk to Illustrator, you might say, “Repeat the following procedure twenty times.” In scripting terms, this sort of direction is called a “control structure.” Control structures provide for repetitive processes, or “loops.” The idea of a loop is to repeat some action over and over again, with or without changes each time through the loop, until some condition is met.

JavaScript has a variety of different control structures to choose from. The simplest form of a loop is one that repeats some series of script operations a set number of times.

for counter = 1 to 20 {MsgBox counter

}

A more complicated type of control structure includes conditional logic, so that it loops while or until some condition is true or false.

while flag = false {flag = (MsgBox ("Quit?", vbOKCancel)) = vbCancel

}do {myFunction ();} while flag = false;


Including Other Script Files

ExtendScript for Illustrator provides two file-inclusion directives. One allows you to include another JavaScript script file in this script, and the other specifies a search path for included script files.

The include functionality makes it much easier for Adobe scripters to build, pre-test, and use libraries of pre-made JavaScript functions to enable code reuse and to facilitate sharing with other users.

For example:

@includepath “~/MainScripts;../OtherScripts”@include “scriptname.js”

In this case, Illustrator searches for the file scriptname.js in the following folders, in this order:

● The current working folder (always)

● The MainScripts folder in the current user’s home folder

● The OtherScripts folder one level up from the current working folder

For additional details, see Chapter 7, "ExtendScript Tools and Features."

Testing and troubleshootingThe scripting environment provides tools for monitoring the progress of your script while it is running—which makes it easier for you to track down any problems your script might be encountering or causing.

For JavaScript, the ExtendScript Toolkit provides a view into your scripts. This tool allows you to execute specific statements, step through execution of a script, and set and check the values of script variables interactively.

● The Scripts pane allows you to load and display any script that Illustrator can access in the file system.

● Scripts are displayed in the main Editor pane. You can edit a displayed script, save it, or run it. You can set breakpoints in the script, to stop execution at that point, then step through it statement by statement.

● The JavaScript Console is an output window for your scripts; you can include writeln statements to print messages into this window to help debug your scripts.

● The command line above the Console allows you to enter and execute individual JavaScript statements without saving them in scripts. For example, you can check or set variable values in the current script.

Directive Description

@include script Provides the name of a script to include in the current script, given as an absolute or relative path and file name. The file must exist; if it is not found, a run-time error occurs.

The script is read directly into the current script at the point where this statement is encountered, and is treated in every way as if the script was directly pasted into this file. The inclusion process is done before the current script is evaluated.

@includepath path Provides a search path on which to look for JavaScript files named in subsequent @include statements. The comment containing this directive must be placed above any @include statement to which it should apply.


● The Call Stack pane shows the sequence of function calls during execution. If execution stops because of a breakpoint you have set or because of a run-time error, you can see exactly what sequence of calls has occurred.

For detailed information about using the ExtendScript Toolkit, see Chapter 7, "ExtendScript Tools and Features."

About error handling

Imagine that you’ve written a script that formats the current text selection. What should the script do if the current selection turns out not to be text at all, but a path item? You can add error handling code to your script to respond to conditions other than those you expect it to encounter.

If you have complete control over the situations in which your script will run, there’s no need for you to worry about error handling. If not, however, you’ll have to add some error handling capabilities to your script.

When an error occurs, you can handle it in different ways, depending on what happened. JavaScript allows you to use the throw statement to send information to another part of your program, which can use try, catch, and finally statement blocks for to handle that information. You can throw specific values of any type, or the Error objects that JavaScript generates for run-time errors.

JavaScript ResourcesFor documentation of the JavaScript language and descriptions of how to use it, see any of numerous works on this subject, including the following:

JavaScript: The Definitive Guide, 4th Edition; Flanagan, D.; O’Reilly 2001; ISBN 0-596-00048-0

JavaScript Programmer’s Reference; Wootton, C.; Wrox 2001; ISBN 1-861004-59-1

JavaScript Bible. 5th Edition; Goodman, D. and Morrison, M.; John Wiley and Sons1998; ISBN 0-7645-57432

3
Scripting Illustrator
This chapter describes the Illustrator object model, and provides an overview of how to use JavaScript to program Illustrator CS.

The Illustrator object modelA good understanding of the Illustrator object model will improve your scripting abilities. The figure below shows the containment hierarchy of the object model, starting with the Application object. The Layer and GroupItem classes and all text classes can contain additional objects of the same class which can, in turn, contain additional nested objects.

Illustrator Scripting Object Model

WIthin text, characters, words, paragraphs, and lines are all represented by the TextRange object. For example, a character is a TextRange with a length of 1, and a word is a TextRange that has a space before it. These types of text ranges are collected into collection objects; Characters, Words, Paragraphs, and Lines. For additional text-related objects, see Working with Text and Printing.

In addition to the application-specific object model, ExtendScript provides the File and Folder objects, which give you operating-system-independent access to the file system. For details, see Chapter 4, “Using File and Folder Objects.”

Application

Text Font

Document

Layer

Group Item

Page Item

Path Item

Text Frame

Symbol Item

CompoundPath Item

Graph Item

Mesh ItemBrush

Dataset

Paragraph Style

Character Style

Spot

Swatch

Variable

Symbol

Pattern

Gradient

Graphic Style

View

Path Item

Placed Item

Plugin Item

Raster Item

Path Point

Story

Printers

PPD File List

Print Preset List

PDF Preset List

Flattener Preset List

Ink ListLegacy Text Item

60

Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 61

Referencing and Creating Objects in JavaScript

As the object model diagram shows, all objects are arranged in a hierarchy. To obtain a reference to a specific object you need to navigate the hierarchy. For example, to store a reference to the first path item in the second layer of the active document in the variable pathRef, you would write:

pathRef = app.activeDocument.layers[1].pathItems[0];

All array references in JavaScript are zero-based. The first element of an array is index [0]. You can refer to objects in a collection by index number ( [ i ] ) or by name. For example, you can refer to the “Black” swatch in either of these ways:

app.activeDocument.swatches[4]app.activeDocument.swatches["Black"]

For some types of objects, the name property is writable. The collections are sorted alphabetically by name, so if a script modifies the name of such an object, references to that object by the old name or index can become invalid. These object types include the following:

BrushGradientGraphicStylePatternSwatchSymbolVariable

The following collection objects do not have names; you can only reference them by index.

CharactersGradientStopsLinesParagraphsPathPointsWords

Since all JavaScript scripts are executed from within the Illustrator application, a specific reference to the application object is not required. For example, to assign the active document in Illustrator to the variable frontMostDocument, you would reference the activeDocument property of the application object as follows:

frontMostDocument = app.activeDocument;

There are a number of objects that cannot be obtained by using the hierarchy shown in the object model diagram. You must create these explicitly by defining a variable, using the new object constructor, and assigning objects or values to them. For example, to create the new CMYKColor object, newCMYKColor:

var newCMYKcolor = new CMYKColor();

The following objects must be created:

CMYKColorColorEPSSaveOptionsExportOptionsFlashExportOptionsGIFExportOptionsJPEGExportOptionsPhotoshopExportOptionsPNG8

ExportOptionsPNG24ExportOptionsPS5ExportOptionsSVGFileFolderGradientColorGrayColorIllustratorSaveOptions

MatrixPatternColorPDFOpenOptionsPDFOpenOptionsPDFSaveOptionsRGBColorSpotColorNoColor


The following example creates a new EPSSaveOptions object, assigns values to it, and saves it to a file named \temp\sample.eps in the user’s home folder:

// Create an EPS-save option objectvar fileSpec = new File("~/temp/sample.eps");var newSaveOptions = new EPSSaveOptions();

// Set the options to define how the EPS document is saved by IllustratornewSaveOptions.embedAllFonts = true;newSaveOptions.compatibility = Compatibility.ILLUSTRATOR8;newSaveOptions.preview = EPSPreview.COLORTIFF;

// Save the active documentapp.activeDocument.saveAs(fileSpec, newSaveOptions);

Working with the Selection Object

The document selection object returns either an array of art items or a string of text. To correctly handle the selection, you must first test to see if you have artwork or text. The properties of the art items in the array of artwork items can only be accessed by referencing the individual items in the array.

The following example checks the type of data contained in the selection object, assigns a name to the object, and then displays the typename and toString() values for art items or returns a message that you have selected text.

// Determine if the selection is an array of art item objects or text.// Then display the typename and toString() values for each selected item.

mySelection = app.activeDocument.selection;if (mySelection instanceof Array) {

msgType = "Selection items: ";msgString = "Selection items: ";for (i=0; i<mySelection.length; i++) {

mySelection[i].name = "SelectItem " + i;msgType = msgType + "\nItem[" + i + "] typename is: " +

mySelection[i].typename;msgString = msgString + "\nItem[" + i + "] toString is: " +

mySelection[i].toString();}

}else {

msgType = "You have selected text.";msgString = "You have selected text.";}

alert(msgType);alert(msgString);

Working with paths

Path items include all artwork that contain paths, including rectangles, ellipses, polygons, as well as freeform paths. In Illustrator, every path consists of a series of points; see the following figure.


Path items, as well as path points, can be created and manipulated from a script. Every aspect of a path point can be accessed from scripting, including the anchor and both control points, known as the leftDirection and rightDirection properties.

For more information on working with paths, Bézier curves, and path points, refer to the Illustrator Plug-in Software Development Kit Function Reference. This document is available as part of the Illustrator Software Development Kit (SDK), which can be downloaded from the Adobe Solutions Network (ASN) web site:

http://partners.adobe.com/asn/developer/sdks.html

Working with color

Swatches can be created and manipulated from your scripts. You can also create new patterns, gradients, and spot colors from scripts. Just as in the user interface, percentages (0.0 through 100.0) are used to specify grayscale, individual CMYK values and spot tints. The range 0.0 to 255.0 is used for the individual RGB color values. Special attention should be paid to working with CMYK and RGB color values. Illustrator CS supports only a single color model within each document, either CMYK or RGB. When you specify a CMYK color value in a document that uses the RGB color model, Illustrator will convert the values to RGB and return an RGB color, and vice-versa when specifying RGB colors in a CMYK document. However, there is some data loss during this conversion. Refer to the “Applying Color” chapter in the Adobe Illustrator User Guide for more information on working with color.

Working with symbols and symbol items

Symbols are art items that are stored in the Symbols palette and applied to documents. You can create, delete, and duplicate symbols. When you create symbols, Illustrator adds them to the Symbols Palette for the target document. When you save the document, Illustrator also saves the symbols you created and used in the document.

Symbol items refer to instances of symbols in a document. You can create, delete, and duplicate symbol items. They are “linked” to the symbol definition such that changing the definition of a symbol causes all of the instances of the symbol to change as well. Symbol items are Illustrator art items and therefore can be treated as other art items or page items. In other words, you can rotate, resize, select, lock, hide, and perform other operations on them.

Working with MethodsWhen you work with methods that have multiple parameters, you may omit optional parameters at the end of the parameter list, but you may not omit parameters in the middle of the list. If you do not wish to specify a particular parameter in the middle of the list, you must insert the string “undefined”. The

pathItem

pathPoint

rightDirection

anchor

leftDirection

http://partners.adobe.com/asn/developer/sdks.html


JavaScript interpreter will insert the default parameters wherever “undefined” is specified. For example, to rotate an object 30 degrees and have the fillGradients changed:

myObject.rotate(30, undefined, undefined, true)

Note that you only need to specify “undefined” for the changePositions and changeFillPatterns parameters. You do not have to specify anything for the parameters that follow the changeFillGradients parameter.

Working with Text and PrintingThe following figure shows object model for text.

The text in an Illustrator document is contained inside a story. A document can have multiple stories, and each story has a text range. A story can contain one or more text frames. In this case, multiple text frames are linked together to form a single story. There are special sets of text ranges within a text range that have semantic meanings such as paragraphs, lines, words, and characters.

There are three types of text frame items in Adobe Illustrator: point text, path text, and area text. The kind property of a text frame item is used to determine the type of the text frame item. While all three kinds of text art have some common characteristics, such as an orientation, each kind of text art also has unique characteristics.

All three kinds of text frames have least one text path associated with them. A textPath is not the same as a path art item, but defines the text frame’s position on the artboard and its orientation (horizontal or vertical). Point text is defined completely by the properties of its text frame and associated text path.

For path and area text, text paths are associated with normal path art items. These path art items can be accessed and manipulated to modify the appearance of the associated text frame. If the text frame is path text, it will have a startTValue property which indicates where on the path object the text begins.

Application

Document

Character Style

Paragraph Style

Story

Selection

Paragraphs

Lines

Words

Characters

Text Range

Text Frame

This is anexample ofpoint text.

This is an exam-

ple of area text. Th

is is

an

exam

ple of text on a path


All text art items also have at least one line of text depending on the object’s geometry. A line of text is all of the characters that fit on a single line in the text frame item. Text art will have multiple text lines if it contains hard line breaks or its characters flow to a new line because they do not fit in the width of the text art. Unlike characters, paragraphs, and words, lines can only be created by the Illustrator application.

Refer to the “Using Type” chapter in the Adobe Illustrator User Guide for more information on working with text art.

Content of a Text Range

You can set the content of a text range by passing in a Unicode string known to that particular scripting language. If you know the Unicode value of a character, you can enter it using a C language style backslash escape sequence. If the string starts with a single or double quote, treat the quote as a delimiter. The exact escape characters it recognizes depends on the scripting language being used.

Character Style, Character Attributes, Local Character Attributes

You can change the display properties of a text range by applying an appropriate character style and/or providing local overrides of character attributes at the text and/or paragraph levels.

The character styles are hierarchical, namely you can derive a new character style from another base (parent) character style, although only one level of inheritance is allowed. The root character style is named ‘Normal’, with all character attributes defined and set to default values.

If you query for the character attributes of a text range, Illustrator will derive a fully defined/flattened set of character attributes (because at the root level, ‘Normal’ character style is always fully defined).

This principle also applies the paragraph style, paragraph attributes and local paragraph attributes.

Printing Illustrator Documents

Prior to Illustrator CS, scripters could use the print command, but they could not control any of the print settings. With the new printing model, you can use the full range of Illustrator print capabilities using JavaScript. In many instances, the print features available via scripting are greater than those available through the Illustrator CS print user interface.

Using the print scripting feature, scripters can capture and automate parts of their print workflow, which allows them to focus on other more creative work. Scripting exposes the full capabilities of Illustrator printing, some of which may not be accessible through the normal print user interface.

Illustrator supports at most one print session at any give time because of limitations in the current printing architecture.

When printing, you may provide an options parameter to more fully control the printing process. Illustrator CS supports an extensive list of new printing options, all of which have default values. As a scripter, you can override any one of these printing options. If you override a printing option with an illegal value (such as specifying a printer or paper that does not exist), an error is returned.

The following lists the categories of printing options that you can specify. Each one of these categories is optional. Within each category, default values have been provided for all properties.


The print settings are determined through the following precedence order:

● The print style settings, if any are specified, will override the default print settings.

● The specific printing options (if there are any) will override the print style settings.

To get lists of printers, PPD files, and so on, you must have a document open or an error is returned.

Measurement unitsIllustrator uses points as the unit of measurement for almost all distances, where one inch is equal to 72 points. The one exception is that for values for properties such as kerning, tracking, and the aki properties (used for Japanese text composition), em units are used (see Em Space Units).

Even if you change the current document ruler’s units of measurement, Illustrator still uses points when communicating with your scripts. If your script depends on adding, subtracting, multiplying, or dividing specific measurement values for units other than points, it must perform any unit conversions needed to represent your measurements as points.

For example, to use English measurements such as inch values for coordinates or measurement units, your script will need to multiply all inch values by 72 to convert to points, since there are 72 points in an inch. To use metric measurements such as centimeters, you will need to multiply all centimeter values by 28.346, since there are 28.346 points in a centimeter.

This table shows the conversion formulae for various units of measurement:

Print Option Description

Printer name Name of the selected printer

PPD file name File name of the selected PPD file

Print style name Specifies the printing style

Paper options Specifies the paper name and custom paper sizes

Print job options Options which control things such as number of print copies

Color separation options Specifies the separation mode, ink list, etc.

Page marks options Controls the printing of page marks

Coordinate options Specifies the positioning and scaling of artwork on the media

Font options Controls the fonts used for printing

PostScript® options Controls parameters such as the PostScript Language Level

Color management Sets color profiles

Flattener options Controls the transparency flattening

Unit Conversion formula

centimeters 28.346 points = 1 centimeter

inches 72 points = 1 inch


ExtendScript provides the UnitValue object type, which offers unit conversion utilities. For details, see Specifying Measurement Values.

Em Space Units

One exception to the rule of points being used for all measurements is the use of em units (a traditional typesetting measure) for a few properties such as for kerning and tracking. Values for these properties are measured in thousandths of an em space.

Em units are proportional to the current font size. For example, in a 6-point font, 1 em equals 6 points; in a 10-point font, 1 em equals 10 points. Similarly, a kerning value of 20 em units for a 10-point font would be equivalent to:

(20 units x 10 points) / 1000 units/em = 0.2 points

Page item positioning and dimensions

Illustrator uses simple two-dimensional geometry to record the position of objects in a document. The coordinates used in Illustrator are the same as the “traditional” geometric coordinate system you learned about in school. The horizontal component of a coordinate pair (or “point”) is referred to as “x” and the vertical position is denoted by “y”. You can see these coordinates in the Info palette when you select or create an object in Illustrator.

The zero point (0, 0) for coordinate numbering in Illustrator is in the lower left corner of the document. On the horizontal axis, coordinates to the right of the ruler’s zero point are positive numbers, and on the vertical axis, coordinates above the zero point are positive. The pageOrigin of a document defines the lower left corner of the printable region of the document as a fixed point.

Every object, or page item, in a document has a position described by a fixed point and a width and height. The maximum value allowed for the width or height of a page item is 16348 points.

millimeters 2.834645 points = 1 millimeter

picas 12 points = 1 pica

Qs 0.709 point = 1 Q (1 Q equals 0.23 millimeter)

Unit Conversion formula


Every page item also has three properties that describe the object’s overall extent using fixed rectangles. The geometricBounds of a page item are the rectangular dimensions of the object excluding stroke width. The visibleBounds of a page item are the dimensions of the object including any stroke widths. Finally, the controlBounds define the rectangular dimensions of the object including in- and out- control points.

(0,0)pageOrigin

position

controlBounds

Detail

visibleBounds

geometricBounds

69

4 Using File and Folder Objects

Overview Because path name syntax is very different in Windows, Mac OS and UNIX®, Adobe ExendScript defines the File and Folder objects to provide platform-independent access to the underlying file system. A File Object represents a disk file, a Folder Object represents a directory or folder.

● The Folder object supports file system functionality such as traversing the hierarchy; creating, renaming or removing files; or resolving file aliases.

● The File object supports input/output functions to read or write files.

There are several ways to distinguish between a File and a Folder object. For example:

if (f instanceof File) ...if (typeof f.open == "undefined") ...// Folders do not open

File and Folder objects can be used anywhere that a path name is required, such as in properties and arguments for files and folders. For details about the objects and their properties and methods, see Chapter 6, “File and Folder Object Reference."

Note: When you create two File objects that refer to the same disk file, they are treated as distinct objects. If you open one of them for I/O, the operating system may inhibit access from the other object, because the disk file already is open.

Specifying PathsWhen creating a File or Folder object, you can specify a platform-specific path name, or an absolute or relative path in a platform-independent format known as universal resource identifier (URI) notation. The path stored in the object is always an absolute, full path name that points to a fixed location on the disk.

● Use the toString method to obtain the name of the file or folder as string containing an absolute path name in URI notation.

● Use the fsName property to obtain the platform-specific file name.

Absolute and relative path names

An absolute path name in URI notation describes the full path from a root directory down to a specific file or folder. It starts with one or two slashes (/), and a slash separates path elements. For example, the following describes an absolute location for the file myFile.jsx:

/dir1/dir2/mydir/myFile.jsx

A relative path name in URI notation is appended to the path of the current directory, as stored in the globally-available current property of the Folder class. It starts with a folder or file name, or with one of the special names dot (.) for the current directory, or dot dot (..) for the parent of the current directory. A

Adobe Illustrator CS2JavaScript Scripting Reference Using File and Folder Objects 70

slash (/) separates path elements. For example, the following paths describe various relative locations for the file myFile.jsx:

Relative path names are independent of different volume names on different machines and operating systems, and therefore make your code considerably more portable. You can, for example, use an absolute path for a single operation, to set the current directory in the Folder.current property, and use relative paths for all other operations. You would then need only a single code change to update to a new platform or file location.

Character interpretation in paths

There are some platform differences in how pathnames are interpreted:

● In Windows and Mac OS, path names are not case sensitive. In UNIX, paths are case sensitive.

● In Windows, both the slash (/) and the backslash (\) are valid path element separators.

● In Mac OS, both the slash (/) and the colon (:) are valid path element separators.

If a path name starts with two slashes (or backslashes in Windows), the first element refers to a remote server. For example, //myhost/mydir/myfile refers to the path /mydir/myfile on the server myhost.

URI notation allows special characters in pathnames, but they must specified with an escape character (%) followed by a hexadecimal character code. Special characters are those which are not alphanumeric and not one of the characters:

/ - — . ! ~ * ' ( )

A space, for example, is encoded as %20, so the file name "my file" is specified as "my%20file". Similarly, the character ä is encoded as %E4, so the file name "Bräun" is specified as "Br%E4un".

This encoding scheme is compatible with the global JavaScript functions encodeURI and decodeURI.

The home directory

A path name can start with a tilde (~) to indicate the user's home directory. It corresponds to the platform’s HOME environment variable.

UNIX and Mac OS assign the HOME environment variable according to the user login. In Mac OS, the default home directory is /Users/username. In UNIX, it is typically /home/username or /users/username. Extend Script assigns the home directory value directly from the platform value.

In Windows, the HOME environment variable is optional. If it is assigned, its value must be a Windows path name or a path name referring to a remote server (such as \\myhost\mydir). If the HOME environment variable is undefined, the Extend Script default is the user's home directory, usually the C:\Documents and Settings\username folder.

myFile.jsx./myFile.jsx

In the current directory.

../myFile.jsx In the parent of the current directory.

../../myFile.jsx In the grandparent of the current directory.

../dir1/myFile.jsx In dir1, which is parallel to the current directory.


Note: A script can access many of the folders that are specified with platform-specific variables through static, globally-available Folder class properties; for instance, appData contains the folder that stores application data for all users.

Volume and drive names

A volume or drive name can be the first part of an absolute path in URI notation. The values are interpreted according to the platform.

Mac OS volumes

When Mac OS X starts, the startup volume is the root directory of the file system. All other volumes, including remote volumes, are part of the /Volumes directory. The File and Folder objects use these rules to interpret the first element of a path name:

● If the name is the name of the startup volume, discard it.

● If the name is a volume name, prepend /Volumes.

● Otherwise, leave the path as is.

Mac OS 9 is not supported as an operating system, but the use of the colon as a path separator is still supported and corresponds to URI and to Mac OS X paths as shown in the following table. These examples assume that the startup volume is MacOSX, and that there is a mounted volume Remote.

Windows drives

In Windows, volume names correspond to drive letters. The URI path /c/temp/file normally translates to the Windows path C:\temp\file.

If a drive exists with a name matching the first part of the path, that part is always interpreted as that drive. It is possible for there to be a folder in the root that has the same name as the drive; imagine, for example, a folder C:\C in Windows. A path starting with /c always addresses the drive C:, so in this case, to access the folder by name, you must use both the drive name and the folder name, for example /c/c for C:\C.

If the current drive contains a root folder with the same name as another drive letter, that name is considered to be a folder. That is, if there is a folder D:\C, and if the current drive is D:, the URI path /c/temp/file translates to the Windows path D:\c\temp\file. In this case, to access drive C, you would have to use the Windows path name conventions.

To access a remote volume, use a uniform naming convention (UNC) path name of the form //servername/sharename. These path names are portable, because both Max OS X and UNIX ignore multiple slash characters. Note that in Windows, UNC names do not work for local volumes.

These examples assume that the current drive is D:

URI path name Mac OS 9 path name Mac OS X path name

/MacOSX/dir/file MacOSX:dir:file /dir/file

/Remote/dir/file Remote:dir:file /Volumes/Remote/dir/file

/root/dir/file Root:dir:file /root/dir/file

~/dir/file /Users/jdoe/dir/file


Aliases

When you access an alias, the operation is transparently forwarded to the real file. The only operations that affect the alias are calls to rename and remove, and setting properties readonly and hidden. When a File object represents an alias, the alias property of the object returns true, and the resolve method returns the File or Folder object for the target of the alias.

In Windows, all file system aliases (called shortcuts) are actual files whose names end with the extension .lnk. Never use this extension directly; the File and Folder objects work without it.

For example, suppose there is a shortcut to the file /folder1/some.txt in the folder /folder2. The full Windows file name of the shortcut file is \folder2\some.txt.lnk.

To access the shortcut from a File object, specify the path /folder2/some.txt. Calling that File object’s open method opens the linked file (in /folder1). Calling the File object’s rename method renames the shortcut file itself (leaving the .lnk extension intact).

However, Windows permits a file and its shortcut to reside in the same folder. In this case, the File object always accesses the original file. You cannot create a File object to access the shortcut when it is in the same folder as its linked file.

A script can create a file alias by creating a File object for a file that does not yet exist on disk, and using its createAlias method to specify the target of the alias.

Portability issues

If your application will run on multiple platforms, use relative path names, or try to originate path names from the home directory. If that is not possible, work with Mac OS X and UNIX aliases, and store your files on a machine that is remote to your Windows machine so that you can use UNC names.

As an example, suppose you use the UNIX machine myServer for data storage. If you set up an alias share in the root directory of myServer, and if you set up a Windows-accessible share at share pointing to the same data location, the path name //myServer/share/file would work for all three platforms.

Unicode I/O When doing file I/O, Adobe applications convert 8-bit character encoding to Unicode. By default, this conversion process assumes that the system encoding is used (code page 1252 in Windows or Mac Roman in Mac OS). The encoding property of a File object returns the current encoding. You can set the encoding property to the name of the desired encoding. The File object looks for the corresponding encoder in the operating system to use for subsequent I/O. The name is one of the standard Internet names that are used to describe the encoding of HTML files, such as ASCII, X-SJIS, or ISO-8859-1. For a complete list, see File and Folder Supported Encoding Names.

URI path name Windows path name

/c/dir/file c:\dir\file

/remote/dir/file D:\remote\dir\file

/root/dir/file D:\root\dir\file

~/dir/file C:\Documents and Settings\jdoe\dir\file


A special encoder, BINARY, is provided for binary I/O. This encoder simply extends every 8-bit character it finds to a Unicode character between 0 and 255. When using this encoder to write binary files, the encoder writes the lower 8 bits of the Unicode character. For example, to write the Unicode character 1000, which is 0x3E8, the encoder actually writes the character 232 (0xE8).

The data of some of the common file formats (UCS-2, UCS-4, UTF-8, UTF-16) starts with a special byte order mark (BOM) character (\uFEFF). The File.open method reads a few bytes of a file looking for this character. If it is found, the corresponding encoding is set automatically and the character is skipped. If there is no BOM character at the beginning of the file, open() reads the first 2 KB of the file and checks whether the data might be valid UTF-8 encoded data, and if so, sets the encoding to UTF-8.

To write 16-bit Unicode files in UTF-16 format, use the encoding UCS-2. This encoding uses whatever byte-order format the host platform supports.

When using UTF-8 encoding or 16-bit Unicode, always write the BOM character "\uFEFF" as the first character of the file.

File Error Handling Each object has an error property. If accessing a property or calling a method causes an error, this property contains a message describing the type of the error. On success, the property contains the empty string. You can set the property, but setting it only causes the error message to be cleared. If a file is open, assigning an arbitrary value to the property also resets its error flag.

For a complete list of supported error messages, see File and Folder Error Messages.

5
JavaScript Object Reference
This section presents all of the object classes in the type library. Each class listing includes the following:

● Properties of the class, including value type, read-only status, and an explanation.

● Methods for the class. Constants and value types needed by the method are shown in bold face. Required terms are shown in plain face. All items surrounded by brackets [ ] are optional.

● Notes to explain special issues.

● Sample code to help illustrate the syntax and typical workflow usage of the object class.

Note that these examples are intended to be clear demonstrations of syntax, and do not show the best or most efficient way to construct a JavaScript script. Error checking, for instance, is generally brief or missing. However, the examples can be combined and expanded to make scripts with greater functionality.

74

Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 75

ApplicationThe Adobe Illustrator application object, referenced using the pre-defined global app object, which contains all other Illustrator objects.

Application properties

Property Value type What it is

activeDocument Document object The active (frontmost) document in Illustrator.

browserAvailable boolean Read-only. If true, a web browser is available.

documents Documents collection object

Read-only. The documents in the application.

flattenerPresetsList object Read-only. The list of flattener style names currently available for use.

freeMemory number (long) Read-only. The amount of unused memory (in bytes) within the Adobe Illustrator partition.

name string Read-only. The application’s name (not related to the filename of the application file).

path File object Read-only. The file path to the application.

PDFPresetsList object Read-only. The list of preset PDF-options names available for use.

PPDFileList object Read-only. The list of PPD files currently available for use.

preferences Preference object The preference settings for Illustrator.

printerList Printers collection object

Read-only. The list of installed printers.

printPresetsList object Read-only. The list of preset printing-options names available for use.

scriptingVersion string Read-only. The version of the Scripting plugin.

selection array of objects All of the currently selected objects in the active (frontmost) document.

textFonts TextFonts collection object

Read-only. The installed fonts.

tracingPresetList array of strings Read-only. The list of preset tracing-options names available for use.

typename string Read-only. The class name of the referenced object.

userInteractionLevel UserInteractionLevel What level of interaction with the user should be allowed when handling script commands.


Application methods

version string Read-only. The version of the Adobe Illustrator application.

visible boolean Read-only. If true, the application is visible.


Method Parameter type Returns What it does

beep

()

nothing Alerts the user.

concatenateMatrix

(matrix, secondMatrix)

Matrix objectMatrix object

Matrix object

Joins two matrices together.

concatenateRotationMatrix

(matrix, angle)

Matrix objectnumber (double)

Matrix object

Joins a rotation translation to a transformation matrix.

concatenateScaleMatrix

(matrix [,scaleX] [,scaleY])

objectnumber (double)number (double)

Matrix object

Concatenates a scale translation to a transformation matrix.

concatenateTranslationMatrix

(matrix [,deltaX] [,deltaY])

Matrix objectnumber (double)number (double)

Matrix object

Joins a translation to a transformation matrix.

getIdentityMatrix

()

Matrix object

Returns an identity matrix.

getRotationMatrix

([angle) number (double)Matrix object

Returns a transformation matrix containing a single rotation.

getScaleMatrix

([scaleX] [, scaleY])

number (double)number (double)

Matrix object

Returns a transformation matrix containing a single scale.

getTranslationMatrix

([deltaX] [, deltaY])

number (double)number (double)

Matrix object

Returns a transformation matrix containing a single translation.

invertMatrix

(matrix) Matrix objectMatrix object

Inverts a matrix.

isEqualMatrix

(matrix, secondMatrix)

Matrix objectMatrix object

boolean Checks whether the two matrices are equal.

isSingularMatrix

(Matrix) Matrix objectboolean Checks whether a matrix is

singular and cannot be inverted.


➤ Duplicating the active document

In this script, we use the application property activeDocument to duplicate the current document’s selection before moving it into a new document. This script also demonstrates how to create the new document.

// Duplicate the selection from the active document into a new document.

// To invoke the JavaScript debugger, remove comment delimiters //$.level = 1; debugger;

var newItem;var docSelected = app.activeDocument.selection;

if ( docSelected.length > 0 ) {// Create a new document and move the selected items to it.var newDoc = app.documents.add();if ( docSelected.length > 0 ) {

for ( i = 0; i < docSelected.length; i++ ) {docSelected[i].selected = false;newItem = docSelected[i].duplicate( newDoc,

ElementPlacement.PLACEATEND );}

open

(file [, documentColorSpace] [,options])

File objectDocumentColorSpaceanything

Document object

Opens the file specified by the string with the specified color space and options.

If you open a pre-Illustrator 9 document that contains both RGB and CMYK colors and documentColorSpace is supplied, all colors are converted to the specified color space. If the parameter is not supplied, Illustrator opens a dialog so the user can choose the color space.

quit

()

nothing Quits Illustrator. Note that if the clipboard contains data, Illustrator may show a dialog prompting the user to save the data for other applications.

redraw

()

nothing Forces Illustrator to redraw all its windows.

showPresets

(fileSpec) File objectobject Gets presets from the file.

translatePlaceholderText

(text) stringstring Translates the placeholder text

to regular text (a way to enter Unicode points in hex values).



}else {

docSelected.selected = false;newItem = docSelected.parent.duplicate( newDoc,

ElementPlacement.PLACEATEND );}

}else {

alert( "Please select one or more art objects" );}


BrushA brush in an Illustrator document. Brushes are contained in documents. Additional brushes may be created by the user within Illustrator. You can access brushes within a script, but you cannot create them.

Brush properties

Brush methods

➤ Applying a brush

This example duplicates and groups the current selection, applying the third art style in the document to the items in the group.

// Duplicate and group the current selection,// and apply a brush to the items as a group

if ( app.documents.length > 0 ) {docSelection = app.activeDocument.selection;if ( docSelection.length > 0 ) {

newGroup = app.activeDocument.groupItems.add();

for ( i = 0; i < docSelection.length; i++ ) {newItem = docSelection[i].duplicate();newItem.moveToBeginning( newGroup );

}brush4 = app.activeDocument.brushes[3];brush4.applyTo( newGroup );

}}


name string The name of the brush.

parent Document object

Read-only. The document that contains this brush.



applyTo

(artItem) PageItem objectNothing Applies the brush to a specific art item.


BrushesA collection of brush objects in a document.

Brushes properties

Brushes methods

➤ Counting brushes

This script displays the total number of available brushes in the current document.

// Count all brushes in active document and display total

if ( app.documents.length > 0 ) {numberOfBrushes = app.activeDocument.brushes.length;alert ("There are " + numberOfBrushes

+ " brushes in the active document.");}


length number Read-only. The number of objects in the collection.

parent object Read-only. The document that contains this brushes collection.

typename string Read-only. Read-only. The class name of the referenced object.


getByName

(name) stringBrush object

Gets the first element in the collection with the specified name.

index

(itemKey) string, numberBrush object

Gets an element from the collection.


CharacterAttributesSpecifies the properties of a character contained in a text frame. A CharacterStyle object associates these attributes with a specific text range through its characterAttributes property.

Note: Character attributes do not have default values, and are undefined until explicitly set.

CharacterAttributes properties


akiLeft number (double) The amount of inter-character spacing to be added to the left side of the character, in thousandths of an em (that amount will not compress or expand during full-justification).

akiRight number (double) The amount of inter-character spacing to be added to the right side of the character, in thousandths of an em (that amount will not compress or expand during full-justification).

alignment StyleRunAlignmentType The character alignment type.

alternateGlyphs AlternateGlyphsForm The alternate glyphs form.

autoLeading boolean If true, the automatic leading should be used.

baselineDirection BaselineDirectionType The Japanese text baseline direction.

baselinePosition FontBaselineOption The baseline position of text.

baselineShift number (double) The amount of shift in points of the text baseline.

capitalization FontCapsOption The case of text.

connectionForms boolean If true, the OpenType® connection forms should be used.

contextualLigature boolean If true, the contextual ligature should be used.

discretionaryLigature boolean If true, the discretionary ligature should be used.

figureStyle FigureStyleType Specifies which figure style to use in an OpenType font.

fillColor color object The color of the text fill.


fractions boolean If true, the OpenType fractions should be used.

horizontalScale number (double) The character horizontal scaling factor expressed as a percentage (100 = 100%).

italics boolean If true, the Japanese OpenType font supports italics.

kerningMethod AutoKernType The automatic kerning method to use.

language LanguageType The language of text.

leading number (double) The amount of space between two lines of text, in points.

ligature boolean If true, the ligature should be used.

noBreak boolean If true, line breaks are allowed.

openTypePosition FontOpenTypePositionOption The OpenType baseline position.

ordinals boolean If true, the OpenType ordinals should be used.

ornaments boolean If true, the OpenType ornaments should be used.

overprintFill boolean If true, the fill of the text should be overprinted.

overprintStroke boolean If true, the stroke of the text should be overprinted.

parent object Read-only. The object’s container.

proportionalMetrics boolean If true, the Japanese OpenType font supports proportional glyphs.

rotation number (double) The character rotation angle in degrees.

size number (double) Font size in points.

strikeThrough boolean If true, characters use strike-through style.

strokeColor color object The color of the text stroke.

strokeWeight number (double) Line width of stroke.

stylisticAlternates boolean If true, the OpenType stylistic alternates should be used.



➤ Setting character attributes

// Character Attributes// Create a new document add a simple text item

swash boolean If true, the OpenType swash should be used.

tateChuYokoHorizontal number (long) The Tate-Chu-Yoko horizontal adjustment in points.

tateChuYokoVertical number (long) The Tate-Chu-Yoko vertical adjustment in points.

textFont TextFont object The text font.

titling boolean If true, the OpenType titling alternates should be used.

tracking number (long) The tracking or range kerning amount, in thousandths of an em. An integer.

Tsume number (double) The percentage of space reduction around a Japanese character.

typename string Read-only. The class name of the object.

underline boolean If true, characters are underlined.

verticalScale number (double) Character vertical scaling factor expressed as a percentage (100 = 100%).

wariChuCharactersAfterBreak number (long) Specifies how the characters in Wari-Chu text (an inset note in Japanese text) are divided into two or more lines.

wariChuCharactersBeforeBreak number (long) Specifies how the characters in Wari-Chu text (an inset note in Japanese text) are divided into two or more lines.

wariChuEnabled boolean If true, Wari-Chu is enabled.

wariChuJustification WariChuJustificationType The Wari-Chu justification.

wariChuLineGap number (long) The Wari-Chu line gap.

wariChuLines number (long) The number of Wari-Chu (multiple text lines fit into a space meant for one) lines.

wariChuScale number (double) The Wari-Chu scale.



var docRef = documents.add();var textRef = docRef.textFrames.add();textRef.contents = "I Love Scripting!";textRef.top = 400;textRef.left = 100;

// incrementally increase the size of each charactervar charCount = textRef.textRange.characters.length;var size = 100;for(i=0; i<charCount; i++, size *= 1.2) {

textRef.textRange.characters[i].characterAttributes.horizontalScale= size;

textRef.textRange.characters[i].characterAttributes.verticalScale= size;

}


CharactersA collection of characters (TextRange objects of length 1). The elements are not named; you must access them by index.

Characters properties

Characters methods

➤ Counting characters

This script displays the total number of characters contained in all of the text art items in the current document.

// Count all characters, including whitespace,// in the active document and returns the totalif ( app.documents.length > 0 ) {

var doc = app.activeDocument;var numChars = 0;for ( i = 0; i < doc.textFrames.length; i++ ) {

textArtRange = doc.textFrames[i].contents;numChars += textArtRange.length;

}alert("There are " + numChars

+ " characters, including whitespace, in the document.");}


length number Read-only. The number of characters in the collection.

parent object Read-only. The text art item that contains this character.



add

(contents [,relativeObject] [,insertionLocation])

stringTextFrame objectElementPlacement

TextRange Adds a new character with specified text contents at the specified location in the current document. If location is not specified, adds the new character to the containing text frame after the current text selection or insertion point.

addBefore

(contents) stringTextRange Adds a character before the current text

selection or insertion point.

index

(itemKey) numberTextRange Gets an element from the collection.

removeAll

()

Nothing Deletes all elements in the collection.


CharacterStyleAssociates character attributes with characters. For an example, see CharacterStyles.

CharacterStyle properties

CharacterStyle methods


characterAttributes CharacterAttributes object

Read-only. The character properties for the text range.

name string The character style’s name.




applyTo

(textItem [,clearingOverrides])

objectboolean

Nothing Applies the character style to the text object or objects.

remove

()

Nothing Deletes the object.


CharacterStylesA collection of CharacterStyle objects.

CharacterStyles properties

CharacterStyles methods

➤ Using characters styles

/************************************************************ Create a character style and apply to each text frame. * * Character styles allow you to save and apply set of * * character attributes. ************************************************************/

// Create a new document add a 3 simple text itemsvar docRef = documents.add();var textRef1 = docRef.textFrames.add();textRef1.contents = "Scripting is fun!";textRef1.top = 700;textRef1.left = 50;

var textRef2 = docRef.textFrames.add();textRef2.contents = "Scripting is easy!";textRef2.top = 625;textRef2.left = 100;

var textRef3 = docRef.textFrames.add();textRef3.contents = "Everyone should script!";textRef3.top = 550;textRef3.left = 150;redraw();


length number Read-only. Number of elements in the collection.




add

(name) stringCharacterStyle object

Creates a named character style.

getByName

(name) stringCharacterStyle object

Gets the first element in the collection with the provided name.

index

(itemKey) string, numberCharacterStyle object


removeAll

()

Nothing Deletes all elements in this collection.


// Create a new character stylealert("Create and apply a character style \"BigRed\".");var charStyle = docRef.characterStyles.add("BigRed");

// set character attributesvar charAttr = charStyle.characterAttributes;charAttr.size = 40;charAttr.tracking = -50;charAttr.capitalization = FontCapsOption.ALLCAPS;var redColor = new RGBColor();redColor.red = 255;redColor.green = 0;redColor.blue = 0;charAttr.fillColor = redColor;

// apply to each textFrame in the documentcharStyle.applyTo(textRef1.textRange);charStyle.applyTo(textRef2.textRange);charStyle.applyTo(textRef3.textRange);


CMYKColorA CMYK color specification, used where a color object is required.

If the color space of a document is RGB and you specify the color value for a page item in that document using CMYK, Illustrator will translate the CMYK color specification into an RGB color specification. The same thing happens if the document’s color space is CMYK and you specify colors using RGB. Since this translation can lose information, you should specify colors using the class that matches the document’s actual color space.

CMYKColor properties7

➤ Setting a CMYK color

This script sets the fill color for the frontmost PathItem in the active document to a light shade of purple.

// Set the fill color of the frontmost path item in// the current document to a light purple CMYK color

if ( app.documents.length > 0 && app.activeDocument.pathItems.length > 0) {frontPath = app.activeDocument.pathItems[0];// Set color values for the CMYK objectnewCMYKColor = new CMYKColor();newCMYKColor.black = 0;newCMYKColor.cyan = 30.4;newCMYKColor.magenta = 32;newCMYKColor.yellow = 0;// Use the color object in the path itemfrontPath.filled = true;frontPath.fillColor = newCMYKColor;

}


black number (double) The black color value. Range 0.0–100.0. Default: 0.0

cyan number (double) The cyan color value. Range 0.0–100.0. Default: 0.0

magenta number (double) The magenta color value. Range 0.0–100.0. Default: 0.0


yellow number (double) The yellow color value. Range 0.0–100.0. Default: 0.0


CompoundPathItemA compound path. These objects are composed of multiple intersecting paths, resulting in transparent interior spaces where the component paths overlap. The pathItems property provides access to the paths that make up the compound path.

Paths contained within a compound path or group in a document are returned as individual paths when a script asks for the paths contained in the document. However, paths contained in a compound path or group are not returned when a script asks for the paths in a layer that contains the compound path or group.

All paths within a compound path share property values. Therefore, if you set the value of a property of any one of the paths in the compound path, the properties of all other component paths are updated with the new value.

CompoundPathItem properties


artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.

blendingMode BlendModes The mode used when compositing an object.

controlBounds array of 4 numbers Read-only. The bounds of the object including stroke width and controls.

editable boolean Read-only. If true, this item is editable.

geometricBounds array of 4 numbers Read-only. The bounds of the object excluding stroke width.

height number(double) The height of the compound path item excluding stroke width.

hidden boolean If true, this compound path item is hidden.

isIsolated boolean If true, this object is isolated.

layer Layer object Read-only. The layer to which this compound path item belongs.

left number(double) The position of the left side of the item.

locked boolean If true, this compound path item is locked.

name string The name of this compound path item.

opacity number (double) The opacity of the object. Range: 0.0 to 100.0

parent Layer object or GroupItem object

Read-only. The parent of this object.

pathItems PathItems collection object

Read-only. The path art items in this compound path.

position array of 2 numbers The position of the top left corner of the compound path item excluding stroke width.


CompoundPathItem methods

selected boolean If true, this compound path item is selected.

sliced boolean If true, the item is sliced. Default: false

tags Tags collection object

Read-only. The tags contained in this object.

top number (double) The position of the top of the item.


uRL string The value of the Adobe URL tag assigned to this compound path item.

visibilityVariable Variable object The visibility variable bound to the item.

visibleBounds array of 4 numbers Read-only. The visible bounds of the compound path item including stroke width.

width number (double) The width of the compound path item excluding stroke width.

wrapInside boolean If true, the text frame object should be wrapped inside this object.

wrapOffset number (double) The offset to use when wrapping text around this object.

wrapped boolean If true, wrap text frame objects around this object (text frame must be above the object).

zOrderPosition number (long) Read-only. The position of this art item within the stacking order of the group or layer (Parent) that contains the art item.



duplicate

([relativeObject] [,insertionLocation])

objectElementPlacement

Compound-PathItem object

Creates a duplicate of the selected object.

move

(relativeObject, insertionLocation)


Nothing Moves the object.

remove

()

Nothing Deletes this object.


➤ Selecting paths in a document

This example demonstrates how to select all of the paths in a document that are not part of a compound path or a group by testing the type of the Parent property with a function.

// Select all paths not part of a compound path.if ( app.documents.length > 0 ) {

doc = app.activeDocument;count = 0;if ( doc.pathItems.length > 0 ) {

thePaths = doc.pathItems;numPaths = thePaths.length;for ( i = 0; i < doc.pathItems.length; i++ ) {

pathArt = doc.pathItems[i];if ( pathArt.parent.typename != "CompoundPathItem" ) {

pathArt.selected = true;count++;

}

resize

(scaleX, scaleY [,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,scaleAbout])

number (double)number (double)booleanbooleanbooleanbooleannumber (double)Transformation

Nothing Scales the art item where scaleX is the horizontal scaling factor and scaleY is the vertical scaling factor. 100.0 = 100%.

rotate

(angle [,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,rotateAbout])

number (double)booleanbooleanbooleanbooleanTransformation

Nothing Rotates the art item relative to the current rotation. The object is rotated counter-clockwise if the angle value is positive, clockwise if the value is negative.

transform

(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])

Matrix objectbooleanbooleanbooleanbooleannumber (double)vTransformation

Nothing Transforms the art item by applying a transformation matrix.

translate

([deltaX] [,deltaY] [,transformObjects] [,transformFillPatterns] [,transformFillGradients] [,transformStrokePatterns])

number (double)number (double)booleanbooleanbooleanboolean

Nothing Repositions the art item relative to the current position, where deltaX is the horizontal offset and deltaY is the vertical offset.

zOrder

(zOrderCmd) ZOrderMethod Nothing Arranges the art item’s position

in the stacking order of the group or layer (parent) of this object.



}}

}alert( "Number of pathItems selected = " + count );

➤ Creating and modifying a compound path item

This example demonstrates how to create a new compound path containing three path items, then modifies the stroke of the paths in the compound path. Note that when you modify the properties of a PathItem inside a compound path you affect all paths contained in the compound path. The example also shows how to access swatches in a document by name.

// Create a CoumpoundPath containing 3 PathItems// Set the width and the color of the stroke// (Change affects all paths in the compound path)

if ( app.documents.length > 0 ) {doc = app.activeDocument;newCompoundPath = doc.activeLayer.compoundPathItems.add();

// Create the path itemsnewPath = newCompoundPath.pathItems.add();newPath.setEntirePath( Array( Array(30, 50), Array(30, 100) ) );

newPath = newCompoundPath.pathItems.add();newPath.setEntirePath( Array( Array(40, 100), Array(100, 100) ) );

newPath = newCompoundPath.pathItems.add();newPath.setEntirePath( Array( Array(100, 110), Array(100, 300) ) );

// Set stroke properties of the compound pathnewPath.stroked = true;newPath.strokeWidth = 3.5;newPath.strokeColor = app.activeDocument.swatches["Orange"].color;

}


CompoundPathItemsA collection of CompoundPathItem objects.



➤ Counting compound paths

This example displays the total number of compound paths contained in the first layer of the current document.

// Count all compound paths in layer 1 of current document

if ( app.documents.length > 0 ) {doc = app.activeDocument;numCompoundPaths = doc.layers[0].compoundPathItems.length;alert("There are " + numCompoundPaths

+ " compound paths in the active document.");}



parent object Read-only. The parent of this collection (either a Layer or a GroupItem).



add

()

CompountPathItem object

Creates a new CompoundPathItem.

getByName

(name) stringCompountPathItem object


index

(itemKey) string, numberCompountPathItem object


removeAll

()



DatasetA set of data used for dynamic publishing. A dataset allows you to collect a number of variables and their dynamic data into one object. You must have at least one variable bound to an art item in order to create a dataset. See the class Variable.

Dataset properties

Dataset methods

➤ Using variables and datasets

// Variables and Datasets//// Create two variables (visibility and text)// Create two datasets with different values// Display both datasets//var docRef = documents.add();

// Create 2 variables, Visibility and Textvar itemRef = docRef.pathItems.rectangle(600, 200, 150, 150);var colorRef = new RGBColor;colorRef.red = 255;itemRef.fillColor = colorRef;var visibilityVar = docRef.variables.add();visibilityVar.kind = VariableKind.VISIBILITY;itemRef.visibilityVariable = visibilityVar;

// Create a text variablevar textRef = docRef.textFrames.add();textRef.contents = "Text Variable, dataset 1";textRef.top = 400;textRef.left = 200;var textVar = docRef.variables.add();

Property Value type What is it

name string Then name of the dataset.


Read-only. The name of the object that contains this dataset.



display

()

Nothing Displays the dataset.

remove

()


update

()

Nothing Updates the dataset.


textVar.kind = VariableKind.TEXTUAL;textRef.contentVariable = textVar;redraw();

alert("There are " + docRef.variables.length + " variables.");alert("Creating 2 new datasets.");

// Create the 1st DataSetvar ds1 = docRef.dataSets.add();

// Change data and create a 2nd datasetitemRef.hidden = true;textRef.contents = "Text Variable, dataset 2";redraw();var ds2 = docRef.dataSets.add();

alert("Switching to DataSet 1");ds1.display();redraw();alert("Switching to DataSet 2");ds2.display();redraw();


DatasetsA collection of Dataset objects.

Datasets properties

Datasets methods

Property Value type What is it

length number Read-only. The number of datasets in the collection


Read-only. The name of the object that contains this dataset



add

()

Dataset object

Creates a new dataset object.

getByName

(name) stringDataset object


index

(itemKey) string, numberDataset object


removeAll

()

Nothing Removes all elements in the collection.


DocumentAn Illustrator document. Documents are contained in the Application object.

The default document settings—those properties starting with the word “default”—are global settings that affect the current document. Be sure to modify these default properties only when a document is open. Note that if you set default properties to desired values before creating new objects, you can streamline your scripts, eliminating the need to specify specific properties such as fillColor and stroked that have default properties.

A document’s color space, height, and width can only be set when the document is created. You cannot modify these properties in an existing document. See Application.open for more information on how document color spaces are handled.

Document properties


activeDataset Dataset object The currently opened dataset.

activeLayer Layer object The active layer in the document.

activeView View object Read-only. The document’s current view.

brushes Brushes collection object

Read-only. The brushes contained in the document.

characterStyles CharacterStyles collection object

Read-only. The list of character styles in this document.

compoundPathItems CompoundPathItems collection object

Read-only. The compound path items contained in the document.

cropBox array of 4 numbers The boundary of the document’s cropping box for output, or null if no value has been set.

cropStyle CropOptions The style of the document’s cropping box.

dataSets Datasets collection object

Read-only. The datasets contained in the document.

defaultFillColor color object The color to use to fill new paths if defaultFilled is true.

defaultFilled boolean If true, a new path should be filled.

defaultFillOverprint boolean If true, the art beneath a filled object should be overprinted by default.

defaultStrokeCap StrokeCap Default type of line capping for paths created.

defaultStrokeColor color object The stroke color for new paths if default stroked is true.

defaultStroked boolean If true, a new path should be stroked.


defaultStrokeDashes object Default lengths for dashes and gaps in dashed lines, starting with the first dash length, followed by the first gap length, and so on. Set to an empty object, {}, for solid line.

defaultStrokeDashOffset number (double) The default distance into the dash pattern at which the pattern should be started for new paths.

defaultStrokeJoin StrokeJoin Default type of joints in new paths.

defaultStrokeMiterLimit number (double) When a default stroke join is set to mitered, this property specifies when the join will be converted to beveled (squared-off ) by default. The default miter limit of 4 means that when the length of the point reaches four times the stroke weight, the join switches from a miter join to a bevel join. Range: 1 to 500; a value of 1 specifies a bevel join.

defaultStrokeOverprint boolean If true, the art beneath a stroked object should be overprinted by default.

defaultStrokeWidth number (double) Default width of stroke for new paths.

documentColorSpace DocumentColorSpace Read-only. The color specification system to use for this document’s color space.

fullName File object Read-only. The file associated with the document, which includes the complete path to the file.

geometricBounds array of 4 numbers Read-only. The bounds of the illustration excluding the stroke width of any objects in the document.

gradients Gradients collection object

Read-only. The gradients contained in the document.

graphicStyles GraphicStyles collection object

Read-only. The graphic styles defined in this document.

graphItems GraphItems collection object

Read-only. The graph art items in this document.

groupItems GroupItems collection object

Read-only. The group items contained in the document.

height number (double) Read-only. The height of the document.

inkList object Read-only. The list of inks in this document.

kinsokuSet object Read-only. The Kinsoku set of characters that cannot begin or end a line of Japanese text.



layers Layers collection object

Read-only. The layers contained in the document.

legacyTextItems LegacyTextItems collection object

Read-only. The text frame items in this story.

meshItems MeshItems collection object

Read-only. The mesh art items contained in the document.

mojikumiSet object Read-only. A list of names of predefined Mojikumi sets which specify the spacing for the layout and composition of Japanese text.

name string Read-only. The document’s name (not the complete file path to the document).

outputResolution number (double) Read-only. The current output resolution for the document in dots per inch (dpi).

pageItems PageItems collection object

Read-only. The page items (all art item classes) contained in the document.

pageOrigin array of 2 numbers The zero-point of the page in the document without margins, relative to the overall height and width.

paragraphStyles ParagraphStyles collection object

Read-only. The list of paragraph styles in this document.

parent Application object Read-only. The application that contains this document.

path File object Read-only. The file associated with the document, which includes the complete path to the file.


Read-only. The path items contained in this document.

patterns Patterns collection object

Read-only. The patterns contained in this document.

placedItems PlacedItems collection object

Read-only. The placed items contained in this document.

pluginItems PluginItems collection object

Read-only. The plugin items contained in this document.

printTiles boolean Read-only. If true, this document should be printed as tiled output.

rasterItems RasterItems collection object

Read-only. The raster items contained in this document.

rulerOrigin array of 2 numbers The zero-point of the rulers in the document relative to the bottom left of the document.



rulerUnits RulerUnits Read-only. The default measurement units for the rulers in the document.

saved boolean If true, the document has not been changed since last time it was saved.

selection array of objects References to the objects in this document’s current selection, or null when nothing is selected.

A reference to an insertion point is returned when there is an active insertion point in the contents of a selected text art item. Similarly, a reference to a range of text is returned when characters are selected in the contents of a text art item.

showPlacedImages boolean Read-only. If true, placed images should be displayed in the document.

splitLongPaths boolean Read-only. If true, long paths should be split when printing.

spots Spots collection object

Read-only. The spot colors contained in this document.

stationery boolean Read-only. If true, the file is a stationery file.

stories Stories collection object

Read-only. The story items in this document.

swatches Swatches collection object

Read-only. The swatches contained in this document.

symbolItems SymbolItems collection object

Read-only. The art items in the document linked to symbols.

symbols Symbols collection object

Read-only. The symbols contained in this document.


Read-only. The tags contained in this document.

textFrames TextFrames collection object

Read-only. The text frames contained in this document.

tileFullPages boolean Read-only. If true, full pages should be tiled when printing this document.


useDefaultScreen boolean Read-only. If true, the printer’s default screen should be used when printing this document.

variables Variables collection object

Read-only. The variables defined in this document.



Document methods

variablesLocked boolean If true, the variables are locked.

views Views collection object

Read-only. The views contained in this document.

visibleBounds array of 4 numbers Read-only. The visible bounds of the document, including stroke width of any objects in the illustration.

width number (double) Read-only. The width of this document.



activate

()

Nothing Brings the first window associated with the document to the front.

close

([saveOptions]) SaveOptionsNothing Closes a document using specified

save options.

When you close a document, you should set your document reference to null to prevent your script from accidentally trying to access closed documents.

exportFile

(exportFile, exportFormat[,options])

File objectExportType ExportOptions object

Nothing Exports the document to the specified file using one of the predefined export file formats. The appropriate file extension is automatically appended to the file name, except for Photoshop documents. For these, you must include the file extension (.psd) in the file specification.

exportPDFPreset

(file) File objectNothing Exports the current PDF preset

values to the file.

exportPrintPreset

(file) File objectNothing Exports the current print preset

values to the file.

exportVariables

(fileSpec) File objectNothing Saves datasets into an XML library.

The datasets contain variables and their associated dynamic data.

importCharacterStyles

(fileSpec) File objectNothing Loads the character styles from the

Illustrator file.

importParagraphStyles

(fileSpec) File objectNothing Loads the paragraph styles from the

Illustrator file.


➤ Deselect all objects in the current document

The frontmost document can be referred to as either activeDocument or documents[0].

var docRef = activeDocument;docRef.selection = null;

➤ Close a document

// Close the active document without saving changes.

if ( app.documents.length > 0 ) {aiDocument = app.activeDocument;aiDocument.close( SaveOptions.DONOTSAVECHANGES );aiDocument = null;

}

➤ Create a document with defaults

This example demonstrates how to create a new document with specific default properties.

// Create a document if none exists// Set fill and stroke defaults

if ( app.documents.length == 0 ) {doc = app.documents.add();

}else {

doc = app.activeDocument;}doc.defaultFilled = true;doc.defaultStroked = true;

importPDFPreset

(fileSpec [, replacingPreset])

File objectboolean

Nothing Loads all PDF presets from a file.

importPrintPreset

(printPreset, fileSpec)

stringFile object

Nothing Loads the named print preset from the file.

importVariables

(fileSpec) File objectNothing Imports a library containing

datasets, variables, and their associated dynamic data. Importing variables overwrites existing variables and datasets.

print

([options]) PrintOptions objectNothing Prints the document.

save

()

Nothing Saves the document in it current location.

saveAs

(saveIn[, options])

File objectSaveOptions object

Nothing Saves the document in the specified file as an Illustrator, EPS, or PDF file.



DocumentsA collection of Document objects.

Documents properties

Documents methods

➤ Create a new document

This examples demonstrates how to create a new document with a specific color space.

// Create a document with RGB color space

app.documents.add( DocumentColorSpace.RGB );



parent object Read-only. The parent of this object.



add

([documentColorSpace] [, width] [, height])

DocumentColorSpacenumber (double)number (double)

Document object

Creates a new document using optional parameters and returns a reference to the new document.

getByName

(name) stringDocument object


index

(itemKey) string, numberDocument object



EPSSaveOptionsOptions for saving a document as an Illustrator EPS file, used with the saveAs method. All properties are optional.

EPSSaveOptions properties

➤ Saving to EPS format

This example demonstrates how to save the current document as an Illustrator 8-compatible EPS file using CMYK PostScript with all fonts embedded.

// Save a document to the home folder of the current user// as EPS with specific options

var newFile = new File("~/sample.eps");var saveDoc;if ( app.documents.length == 0 )

saveDoc = app.documents.add();


cmykPostScript boolean If true, use CMYK PostScript.

compatibility Compatibility Specifies the version of the EPS file format to save. Default: ILLUSTRATORCS

compatibleGradientPrinting boolean If true, create a raster item of the gradient or gradient mesh so that PostScript Level 2 printers can print the object. Default: false

embedAllFonts boolean If true, all fonts used by the document should be embedded in the saved file (version 7 or later). Default: false

embedLinkedFiles boolean If true, linked image files are to be included in the saved document.

flattenOuput OutputFlattening How should transparency be flattened for file formats older than Illustrator 9.

includeDocumentThumbnails boolean If true, thumbnail image of the EPS artwork should be included.

overprint PDFOverprint Whether to preserve, discard, or simulate the overprint. Default: PDFOverprint.PRESERVEPDFOVER-PRINT

postScript EPSPostScriptLevelEnum PostScript Language Level to use (Level 1 valid for file format version 8 or older). Default: LEVEL2

preview EPSPreview The format for the EPS preview image.



elsesaveDoc = app.activeDocument;

var saveOpts = new EPSSaveOptions();saveOpts.cmykPostScript = true;saveOpts.compatibility = Compatibility.ILLUSTRATOR8;saveOpts.embedAllFonts = true;

saveDoc.saveAs( newFile, saveOpts );


ExportOptionsFlashOptions for exporting a document as a Macromedia® Flash™ (SWF) file, used with the exportFile method. All properties are optional.

When you export a document, the appropriate file extension is appended automatically. You should not include any file extension in the file specification.

ExportOptionsFlash properties


artBoardClipping boolean If true, the exported image can be clipped to the art board. Default: false

backgroundColor RGBColor object The background color of the exported Flash frames.

backgroundLayers array of Layer objects

A list of layers to be included as the static background of the exported Flash frames.

blendAnimation BlendAnimationType How the blend art objects are animated when exported to Flash frames. Default: NOBLENDANIMATION

compressed boolean If true, the exported file should be exported compressed. Default: false

convertTextToOutlines boolean If true, all text should be converted to outlines. Default: false

curveQuality number (long) The amount of curve information that should be presented. Default: 7

exportStyle FlashExportStyle The style in which the exported data should be created in Flash. Default: ASFLASHFILE

flattenOutput OutputFlattening How transparency should be flattened to preserve appearance or editability on export. Default: PRESERVEAPPEARANCE

frameRate number (double) The display rate in frames per second. Range: 0.01–12.0 Default: 12.0

generateHTML boolean If true, the image should be exported as an HTML file. Default: true

imageFormat FlashImageFormat How should the image in the exported Flash file be compressed. Default: LOSSLESS

jpegMethod FlashJPEGMethod Specifies the JPEG method to use. Default: Standard

jpegQuality number (long) Level of compression to use. Range 1 to 10. Default: 3

layerOrder LayerOrderType The order in which layers are exported to Flash frames. Default: BOTTOMUP


➤ Exporting to Flash format

// Export current document as a Flash file with 150 dpiif ( app.documents.length > 0 ) {

var exportOptions = new ExportOptionsFlash();var type = ExportType.FLASH;var fileSpec = new File("~/sample.swf");exportOptions.resolution = 150;app.activeDocument.exportFile( fileSpec, type, exportOptions );

}

looping boolean If true, the Flash file is set to loop when run. Default: false

readOnly boolean If true, export as read-only file. Default: false

replacing SaveOptions If a file with the same name already exists, should it be replaced. Default: PROMPTTOSAVECHANGES

resolution number (double) The resolution in pixels per inch. Range: 72–2400 Default: 72




ExportOptionsGIFOptions for exporting a document as a GIF file, used with the exportFile method. All properties are optional.


ExportOptionsGIF properties


antiAliasing boolean If true, the exported image should be anti-aliased. Default: true

artBoardClipping boolean If true, the exported image should be clipped to the art board. Default: false

colorCount number (long) The number of colors in the exported image’s color table. Range: 2 to 256 Default: 128

colorDither ColorDitherMethod The method used to dither colors in the exported image. Default: DIFFUSION

colorReduction ColorReductionMethod The method used to reduce the number of colors in the exported image. Default: SELECTIVE

ditherPercent number (long) How much should the colors of the exported image be dithered, where 100.0 is 100%.

horizontalScale number (double) The horizontal scaling factor to apply to the exported image, where 100.0 is 100%. Default: 100.0

infoLossPercent number (long) The level of information loss allowed during compression, where 100.0 is 100%.

interlaced boolean If true, the exported image should be interlaced. Default: false

matte boolean If true, the art board should be matted with a color. Default: true

matteColor RGBColor object The color to use when matting the art board. Default: WHITE

saveAsHTML boolean If true, the exported image should be saved with an accompanying HTML file. Default: false

transparency boolean If true, the exported image should use transparency. Default: true



➤ Export to GIF format

// Save the current document as a GIF file with specific options if ( app.documents.length > 0 ) {

var exportOptions = new ExportOptionsGIF();var type = ExportType.GIF;var fileSpec = new File("~/sample.gif");

exportOptions.antiAliasing = false;exportOptions.colorCount = 64;exportOptions.colorDither = ColorDitherMethod.DIFFUSION;

app.activeDocument.exportFile( fileSpec, type, exportOptions );}

verticalScale number (double) The vertical scaling factor to apply to the exported image, where 100.0 is 100%. Default: 100.0

webSnap number (long) How much should the color table be changed to match the web palette, where 100 is maximum. Default: 0



ExportOptionsJPEGOptions for exporting a document as a JPEG file, used with the exportFile method. All properties are optional.


ExportOptionsJPEG properties

➤ Exporting to JPEG format

This example demonstrates how to export the current document as a JPEG with specific options.

// Export the current document as a JPEG with specific optionsif ( app.documents.length > 0 ) {

var exportOptions = new ExportOptionsJPEG();var type = ExportType.JPEG;var fileSpec = new File("~/sample.jpg");exportOptions.antiAliasing = false;exportOptions.qualitySetting = 70;app.activeDocument.exportFile( fileSpec, type, exportOptions );

}




blurAmount number (double) The amount of blur to apply to the exported image. Range: 0.0 to 2.0 Default: 0.0



matteColor RGBColor object The color to use when matting the art board. Default: white

optimization boolean If true, the exported image should be optimized for web viewing. Default: true

qualitySetting number (long) The quality of the exported image. Range: 0 to 100 Default: 30

saveAsHTML boolean If true, the exported image should be saved with an accompanying HTML file. Default: false


verticalScale number (double) The vertical scaling factor to apply to the exported image. Range: 0.0 to 776.19 Default: 100.0


ExportOptionsPhotoshopOptions for exporting a document as an Adobe Photoshop® file, used with the exportFile method. All properties are optional.


ExportOptionsPhotoshop properties

➤ Export to Photoshop format

This example exports the current document as a Photoshop file with specific options.

// Export the current document as a Photoshop file with layers.

if ( app.documents.length > 0 ) {var exportOptions = new ExportOptionsPhotoshop();var type = ExportType.PHOTOSHOP;var fileSpec = new File("~/sample.psd");exportOptions.resolution = 150;app.activeDocument.exportFile( fileSpec, type, exportOptions );

}



compatibility PhotoshopCompatibility Specifies which Photoshop file format to create. Default: PHOTOSHOP8

editableText boolean If true, text objects should be exported as editable text layers. Default: true

embedICCProfile boolean If true, an ICC profile should be embedded in the exported file. Default: false

imageColorSpace ImageColorSpace The color space of the exported file. Default: RGB

maximumEditability boolean Preserve as much of the original document’s structure as possible when exporting. Default: true

resolution number (double) Resolution of the exported file in dots per inch (dpi). Range: 72.0 to 2400.0 Default: 150.0


warnings boolean If true, a warning dialog should be displayed in case of conflicts in the export settings. Default: true

writeLayers boolean If true, the document layers should be presented in the exported document. Default: true


ExportOptionsPNG8Options for exporting a document as an 8-bit PNG file, used with the exportFile method. All properties are optional.


ExportOptionsPNG8 properties




colorCount number (long) The number of colors in the exported image’s color table. Range: 2 to 256 Default: 128

colorDither ColorDitherMethod The method used to dither colors in the exported image. Default: Diffusion

colorReduction ColorReductionMethod The method used to reduce the number of colors in the exported image. Default: SELECTION

ditherPercent number (long) Specifies ow much the colors of the exported image should be dithered, where 100.0 is 100%. Range: 0 to 100 Default: 88


interlaced boolean If true, the exported image should be interlaced. Default: false


matteColor RGBColor object The color to use when matting the art board. Default: white

saveAsHTML boolean If true, the exported image be saved with an accompanying HTML file. Default: false

transparency boolean If true, the exported image use transparency. Default: true


verticalScale number (double) The vertical scaling factor to apply to the exported image, where 100.0 is 100. Default: 100.0

webSnap number (long) Specifies how much the color table should be changed to match the web palette, where 100 is maximum. Default: 0


➤ Export to PNG8 format

This example exports the current document as a PNG8 file.

// Export the current document as a PNG8 with specific options

if ( app.documents.length > 0 ) {var exportOptions = new ExportOptionsPNG8();var type = ExportType.PNG8;var fileSpec = new File("~/sample.png");

exportOptions.colorCount = 8;exportOptions.transparency = false;app.activeDocument.exportFile( fileSpec, type, exportOptions );

}


ExportOptionsPNG24Options for exporting a document as a 24-bit PNG file, used with the exportFile method. All properties are optional.


ExportOptionsPNG24 properties

➤ Export to PNG24 format

This example exports the current document as a PNG24 file.

// Export the current document as a PNG24 with specific options

if ( app.documents.length > 0 ) {var exportOptions = new ExportOptionsPNG24();var type = ExportType.PNG24;var fileSpec = new File("~/sample.png");exportOptions.antiAliasing = false;exportOptions.transparency = false;exportOptions.saveAsHTML = true;



antiAliasing boolean If true, the exported image be anti-aliased. Default: true

artBoardClipping boolean If true, the exported image be clipped to the art board. Default: false

horizontalScale number (double)

The horizontal scaling factor to apply to the exported image, where 100.0 is 100%. Default: 100.0

matte boolean If true, the art board be matted with a color. Default: true

matteColor RGBColor object

The color to use when matting the art board. Default: white

saveAsHTML boolean If true, the exported image be saved with an accompanying HTML file. Default: false

transparency boolean If true, the exported image use transparency. Default: true


verticalScale number (double)

The vertical scaling factor to apply to the exported image, where 100.0 is 100. Default: 100.0


ExportOptionsSVGOptions for exporting a document as a SVG file, used with the exportFile method. All properties are optional.


ExportOptionsSVG properties


compressed boolean If true, the exported file should be compressed. Default: false

coordinatePrecision number (long) The decimal precision for element coordinate values. Range: 1 to 7 Default: 3

cssProperties SVGCSSPropertyLocation How the CSS properties of the document should be included in the exported file. Default: STYLEATTRIBUTES

documentEncoding SVGDocumentEncoding How the text in the document should be encoded. Default: ASCII

DTD SVGDTDVersion The SVG version to which the file should conform. Default: SVG1_1

embedRasterImages boolean If true, the raster images contained in the document should be embedded in the exported file. Default: false

fontSubsetting SVGFontSubsetting Which font glyphs should be included in the exported file. Default: ALLGLYPHS

fontType SVGFontType The type of font to included in the exported file. Default: CEFFONT

includeFileInfo boolean If true, file information should be saved in the exported file. Default: false

includeVariablesAndDatasets boolean If true, variables and datasets should be saved in the exported file. Default: false

optimizeForSVGViewer boolean If true, the exported file should be optimized for the SVG Viewer. Default: false

preserveEditability boolean If true, Illustrator editing capabilities should be preserved when exporting the document. Default: false


➤ Export to SVG format

This example exports the current document as a SVG file.

// Export the current document as a SVG with specific options

if ( app.documents.length > 0 ) {var exportOptions = new ExportOptionsSVG();var type = ExportType.SVG;var fileSpec = new File("~/sample.svg");exportOptions.embedRasterImages = true;exportOptions.embedAllFonts = false;exportOptions.fontSubsetting = SVGFontSubsetting.GLYPHSUSED;


slices boolean If true, slice data should be exported with the file. Default: false

sVGAutoKerning boolean If true, SVG automatic kerning is allowed in the file. Default: false

sVGTextOnPath boolean If true, the SVG text-on-path construct is allowed in the file. Default: false




GradientA gradient definition contained in a document. Scripts can create new gradients.

Gradient properties

Gradient methods

➤ Creating and applying a gradient

This example shows how you can create a new gradient and apply it as a fill pattern to the frontmost path item.

// Create and apply a gradient as a fill colorif ( app.documents.length > 0 ) {

// Create a color for both ends of the gradientvar startColor = new RGBColor();var endColor = new RGBColor();

startColor.red = 0;startColor.green = 100;startColor.blue = 255;endColor.red = 220;endColor.green = 0;endColor.blue = 100;

// Create a new gradient// A new gradient always has 2 stopsvar newGradient = app.activeDocument.gradients.add();newGradient.name = "NewGradient";newGradient.type = GradientType.LINEAR;

// Modify the first gradient stopnewGradient.gradientStops[0].rampPoint = 30;newGradient.gradientStops[0].midPoint = 60;newGradient.gradientStops[0].color = startColor;


gradientStops GradientStops collection object

Read-only. The gradient stops contained in this gradient.

name string The gradient’s name.

parent Document object Read-only. The document that contains this gradient.

type GradientType The kind of the gradient, either radial or linear.



remove

()

Nothing Removes the referenced object from the document.


// Modify the last gradient stop newGradient.gradientStops[1].rampPoint = 80;newGradient.gradientStops[1].color = endColor;

// construct an Illustrator.GradientColor object referring to the // newly created gradientvar colorOfGradient = new GradientColor();colorOfGradient.gradient = newGradient;

// get first path item, apply new gradient as its fillvar topPath = app.activeDocument.pathItems[0];topPath.filled = true;topPath.fillColor = colorOfGradient;

}


GradientColorA gradient color specification in a Gradient object. A script can create a new gradient color using a reference to an existing gradient in the document. If no existing gradient object is referenced, a default gradient is supplied.

GradientColor properties

➤ Changing a gradient color

This script obtains the gradient called “Black, White Radial” from the current document and changes the color of the first gradient stop. The Gradient “Black, White Radial” is one of the default gradients that appear when you create a new Illustrator document.

// Change the color for the first gradient stop// of a named gradient in the active document

if ( app.documents.length > 0 ) {// Get a reference to the gradient that you want to delete

var bwRadial = app.activeDocument.gradients["White, Black Radial"];// Create the new color

startColor = new RGBColor(); startColor.red = 255; startColor.green = 238; startColor.blue = 98; bwRadial.gradientStops[0].color = startColor;}


angle number (double) The gradient vector angle in degrees. Default: 0.0

gradient Gradient object Reference to the object defining the gradient.

hiliteAngle number (double) The gradient highlight vector angle in degrees.

hiliteLength number (double) The gradient highlight vector length.

length number (double) The gradient vector length.

matrix Matrix object An additional transformation matrix to manipulate the gradient path.

origin array of 2 numbers

The gradient vector origin, the center point of the gradient in this color.



GradientsA collection of Gradient objects in a document.

Gradients properties

Gradients methods

➤ Removing a gradient

This example illustrates how you can remove a gradient from a document.

// Delete the first gradient in the active document

if ( app.documents.length > 0 ) { app.activeDocument.gradients[0].remove();}






add

()

Gradient object Creates a new Gradient object.

getByName

(name) stringGradient object Gets the first element in the collection with

the specified name.

index

(itemKey) string, numberGradient object Gets an element from the collection.

removeAll

()



GradientStopA gradient stop definition that represents a point on a specific gradient defined in the document. Each gradient stop specifies a color change in the containing gradient. See Changing a gradient color for an example.

GradientStop properties

GradientStop methods


color color object The color linked to this gradient stop.

midPoint number (double) The midpoint key value is specified as a percentage from 13.0–87.0.

parent Gradient object Read-only. The gradient that contains this gradient stop.

rampPoint number (double) The location of the color in the blend in a range from 0.0 to 100.0, where 100.0 is 100%.



remove

()



GradientStopsA collection of GradientStop objects in a specific gradient. The elements are not named; you must access them by index.

GradientStops properties

GradientStops methods

➤ Adding a new gradient stop

This example illustrates how to add a new gradient stop to an existing gradient.

// Add a gradient stop to a gradient

if ( app.documents.length > 0 && app.activeDocument.gradients.length > 0 ) {// Get a reference to the gradient to changevar changeGradient = app.activeDocument.gradients[0];// Get a reference to the last gradient stopvar origCount = changeGradient.gradientStops.length;var lastStop = changeGradient.gradientStops[origCount-1]; // add the new gradient stopvar newStop = changeGradient.gradientStops.add();

// Set the values of the new gradient stop. // Move the original last gradient stop a bit to the left and // insert the new gradient stop at the old positionnewStop.rampPoint = lastStop.rampPoint;lastStop.rampPoint = lastStop.rampPoint - 10;// Create a new color to apply to the newly created gradient stop// --a Gray tint value of 70%var newStopColor = new GrayColor();newStopColor.gray = 70.0;newStop.color = newStopColor;

}






add

()

GradientStop object

Creates a new object.

index

(itemKey) numberGradientStop object


removeAll

()

Nothing Deletes all objects in this collection.


GraphicStyleA graphic style. Each graphic style defines a set of appearance attributes that you can apply nondestructively to page items. Graphic styles are contained in documents. Scripts cannot create new graphic styles.

GraphicStyle properties

GraphicStyle methods

➤ Applying a graphic style

This example duplicates and groups the current selection, applying the third graphic style in the document to the items in the group.

// Duplicate each PathItem in a selection, placing it into a// new group, then apply a graphic style to the new group's items

if ( app.documents.length > 0 ) {var doc = app.activeDocument;var selected = doc.selection;

var newGroup = doc.groupItems.add();newGroup.name = "NewGroup";newGroup.move( doc, ElementPlacement.PLACEATEND );

var endIndex = selected.length;for ( i = 0; i < endIndex; i++ ) {

if ( selected[i].typename == "PathItem" )selected[i].duplicate( newGroup, ElementPlacement.PLACEATEND );

}for ( i = 0; i < newGroup.pageItems.length; i++ ) {

doc.graphicStyles[1].applyTo( newGroup.pageItems[i] );}

}


name string The graphic style name.

parent Document object Read-only. The document that contains this graphic style.



applyTo

(artItem) ArtItem objectNothing Applies the art style to a specific art item.

remove

()



GraphicStylesA collection of GraphicStyle objects in a document.

GraphicStyles properties

GraphicStyles methods

➤ Counting graphics styles

This script displays the total number of graphic styles available in the current document.

//Find the number of graphic styles in the active document

if ( app.documents.length > 0 ) {var numberOfStyles = app.activeDocument.graphicStyles.length;alert("There are " + numberOfStyles

+ " graphic styles in the active document.");}


length number Read-only. The number of graphic styles in the document.

parent object Read-only. The document that contains this graphic styles collection.


Method Parameter type: Returns What it does

getByName

(name) stringGroupItem object


index

(itemKey) string, numberGroupItem object


removeAll

()

Nothing Removes all elements in the referenced collection.


GraphItemAny graph artwork object. See example Rotating graph items below.

GraphItem properties


artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout. You cannot set this value to Unknown.


contentVariable Variable object The content variable bound to the graph item.

It is not necessary to set the type of the contentVariable before binding. Illustrator automatically set the type to GRAPH.

controlBounds array of 4 numbers

Read-only. The bounds of the object including stroke width and controls.

editable boolean Read-only. If true, this graph item is editable.

geometricBounds array of 4 numbers

Read-only. The bounds of the object excluding stroke width.

height number (double) The height of the graph item.

hidden boolean If true, this graph item is hidden.


layer Layer object Read-only. The layer to which this graph item belongs.

left number The position of the left side of the graph item.

locked boolean If true, this graph item is locked.

name string The name of this graph item.

opacity number(double) The opacity of the object; the value is between 0.0 and 100.0.



position array of 2 numbers

The position of the top left corner of the graph item.

selected boolean If true, this object is selected.

sliced boolean If true, the graph item is sliced. Default: false


Read-only. The tags contained in this graph item.

top number (double) The position of the top of the graph item.

typename string Read-only. The type of the graph item.


GraphItem methods

uRL string The value of the Adobe URL tag assigned to this graph item.

visibilityVariable Variable object The visibility variable bound to the graph item.

It is not necessary to set the type of the visibilityVariable before binding. Illustrator automatically set the type to VISIBILITY.

visibleBounds array of 4 numbers

Read-only. The visible bounds of the graph item including stroke width.

width number (double) The width of the graph item. Range: 0.0 to 16348.0



wrapped boolean If true, wrap text frame objects around this object. (Text frame must be above the object.)

zOrderPosition number (long) Read-only. The position of this art item within the stacking order of the group or layer (parent) that contains the art item.



duplicate



GraphItem object


move



GraphItem object

Moves the object.

remove

()


resize





rotate




transform


Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation


translate




zOrder





GraphItemsA collection GraphItems objects, which gives you access to all the graph art items in an Illustrator document.

GraphItems properties

GraphItems methods

➤ Rotating graph items

This script gets each graph item in the current document and rotates it 90 degrees.

// Rotate each GraphItem in the current document 90 degrees.

// Verify a document with graph item is openvar ok = false;if (documents.length > 0) { var docRef = activeDocument var iCount = docRef.graphItems.length if( iCount > 0) { ok = true; for (var i=0; i<iCount; i++) { var graphRef = docRef.graphItems[i]; graphRef.selected = true; graphRef.rotate(90); //rotate clockwise 90 degrees } redraw(); }}if(ok == false) { alert("Open a document with some graph items.");}






getByName

(name) stringGraphItems object


index

(itemKey) string, numberGraphItems object


removeAll

()



GrayColorA grayscale color specification, used where a color object is required.

GrayColor properties

➤ Changing a color to gray

This example illustrates how to change the color of the first word in the active document to a shade of gray.

// Set the color of the first word in the active document// to a shade of gray

if ( app.documents.length > 0&& app.activeDocument.textFrames.length > 0 ) {var text = app.activeDocument.textFrames[0].textRange;var firstWord = text.words[0];

// Create the new colorvar textColor = new GrayColor();textColor.gray = 45;firstWord.filled = true;firstWord.fillColor = textColor;

}


gray number (double) The tint of the gray. Range: 0.0 to 100.0, where 0.0 is black and 100.0 is white.



GroupItemA grouped set of art items. Group items can contain all of the same page items that a layer can contain, including other nested groups.

Paths contained in a group or compound path in a document are returned as individual paths when a script asks for the paths contained in the document. However, paths contained in a group or compound path are not returned when a script asks for the paths in a layer which contains the group or compound path.

GroupItem properties



blendingMode BlendModes The blend mode used when compositing an object.

clipped boolean If true, the group is clipped to its first path item.


Read-only. The compound path items contained in this group.





Read-only. The graph items contained in this group.


Read-only. The group items contained in this group.

height number (double) The height of the group item.

hidden boolean If true, this group item is hidden.


layer Layer object Read-only. The layer to which this group item belongs.

left number (double) The position of the left side of the item.

legacyTextItems LegacyTextItems Read-only. The text frame items in this group.

locked boolean If true, this group item is locked.


Read-only. The mesh items contained in this group.

name string The name of this group item.




Read-only. The page items (all art item classes) contained in this group.




Read-only. The path items contained in this group.


Read-only. The placed items contained in this group.


Read-only. The plugin items contained in this group.

position array of 2 numbers The position of the top left corner of the group item.


Read-only. The raster items contained in this group.

selected boolean If true, this group item is selected.

sliced boolean If true, the item sliced. Default: false


Read-only. The symbol item objects in this group.


Read-only. The tags contained in this group.


Read-only. The text art items contained in this group.



uRL string The value of the Adobe URL tag assigned to this group item.


visibleBounds array of 4 numbers Read-only. The visible bounds of the group item including stroke width.

width number (double) The width of the group item.




zOrderPosition number (long) Read-only. The position of this group object within the stacking order of the group or layer (parent) that contains the group object.



GroupItem methods

➤ Modifying all objects in a group

It is easy to modify all of the objects contained in a group. This example demonstrates how to simplify your operations on multiple objects by creating group to contain them.

// Create new art in a separate group to hold new triangle art


duplicate



GroupItem object


move



GroupItem object

Moves the object.

remove

()


resize




rotate




transform




translate




zOrder




if ( app.documents.length > 0 ) {var triangleGroup = app.activeDocument.groupItems.add();

// Create a triangle and add text. All new art are created inside a groupvar trianglePath = triangleGroup.pathItems.add();trianglePath.setEntirePath( Array( Array(100, 100), Array(300, 100),

Array(200, Math.tan(1.0471975) * 100 + 100) ) );trianglePath.closed = true;trianglePath.stroked = true;trianglePath.filled = false;trianglePath.strokeWidth = 3;

var captionText = triangleGroup.textFrames.add();captionText.position = Array(100, 150);captionText.textRange.size = 48;captionText.contents = "A triangle";

var fillColor = new RGBColor;fillColor.red = 255;fillColor.green = 0;fillColor.blue = 0;captionText.characters.fillColor = fillColor;

}


GroupItemsThe collection of grouped art items in a document.

GroupItems properties

GroupItems methods

➤ Importing a PDF as a group item

The following script shows how you can import an PDF document using the createFromFile function. Before running this script you must create a one page PDF file and put it in the location /temp/testfile1.pdf.

// Simulate embedding a placed document.

var embedDoc = new File( "/C/temp/testfile1.pdf"); //any pdf file if ( app.documents.length > 0 && embedDoc.exists ) {

var doc = app.activeDocument;var placed = doc.groupItems.createFromFile( embedDoc );

}






add

()

GroupItem object


createFromFile

(imageFile) File objectGroupItem object

Places an external vector art file as a group item in the document.

getByName

(name) stringGroupItem object


index

(itemKey) string, numberGroupItem object


removeAll

()



IllustratorSaveOptionsOptions for saving a document as an Illustrator file, used with the saveAs method. All properties are optional.

IllustratorSaveOptions properties

➤ Saving with options

// Save active document as Illustrator 8 format// Opacity is flattened with the preserve appearance optionif ( app.documents.length > 0 ) {

var saveOptions = new IllustratorSaveOptions();var ai8Doc = new File("~/Ai8Sample.ai");saveOptions.compatibility = Compatibility.ILLUSTRATOR8;saveOptions.flattenOutput = OutputFlattening.PRESERVEAPPEARANCE;app.activeDocument.saveAs( ai8Doc, saveOptions );

}


compatibility Compatibility Specifies the version of Illustrator file format to create. Default: ILLUSTRATOR12

compressed boolean (Illustrator version 10 or later.) If true, the saved file be compressed. Default: true

embedICCProfile boolean (Illustrator version 9 or later.) If true, the document’s ICC profile should be embedded in the saved file. Default: false

embedLinkedFiles boolean (Illustrator version 7 or later.) If true, the linked image files should be embedded in the saved file; Default: false

flattenOutput OutputFlattening (Versions before Illustrator 9.) How transparency should be flattened for older file format versions. Default: PRESERVEAPPEARANCE

fontSubsetThreshold number (double) (Illustrator version 9 or later.) Include a subset of fonts when less than this percentage of characters is used in the document. Range: 0.0 to 100.0 Default: 100.0

overprint PDFOverprint How to perform overprinting. Default: PRESERVEPDFOVERPRINT

pdfCompatible boolean (Illustrator version 10 or later.) If true, the file should be saved as a PDF compatible file. Default: true



InkAssociates a document ink name with ink information.

Ink properties

InkInfoInk information for printing a document.

InkInfo properties

➤ Getting ink information

// Display the inks from the document inkList in a TextFrame

var docRef = documents.add();var textRef = docRef.textFrames.add();

// assemble a string of the inks in this document var sInks = "";var iLength = activeDocument.inkList.length;

for(var i=0; i<iLength; i++) {sInks += docRef.inkList[i].name;


inkInfo InkInfo object The ink information

name string The ink’s name

typename string Read-only. The class name of the object


angle number (double) The ink’s screen angle in degrees.

customColor color object The color of the custom ink.

density number (double) The neutral density. Minimum: 0.0

dotShape string The dot shape name.

frequency number (double) The ink’s frequency. Minimum: 0.0

kind InkType The ink type.

printingStatus InkPrintStatus The ink printing status.

trapping TrappingType The trapping type.

trappingOrder number (long) The order of trapping for the ink. Minimum: 1



sInks += "\r\t";sInks += "Frequency = " + docRef.inkList[i].inkInfo.frequency;sInks += "\r\t";sInks += "Density = " + docRef.inkList[i].inkInfo.density;sInks += "\r";

}textRef.contents = sInks;textRef.top = 600;textRef.left = 200;redraw();


InsertionPointOne or more insertion points in the contents of a text frame, contained in an InsertionPoints collection in the TextFrame object. This is a TextRange object in which characterOffset indicates the location of the insertion point and length is 0. This subclass does not define any additional properties.

InsertionPointsA collection of InsertionPoint objects.

InsertionPoints properties

InsertionPoints methods

➤ Using insertion points to add spaces

// create a new document and simple text framevar docRef = documents.add();var textRef = docRef.textFrames.add();textRef.contents = "Wouldn't you rather be scripting?";textRef.top = 400;textRef.left = 100;textRef.textRange.characterAttributes.size = 20;redraw();

// Add a space between each character using insertion points.var ip;for(var i=0; i<(textRef.insertionPoints.length); i+=2) { ip = textRef.insertionPoints[i]; ip.characters.add(" ");}






index

(itemKey) string, numberInsertionPoint object

Gets an element from the collection,


LabColorA color specification in the CIE Lab color space, used where a color object is required.

LabColor properties7


a number (double) The a (red-green) color value. Range -128.0–128.0. Default: 0.0

b number (double) The b (yellow-blue) color value. Range -128.0–128.0. Default: 0.0

l number (double) The l (lightness) color value. Range -128.0–128.0. Default: 0.0



LayerA layer in an Illustrator document. Layers may contain nested layers, which are called sublayers in the user interface.

The layer object contains all of the page items in the specific layer as elements. Your script can access page items as elements of either the Layer object or as elements of the Document object. When accessing page items as elements of a layer, only objects in that layer can be accessed. To access page items throughout the entire document, be sure to refer to them as contained by the document.

Layer properties


artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout. You cannot set this value to Unknown.


color RGBColor object The layer’s selection mark color.


Read-only. The compound path items contained in this layer.

dimPlacedImages boolean If true, placed images should be rendered as dimmed in this layer.


Read-only. The graph items contained in this layer.


Read-only. The group items contained in this layer.

hasSelectedArtwork boolean If true, an object in this layer has been selected; set to false to deselect all objects in the layer.


layers Layers collection object

Read-only. The layers contained in this layer.

legacyTextItems LegacyTextItems collection object

Read-only. The legacy text items in this layer.

locked boolean If true, this layer is editable; set to false to lock the layer.


Read-only. The mesh items contained in this layer.

name string The name of this layer.

opacity number (double) The opacity of the layer. Range: 0.0 to 100.0


Read-only. The page items (all art item classes) contained in this layer.

parent Document object or Layer object

Read-only. The document or layer that contains this layer.


Layer methods

➤ Bringing a layer to the front

This example illustrates how to move the bottom layer to the front.

// Move the bottom layer to the top

if (documents.length > 0) {countOfLayers = activeDocument.layers.length;if (countOfLayers > 1) {

// Move the bottom layer to the frontbottomLayer = activeDocument.layers[countOfLayers-1];


Read-only. The path items contained in this layer.


Read-only. The placed items contained in this layer.


Read-only. The plug-in items contained in this layer.

preview boolean If true, this layer should be displayed using preview mode.

printable boolean If true, this layer should be printed when printing the document.


Read-only. The raster items contained in this layer.

sliced boolean If true, the layer item is sliced. Default: false


Read-only. The symbol items contained in the layer.


Read-only. The text art items contained in this layer.


visible boolean If true, this layer is visible.

zOrderPosition number (long) Read-only. The position of this layer within the stacking order of layers in the document.


Method Parameter type Returns What does it do

move



Layer object

Moves the object.

remove

()


zOrder

(ZOrderCmd) ZOrderMethodNothing Arranges the layer’s position in the

stacking order of the containing layer or document (parent) of this object


bottomLayer.zOrder(ZOrderMethod.BRINGTOFRONT);}else {

alert("The active document only has only 1 layer") }}


LayersThe collection of layers in the document.

Layers properties

Layers methods

➤ Finding and deleting layers

This example illustrates how to delete all layers whose name starts with the word “Temp” in all open documents.

// Delete layers whose name begins with "Temp" in all open documents

// loop through all open documentsvar layersDeleted = 0;for ( i = 0; i < app.documents.length; i++ ) {

var targetDocument = app.documents[i];var layerCount = targetDocument.layers.length;// Loop through layers from the back, to preserve index// of remaining layers when we remove onefor ( j = layerCount - 1; j >= 0; j-- ) {

targetLayer = targetDocument.layers[j];var layerName = new String( targetLayer.name );if ( layerName.indexOf("Temp") == 0 ) {

targetDocument.layers[j].remove();layersDeleted++;

} }}alert( "Layer deleted: " + layersDeleted );






add

()

Layer object

Creates a new layer in the document.

getByName

(name) stringLayer object


index

(itemKey) string, numberLayer object


removeAll

()



LegacyTextItemThe text frame items in a story which have not been converted to the new format.

LegacyTextItem properties





converted boolean Read-only. If true, the legacy text item has been updated to a native text frame item.




hidden boolean If true, this item is hidden.


layer Layer object Read-only. The layer to which this item belongs.


locked boolean If true, this item is locked.

name string The name of this item.




position array of 2 numbers The position of the top left corner of the item.

selected boolean If true, this item is selected.



Read-only. The tags contained in this item.



uRL string The value of the Adobe URL tag assigned to this item.



LegacyTextItem methods

visibleBounds array of 4 numbers Read-only. The visible bounds of the item including stroke width.

width number (double) The width of the item.




zOrderPosition number (long) Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.



convertToNative

()

TextFrame object

Create a native text frame from a legacy text item. The original legacy text item is deleted.

duplicate



LegacyTextItem object


move



LegacyTextItem object

Moves the object.

remove

()


resize




rotate





transform




translate




zOrder





LegacyTextItemsA collection of LegacyTextItem objects.

LegacyTextItems properties

LegacyTextItems methods






convertToNative

()

boolean Creates text frames from all legacy text items; the original legacy text items are deleted. Returns true on success.

getByName

(name) stringLegacyTextItem Get the first element in the collection with

the specified name.

index

(itemKey) string, numberLegacyTextItem Gets an element from the collection.

removeAll

()



LinesA collection of TextRange objects representing lines of text in a text frame. The elements are not named; you must access them by index.

Lines properties

Lines methods






index

(itemKey) numberTextRange object


removeAll

()



MatrixA transformation matrix specification, used to transform the geometry of objects. Use it to specify and retrieve matrix information from an Illustrator document or from page items in a document.

Matrices are used in conjunction with the transform method and as a property of a number of objects. A matrix specifies how to transform the geometry of an object. You can generate an original matrix using the Application object methods getTranslationMatrix, getScaleMatrix, or getRotationMatrix.

A Matrix is a record containing the matrix values, not a reference to a matrix object. The matrix commands operate on the values of a matrix record. If a command modifies a matrix, a modified matrix record is returned as the result of the command. The original matrix record passed to the command is not modified.

Matrix properties

➤ Combining matrices to apply multiple transformations

If you need to apply multiple transformations to objects it is more efficient to use the matrix suite than to apply the transformations one at a time. The following script demonstrates how to combine multiple matrices together.

// Apply 2 tranformations to all art in a document using the matrix command.// move art half an inch to the right and 1.5 inch up on the page

if ( app.documents.length > 0 ) {var moveMatrix = app.getTranslationMatrix( 0.5, 1.5 );// Add a rotation to the translation, 10 degrees counter clockwisevar totalMatrix = concatenateRotationMatrix( moveMatrix, 10 );// apply the transformation to all art in the documentvar doc = app.activeDocument;for ( i = 0; i < doc.pageItems.length; i++ ) {

doc.pageItems[i].transform( totalMatrix );}

}


mValueA number (double) Matrix property a.

mValueB number (double) Matrix property b.

mValueC number (double) Matrix property c.

mValueD number (double) Matrix property d.

mValueTX number (double) Matrix property tx.

mValueTY number (double) Matrix property ty.



MeshItemA gradient mesh art item. You cannot create mesh items from a script. However, you can copy an existing mesh item with the duplicate method, then use the one of the move methods to place the copy at the proper location.

MeshItem properties




























MeshItem methods








duplicate



MeshItem object


move



MeshItem object

Moves the object.

remove

()


resize




rotate




transform





➤ Finding and locking mesh items

This script illustrates how to lock all mesh items in the active document.

// Lock all meshItems in the frontMost document

if ( app.documents.length > 0 ) {doc = app.activeDocument;for ( i = 0; i < doc.meshItems.length; i++ ) {

doc.meshItems[i].locked = true;}

}

translate




zOrder





MeshItemsA collection of MeshItem objects.

MeshItems properties

MeshItems methods

➤ Copying mesh items to another document

The following script illustrates how to copy mesh items from one document to another. To run this script you need to have two open documents. One document should contain at least one mesh item, the other document can be empty. Make the empty document the frontmost before running the script.

// Copy all MeshItems from one document to another document

if ( app.documents.length > 0 ) {var srcDoc = documents[0];var locationOffset = 0;var targetDoc = documents.add();

for ( i = 0; i < srcDoc.meshItems.length; i++) {srcItem = srcDoc.meshItems[i];var dupItem = srcDoc.meshItems[i].duplicate( targetDoc,

ElementPlacement.PLACEATEND );

// offset the copied items' position on the y axisdupItem.position = Array( 100, 50 + locationOffset );locationOffset += 50;

}}


length number Read-only. The number of objects in the collection

parent object Read-only. The parent of this object



getByName

(name) stringMeshItem object


index

(itemKey) string, numberMeshItem object


removeAll

()



NoColorRepresents the “none” color. Assigning a NoColor object to the fill or stroke color of an art item is equivalent to setting the filled or stroked property to false.

NoColor properties

➤ Using NoColor to remove a fill color

// Create 2 overlapping objects with different fill colors.// Assign the top object a fill color of “NoColor”// allowing the bottom object to become visible.

// create 2 overlapping objects one blue, one red;var docRef = documents.add();var itemRef1 = docRef.pathItems.rectangle(500, 200, 200, 100);var itemRef2 = docRef.pathItems.rectangle(550, 150, 200, 200);var rgbColor = new RGBColor();rgbColor.red = 255;itemRef2.fillColor = rgbColor;rgbColor.blue = 255;rgbColor.red = 0;itemRef1.fillColor = rgbColor;redraw();

// create a nocolor and assign it to the top objectalert(“Change red object to NoColor.”);var noColor = new NoColor();itemRef2.fillColor = noColor;redraw();


typename string Read-only. The class name of the object


OpenOptionsOptions for opening a document, used with the open method.

OpenOptions properties

➤ Automatically updating legacy text on open

// Open a file with legacy text (AI 10 or older)// Use OpenOptions to automatically update the legacy text.

var fileRef = File.openDialog( "Select an Illlustrator file with legacy text.");if (fileRef != null) {

var optRef = new OpenOptions();optRef.updateLegacyText = true;var docRef = open(fileRef, DocumentColorSpace.RGB, optRef);

}



updateLegacyText boolean Whether to update all legacy text items (from previous versions of Illustrator). Default: false


PageItemsA collection of page item objects. Provides complete access to all the art items in an Illustrator document in the following classes:

CompoundPathItemGraphItemGroupItemMeshItemPathItemPlacedItemRasterItemSymbolItemTextFrame

You can reference page items through the PageItems property in a Document, Layer, or Group. When you access an individual item in one of these collections, the reference is a page item of one of a particular type. For example, if you use PageItems to reference a graph item, the typename value of that object is GraphItem.

PageItems properties

PageItems methods

➤ Getting references to external files in page items

This example illustrates how to obtain all references to external files in the current document. The result is presented in a new Illustrator document. Before running this, open a document that contains one or more linked images.

// Get all file-references using the PageItems object

if ( app.documents.length > 0 ) {var fileReferences = new Array();

var sourceDoc = app.activeDocument;






getByName

(name) stringPageItem object


index

(itemKey) string, numberPageItem object


removeAll

()



PaperAssociates paper information with a paper name. Paper objects are used by Printer objects.

Paper properties

PaperInfoPaper information for use in printing documents.

PaperInfo properties

➤ Finding paper information

// Display the papers and paper sizes available for 2nd printer var docRef = documents.add();var itemRef = docRef.pathItems.rectangle(600, 300, 200, 100);var textRef = docRef.textFrames.add();textRef.top = 600;textRef.left = 50;// get paper objects for 2nd printervar printerRef = printerList[1];textRef.contents = printerRef.name;textRef.contents += " paper list:\r";// get details of each papervar iCount = printerRef.printerInfo.paperSizes.length; for( var i=0; i<iCount; i++ ) {

var paperRef = printerRef.printerInfo.paperSizes[i];var paperInfoRef = paperRef.paperInfo;textRef.contents += paperRef.name;textRef.contents += "\t";textRef.contents += paperInfoRef.height;


name string The paper name.

paperInfo PaperInfo object The paper information.



customPaper boolean If true, it is a custom paper.

height number (double) The paper’s height in points.

imageableArea array of 4 numbers

The imageable area.


width number (double) The paper’s width in points.


textRef.contents += " x ";textRef.contents += paperInfoRef.width;textRef.contents += "\r";

} redraw();


ParagraphAttributesSpecifies the properties and attributes of a paragraph contained in a text frame.

Note: Paragraph attributes do not have default values, and are undefined until explicitly set.

ParagraphAttributes properties


autoLeadingAmount number (double) Auto leading amount expressed as a percentage.

bunriKinshi boolean If true, BunriKinshi is enabled.

burasagariType BurasagariTypeEnum The Burasagari type.

desiredGlyphScaling number (double) Glyph scaling expressed as a percentage.

desiredLetterSpacing number (double) Letter spacing expressed as a percentage.

desiredWordSpacing number (double) Word spacing expressed as a percentage.

everyLineComposer boolean If true, the every-line composer is enabled (as opposed to single-line composer).

firstLineIndent number (double) First line left indent in points.

hyphenateCapitalizedWords boolean If true, hyphenation is enabled for capitalized words.

hyphenation boolean If true, hyphenation is enabled for the paragraph.

hyphenationPreference number (double) Hyphenation preference scale for better spacing (0) or fewer hyphens (1). Range: 0.0 to 1.0

hyphenationZone number (double) The size of the hyphenation zone in points.

justification Justification Paragraph justification.

kinsoku string The Kinsoku Shori name.

kinsokuOrder KinsokuOrderEnum The preferred Kinsoku order.

kurikaeshiMojiShori boolean If true, KurikaeshiMojiShori is enabled.

leadingType AutoLeadingType Auto leading type.

leftIndent number (double) The left indent of margin in points.

maximumConsecutiveHyphens number (long) Maximum number of consecutive hyphenated lines.

maximumGlyphScaling number (double) Maximum glyph scaling expressed as a percentage.


➤ Changing justification in paragraphs

// Add a new document with an area text item // containing 3 paragraphs.var docRef = documents.add();var pathRef = docRef.pathItems.rectangle(600, 200, 200, 400);var textRef = docRef.textFrames.areaText(pathRef);textRef.paragraphs.add("Left justified paragraph.");textRef.paragraphs.add("Center justified paragraph.");textRef.paragraphs.add("Right justified paragraph.");textRef.textRange.characterAttributes.size = 28;

// change the justification of each paragraph// using the paragraph attributes object

maximumLetterSpacing number (double) Maximum letter spacing expressed as a percentage.

maximumWordSpacing number (double) Maximum word spacing expressed as a percentage.

minimumAfterHyphen number (long) Minimum number of characters after a hyphen.

minimumBeforeHyphen number (long) Minimum number of characters before a hyphen.

minimumGlyphScaling number (double) Minimum glyph scaling expressed as a percentage.

minimumHyphenatedWordSize number (long) Minimum number of characters for a word to be hyphenated.

minimumLetterSpacing number (double) Minimum letter spacing expressed as a percentage.

minimumWordSpacing number (double) Minimum word spacing expressed as a percentage.

mojikumi string The Mojikumi name.


rightIndent number (double) Right indent of margin in points.

romanHanging boolean If true, Roman hanging punctuation is enabled.

singleWordJustification Justification Single word justification.

spaceAfter number (double) Spacing after paragraph in points.

spaceBefore number (double) Spacing before paragraph in points.

tabStops TabStopInfo object Tab stop settings.




var paraAttr_0 = textRef.paragraphs[0].paragraphAttributes;paraAttr_0.justification = Justification.RIGHT;var paraAttr_1 = textRef.paragraphs[1].paragraphAttributes;paraAttr_1.justification = Justification.CENTER;var paraAttr_2 = textRef.paragraphs[2].paragraphAttributes;paraAttr_2.justification = Justification.LEFT;


ParagraphsA collection of TextRange objects, with each TextRange representing a paragraph. The elements are not named; you must access them by index.

Paragraphs properties

Paragraphs methods

➤ Counting paragraphs

This script displays the total number of paragraphs contained in all the text frames in the current document.

// Count all paragraphs in current doc and report total.

if ( app.documents.length > 0 ) {doc = app.activeDocument;paragraphCount = 0;for ( i = 0; i < doc.textFrames.length; i++ ) {

paragraphCount += doc.textFrames[i].paragraphs.length;}alert( "Paragraph count: " + paragraphCount );

}






add

(contents [,relativeObject] [,insertionLocation])


TextRange object

Adds a new paragraph with specified text contents at the specified location in the current document. If location is not specified, adds the new paragraph to the containing text frame after the current text selection or insertion point.

addBefore

(contents) stringTextRange object

Adds a new paragraph with specified text contents before the current text selection or insertion point.

index



removeAll

()



ParagraphStyleAssociates character and paragraph attributes with a style name. The style object can be used to apply those attributes to the text in a TextFrame object. See Creating and applying a paragraph style below.

ParagraphStyle properties

ParagraphStyle methods


characterAttributes CharacterAttributes object


name string The paragraph style’s name.

paragraphAttributes ParagraphAttributes object

Read-only. The paragraph properties for the text range.




applyTo

(textItem [,clearingOverrides])

objectboolean

Nothing Applies this paragraph style to the specified text item.

remove

()



ParagraphStylesA collection of ParagraphStyle objects.

ParagraphStyles properties

ParagraphStyles methods

➤ Creating and applying a paragraph style

// Add a new document with an area text item // containing 3 paragraphs.var docRef = documents.add();var pathRef = docRef.pathItems.rectangle(600, 200, 200, 400);var textRef = docRef.textFrames.areaText(pathRef);textRef.paragraphs.add("Left justified paragraph.");textRef.paragraphs.add("Center justified paragraph.");textRef.paragraphs.add("Right justified paragraph.");textRef.textRange.characterAttributes.size = 28;

// change the justification of each paragraph// using the paragraph attributes objectvar paraAttr_0 = textRef.paragraphs[0].paragraphAttributes;paraAttr_0.justification = Justification.RIGHT;var paraAttr_1 = textRef.paragraphs[1].paragraphAttributes;paraAttr_1.justification = Justification.CENTER;var paraAttr_2 = textRef.paragraphs[2].paragraphAttributes;paraAttr_2.justification = Justification.LEFT;

alert("Creating and applying a paragraph style");

// create a new paragraph stylevar paraStyle = docRef.paragraphStyles.add("LeftIndent");






add

(name) stringParagraphStyle object

Creates a named paragraph style.

getByName

(name) stringParagraphStyle object

Get the first element in the collection with the provided name.

index

(itemKey) string, numberParagraphStyle object


removeAll

()



// add some paragraph attributesvar paraAttr = paraStyle.paragraphAttributes;paraAttr.justification = Justification.LEFT;paraAttr.firstLineIndent = 10;

// apply the style to each item in the documentvar iCount = textRef.paragraphs.length;for(var i=0; i<iCount; i++) {

paraStyle.applyTo(textRef.paragraphs[i], true);}redraw();


PathItemSpecifies a path item, which contains PathPoint objects that define its geometry. The PathItem class gives you complete access to paths in Illustrator. The setEntirePath method provides an extremely efficient way to create paths comprised of straight lines.

PathItem properties


area number (double) Read-only. The area of this path in square points. If the area is negative, the path is wound counterclockwise. Self-intersecting paths can contain sub-areas that cancel each other out, which makes this value zero even though the path has apparent area.



clipping boolean If true, this path should be used as a clipping path.

closed boolean If true, this path is closed.



evenodd boolean If true, the even-odd rule should be used to determine insideness.

fillColor color object The fill color of the path.

filled boolean If true, the path be filled.

fillOverprint boolean If true, the art beneath a filled object should be overprinted.


guides boolean If true, this path is a guide object.









note string The note text assigned to the path.




pathPoints PathPoints collection object

Read-only. The path points contained in this path item.

polarity PolarityValues The polarity of the path.


resolution number (double) The resolution of the path in dots per inch (dpi).


selectedPathPoints PathPoints collection object

Read-only. All of the selected path points in the path.


strokeCap StrokeCap The type of line capping.

strokeColor color object The stroke color for the path.

stroked boolean If true, the path should be stroked.

strokeDashes object Dash lengths. Set to an empty object, {}, for a solid line.

strokeDashOffset number (double) The default distance into the dash pattern at which the pattern should be started.

strokeJoin StrokeJoin Type of joints for the path.

strokeMiterLimit number (double) When a default stroke join is set to mitered, this property specifies when the join will be converted to beveled (squared-off ) by default. The default miter limit of 4 means that when the length of the point reaches four times the stroke weight, the join switches from a miter join to a bevel join. A value of 1 specifies a bevel join. Range: 1 to 500 Default: 4

strokeOverprint boolean If true, the art beneath a stroked object should be overprinted.

strokeWidth number (double) Width of the stroke.









PathItem methods









duplicate



MeshItem object


move



MeshItem object

Moves the object.

remove

()


resize




rotate




setEntirePath

(pathPoints) PathPoints objectNothing Sets the path using the

specified anchor points.


➤ Setting colors in a path

This script sets the stroke color and the fill color of the first path in the frontmost document.

// Set the stroke and fill of a PathItem to colors of a randomly selected swatch if ( app.documents.length > 0 && app.activeDocument.pathItems.length > 0 ) {

doc = app.activeDocument;for ( i = 0; i < doc.pathItems.length; i++ ) {

pathRef = doc.pathItems[i];pathRef.filled = true;pathRef.stroked = true;swatchIndex = Math.round( Math.random() * ( doc.swatches.length - 1 )

);pathRef.fillColor = doc.swatches[ swatchIndex ].color;pathRef.strokeColor = doc.swatches[ swatchIndex ].color;

}}

➤ Creating a path from straight lines

This script illustrates the use of the setEntirePath method to create a new path consisting of straight lines.

// Create a new open path consisting of 10 straight linesif ( app.documents.length > 0 ) {

var lineList = new Array(10);for ( i = 0; i < lineList.length; i++ ) {

lineList[i] = new Array(((i - 5) ̂ 2) * 5 +50);}app.defaultStroked = true;newPath = app.activeDocument.pathItems.add();newPath.setEntirePath(lineList);

}

transform




translate




zOrder





PathItemsA collection of PathItem objects. The methods ellipse, polygon, rectangle, roundedRectangle, and star allow you to create complex path items using straightforward parameters. If you do not provide any parameters when calling these methods, default values are used.

PathItems properties

PathItems methods






add

()

PathItem object


ellipse

([top] [,left] [,width] [,height] [,reversed] [,inscribed])

number (double)number (double)number (double)number (double)booleanboolean

PathItem object

Creates a new pathItem in the shape of an ellipse using the supplied parameters.

getByName

(name) stringPathItem object


index

(itemKey) string, numberPathItem object


polygon

([centerX] [,centerY] [,radius] [,sides] [,reversed])

number (double)number (double)number (double)number (long)boolean

PathItem object

Creates a new pathItem in the shape of an polygon using the supplied parameters.

rectangle

(top, left, width, height[,reversed])

number (double)number (double)number (double)number (double)boolean

PathItem object

Creates a new pathItem in the shape of an polygon using the supplied parameters.

removeAll

()



➤ Creating a rectangular path item

This script illustrates how to create a new rectangle in the first layer of the frontmost document.

// Create a basic shape in layer 1 of document 1// and apply a random graphic style to it

var doc = app.documents.add();var artLayer = doc.layers[0];app.defaultStroked = true;app.defaultFilled = true;

var rect = artLayer.pathItems.rectangle( 762.5, 87.5, 425.0, 75.0 );var rndRect = artLayer.pathItems.roundedRectangle(

637.5, 87.5, 425.0, 75.0, 20.0, 10.0 );// Create ellipse, 'reversed' is false, 'inscribed' is truevar ellipse = artLayer.pathItems.ellipse(

512.5, 87.5, 425.0, 75.0, false, true );// Create octagon, and 8-sided polygonvar octagon = artLayer.pathItems.polygon( 300.0, 325.0, 75.0, 8 );// Create a 4 pointed starvar star = artLayer.pathItems.star( 300.0, 125.0, 100.0, 20.0, 4 );

for ( i = 0; i < artLayer.pathItems.length; i++ ) {styleIndex = Math.round(

Math.random() * ( doc.graphicStyles.length - 1 ) );doc.graphicStyles[styleIndex].applyTo( artLayer.pathItems[i] );

}

roundedRectangle

(top, left, width, height[,horizontalRadius][,verticalRadius] [,reversed])

number (double)number (double)number (double)number (double)number (double)number (double)boolean

PathItem object

Creates a new pathItem in the shape of a rectangle with rounded corners using the supplied parameters.

star

([centerX] [,centerY] [,radius] [,innerRadius] [,points] [,reversed])

number (double)number (double)number (double)number (double)number (long)boolean

PathItem object

Creates a new path item in the shape of a star using the supplied parameters.



PathPointA point on a specific path. Each path point is made up of an anchor point (anchor) and a pair of handles (leftDirection and rightDirection).

PathPoint properties

PathPoint methods


anchor array of 2 numbers The position of this point’s anchor point.

leftDirection array of 2 numbers The position of this path point’s in control point.

parent PathItem object Read-only. The path item that contains this path point.

pointType PointType The type of path point, either a curve or a corner. Any point can considered a corner point. Setting the type to a corner forces the left and right direction points to be on a straight line when the user attempts to modify them in the user interface.

rightDirection array of 2 numbers The position of this path point’s out control point.

selected PathPointSelection Are points of this path point selected, and if so, which ones.



remove

()

Nothing Removes the referenced point from the path.


PathPointsA collection of PathPoint objects in a specific path. The elements are not named; you must access them by index.

PathPoints properties

PathPoints methods

➤ Adding a path point to a path

This script illustrates how to add a new path point to an existing path.

// Append a new PathPoint to an existing path// and initialize its anchor and handle points.

if ( app.documents.length > 0 ) {var doc = app.activeDocument;var line = doc.pathItems.add();line.stroked = true;line.setEntirePath( Array( Array(220, 475), Array(375, 300) ) );

// Append another point to the linevar newPoint = doc.pathItems[0].pathPoints.add();

newPoint.anchor = Array(220, 300);newPoint.leftDirection = newPoint.anchor;newPoint.rightDirection = newPoint.anchor;newPoint.pointType = PointType.CORNER;

}






add

()

PathPoint object

Creates a new PathPoint object.

index

(itemKey) numberPathPoint object


removeAll

()



PatternA Illustrator pattern definition contained in a document. Patterns are shown in the Palette, and referenced by PatternColors that define their appearance.

Pattern properties

Pattern methods

PatternsA collection of Pattern objects in a document.

Patterns properties

Patterns methods


name string The pattern name.


Read-only. The document that contains this pattern.



remove

()

Nothing Removes the referenced pattern from the document.

toString

()

string Returns the object type of a referenced object. If the object has a name, also returns the name.






add

()

Pattern object


getByName

(name) stringPattern object



➤ Removing a pattern

This script illustrates how to remove a pattern.

// Remove the last pattern in a document.

if ( app.documents.length > 0 ) {var lastIndex = app.activeDocument.patterns.length - 1;var patternToRemove = app.activeDocument.patterns[lastIndex];var patternName = patternToRemove.name;patternToRemove.remove();// Note after removing Illustrator objects, set the variable that // referenced the removed object to null, since it is now invalid.patternToRemove = null;alert( "Removed pattern \'" + patternName + "\' from document." );

}

index

(itemKey) string, numberPattern object


removeAll

()




PatternColorA pattern color specification. You can create a new pattern color by modifying an existing pattern in the document. Any modification you make to a pattern affects that pattern in the Palette.

PatternColor objects can be used in any property that takes a color object, such as fillColor or strokeColor.

PatternColor properties

➤ Modifying and applying pattern colors

This script illustrates how to modify the first pattern in a document.

// Change patterns used as swatch colors in the frontmost document// (This also changes the patterns in the palette)if ( app.documents.length > 0 && app.activeDocument.pathItems.length > 0 ) {

doc = app.activeDocument;swatchIndex = 0;for ( i = 0; i < doc.swatches.length; i++ ) {

// Get the generic color object of the swatchcurrentSwatch = doc.swatches[i];swatchColor = currentSwatch.color;// Only operate on patternsif ( currentSwatch.color.typename == "PatternColor" ) {

// Change a pattern property


matrix Matrix object Additional transformation arising from manipulating the path.

pattern Pattern object A reference to the pattern object that defines the pattern to use in this color definition.

reflect boolean If true, the prototype should be reflected before filling. Default: false

reflectAngle number (double) The axis around which to reflect, in points. Default: 0.0

rotation number (double) The angle in radians to rotate the prototype pattern before filling. Default: 0.0

scaleFactor array of 2 numbers

The fraction to which to scale the prototype pattern before filling, represented as a point containing horizontal and vertical scaling percentages.

shearAngle number (double) The angle in radians by which to slant the shear. Default: 0.0

shearAxis number (double) The axis to shear with respect to, in points. Default: 0.0

shiftAngle number (double) The angle in radians to which to translate the unscaled prototype pattern before filling. Default: 0.0

shiftDistance number (double) The distance in points to which to translate the unscaled prototype pattern before filling. Default: 0.0



currentSwatch.color.rotation = 10;swatchIndex = i;

}}

// Apply the last pattern color swatch to the frontmost pathfirstPath = app.activeDocument.pathItems[0];firstPath.filled = true;firstPath.fillColor = doc.swatches[swatchIndex].color;

}


PDFFileOptionsOptions for opening a PDF file, used with the open method. All properties are optional.

PDFFileOptions properties

➤ Opening a PDF with options

// Set PDFFileOptions to open page 2

var pdfOptions = preferences.PDFFileOptions;pdfOptions.pageToOpen = 2;pdfOptions.pDFCropToBox = PDFBoxType.PDFBOUNDINGBOX;

// Open a file using these preferencesvar fileRef = File.openDialog( "Select a multi-page PDF file to open."); if (fileRef != null) { var docRef = open(fileRef, DocumentColorSpace.RGB); }


pageToOpen number (long) What page should be used when opening a multipage document. Default: 1


pDFCropToBox PDFBoxType Which box should be used when placing a multipage document. Default: PDFMediaBox



PDFSaveOptionsOptions for saving a document as an Adobe PDF file, used with the saveAs method. All properties are optional.

PDFSaveOptions properties


acrobatLayers boolean Create Acrobat® layers from top-level layers. Acrobat 6 only. Default: false

bleedLink boolean Link 4 bleed values. Default: true

bleedOffsetRect array of 4 numbers The bleed offset rectangle.

colorBars boolean Draw color bars. Default: false

colorCompression CompressionQuality The type of color bitmap compression used. Default: None

colorConversionID ColorConversion The PDF color conversion policy. Default: None

colorDestinationID ColorDestination The conversion target for color conversion. Default: None

colorDownsampling number (double) The color downsampling resolution in dots per inch (dpi). If 0, no downsampling is performed. Default: 150.0

colorDownsamplingImageThreshold number (double) Downsample if the image’s resolution is above this value. Default: 225.0

colorDownsamplingMethod DownsampleMethod How color bitmap images should be resampled. Default: NODOWNSAMPLE

colorProfileID ColorProfile The color profile to include. Default: None

colorTileSize number (long) Tile size when compressing with JPEG2000. Default: 256

compatibility PDFCompatibility The version of the Acrobat file format to create. Default: Acrobat6


compressArt boolean If true, the line art and text should be compressed. Default: true

documentPassword string A password string to open the document. Default: no string

enableAccess boolean If true, enable accessing 128-bit. Default: true

enableCopy boolean If true, enable copying of text 128-bit. Default: true

enableCopyAccess boolean If true, enable copying and accessing 40-bit. Default: true

enablePlainText boolean If true, enable plaintext metadata 128-bit. Available only for Acrobat 6. Default: false

flattenerOptions PrintFlattenerOptions object

The printing flattener options.

flattenerPreset string The transparency flattener preset name.

fontSubsetThreshold number (double) Include a subset of fonts when less than this percentage of characters is used in the document. Valid for Illustrator 9 file format. Range: 0.0 to 100.0 Default: 100.0

generateThumbnails boolean If true, thumbnail images are generated with the saved file. Default: true

grayscaleCompression CompressionQuality Quality of grayscale bitmap compression. Default: None

grayscaleDownsampling number (double) Downsampling resolution in dots per inch (dpi). If 0, no downsampling is performed. Default: 150.0

grayscaleDownsamplingImageThreshold number (double) Downsample if the image’s resolution is above this value. Default: 225.0



grayscaleDownsamplingMethod DownsampleMethod How grayscale bitmap images should be resampled Default: NODOWNSAMPLE

grayscaleTileSize number (long) Tile size when compressing with JPEG2000. Default: 256

monochromeCompression MonochromeCompression Type of monochrome bitmap compression used. Default: None

monochromeDownsampling number (double) Downsampling resolution in dots per inch (dpi). If 0, no downsampling is performed. Default: 300

monochromeDownsamplingImageThreshold number (double) Downsample if the image’s resolution is above this value. Default: 450.0

monochromeDownsamplingMethod DownsampleMethod How monochrome bitmap images should be resampled. Default: NODOWNSAMPLE

offset number (double) Custom offset in points for using the custom paper. Default: 0.0

optimization boolean If true, the PDF document should be optimized for fast web viewing. Default: false

outputCondition string An optional comment to add to the PDF file, describing the intended printing condition. Default: not included

outputConditionID string The name of a registered printing condition. Default: not included

pageInformation boolean If true, raw page information. Default: false

pageMarksType PageMarksTypes The page marks style. Default: Roman

pDFAllowPrinting PDFPrintAllowedEnum PDF security printing permission. Default: PRINT128HIGHRESOLUTION

pDFChangesAllowed PDFChangesAllowedEnum Security changes allowed. Default: CHANGE128ANYCHANGES



➤ Saving to PDF format

This script illustrates how to save the frontmost document as PDF.

// Save the current document as PDF// (If the document has never been saved as an AI document// doc.path is null.)if ( app.documents.length > 0 ) {

pDFPreset string Name of PDF preset to use.

pDFXStandard PDFXStandard The PDF standard with which this document complies. Default: PDFXNONE

pDFXStandardDescription string A description of the PDF standard from the selected preset.

permissionPassword string A password string to restrict editing security settings. Default: no string

preserveEditability boolean If true, Illustrator editing capabilities should be preserved when saving the document. Default: true

printerResolution number (double) Flattening printer resolution. Default: 800.0

registrationMarks boolean If true, draw registration marks. Default: false

requireDocumentPassword boolean Require a password to open the document. Default: false

requirePermissionPassword boolean Use a password to restrict editing security settings. Default: false

trapped boolean If true, manual trapping has been prepared for the document. Default: false

trimMarks boolean Draw trim marks. Default: false

trimMarkWeight PDFTrimMarkWeight The trim mark weight. Default: TRIMMARKWEIGHT0125


viewAfterSaving boolean View PDF after saving. Default: false



doc = app.activeDocument;var saveName = new File ( doc.path + "/" + doc.name );

saveOpts = new PDFSaveOptions();saveOpts.compatibility = PDFCompatibility.ACROBAT5;saveOpts.generateThumbnails = true;saveOpts.preserveEditability = true;doc.saveAs( saveName, saveOpts );

}


PhotoshopFileOptionsOptions for opening a Photoshop file, used with the open method. All properties are optional.

PhotoshopFileOptions properties

➤ Opening a Photoshop file

// PhotoshopFileOptions// Open a Photoshop file with layers

// set preferences to preserve layersvar psdOptions = preferences.photoshopFileOptions;psdOptions.preserveLayers = true;psdOptions.pixelAspectRatioCorrection = false;// open a file using these prefsvar fileRef = File.openDialog( "Select a Photoshop file that contains layers."); if (fileRef != null) { var docRef = open(fileRef, DocumentColorSpace.RGB); }



pixelAspectRatioCorrection boolean If true, imported images that have a non-square pixel aspect ratio should be adjusted.

preserveImageMaps boolean If true, image maps should be preserved when document is converted. Default: true

preserveLayers boolean If true, layers should be preserved when document is converted. Default: true

preserveSlices boolean If true, slices should be preserved when document is converted. Default: true



PlacedItemAn artwork item (optionally stored in an external file) placed in a document. A placed item must correspond to a file containing vector-graphic data, such as a PICT, EPS or PDF file. Vector art files can be placed by users with the File > Place command in Illustrator.

When you create a placed item, Illustrator may display a dialog. To avoid this dialog check the box to turn the warning off the first time the dialog is displayed.

PlacedItem properties




boundingBox array of 4 numbers Read-only. The dimensions of the placed art item regardless of transformations.

contentVariable Variable object The content variable bound to the item.



file File object The file containing the artwork.








matrix Matrix object The transformation matrix of the placed artwork.









PlacedItem methods















duplicate



PlacedItem object


embed

()

Nothing Embeds this art in the document. Converts the art to art item objects as needed and deletes this object.

move



PlacedItem object

Moves the object.

remove

()



➤ Changing the selection state of placed items

This script illustrates how to change the selection of placed items.

// Toggle the selection state of all placed items.

resize




rotate




trace

()

PluginItem object

Converts the raster art for this object to vector art, using default options. Reorders the raster art into the source art of a plugin group, and converts it into a group of filled and/or stroked paths that resemble the original image.

Creates and returns a PluginItem object that references a TraceObject object.

transform




translate




zOrder





if ( app.documents.length > 0 ) {for ( i = 0; i < app.activeDocument.placedItems.length; i++ ) {

placedArt = app.activeDocument.placedItems[i];placedArt.selected = !(placedArt.selected);

}}


PlacedItemsA collection of PlacedItem objects in the document.

PlacedItems properties

PlacedItems methods






add

()

none PlacedItem object

Creates a new object. Use to place new art in a document, and use the resulting PlacedItem object’s embed method to convert that art to embedded art items.

getByName

(name) stringPlacedItem object


index

(itemKey) string, numberPlacedItem object


removeAll

()

none Nothing Deletes all elements in this collection.


PluginItemAn art item created by an Illustrator plug-in. Scripts can create a plugin item using PlacedItem.trace or RasterItem.trace, and can copy existing plugin items using the duplicate method, but cannot create PluginItem objects directly.

PluginItem properties










isTracing boolean If true, this plugin group represents a vector art item created by tracing a raster art item. The tracing property contains the tracing object associated with the options used to create it.















PluginItem methods

tracing TracingObject object

When this plugin group was created by tracing (isTracing is true), the tracing object associated with the options used to create it.









zOrderPosition number Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.



duplicate



PluginItem object


move



PluginItem object

Moves the object.

remove

()


resize





➤ Copying a plugin item

This example demonstrates how to create a new plugin item by copying an existing pluginItem.

// Create Plug-in art by copying an existing plugin art item

if ( app.documents.length > 0 && app.activeDocument.pluginItems.length > 0 ) {

doc = app.activeDocument;pluginArt = doc.pluginItems[0];pluginArt.duplicate( pluginArt.parent,

ElementPlacement.PLACEATBEGINNING );}

rotate




transform




translate




zOrder





PluginItemsA collection of PluginItem objects in a document. See Copying a plugin item.

PluginItems properties

PluginItems methods






getByName

(name) stringPluginItem object


index

(itemKey) string, numberPluginItem object


removeAll

()

Nothing Deletes all objects in this collection.


PPDFileAssociates file information with a PostScript Printer Description (PPD) file.

PPDFile properties

PPDFileInfoInformation about a PostScript Printer Description (PPD) file.

PPDFileInfo properties

➤ Setting PPD-file properties

This script sets PPD file information for a new document and displays the information in a text frame in the document.

//PPDFile var sPPD = "";var docRef = documents.add();var x = 30;var y = (docRef.height - 30);

var iLength = PPDFileList.length;

for(var i=0; i<iLength; i++) {var ppdRef = PPDFileList[i];sPPD = ppdRef.name;sPPD += "\r\tPS Level ";var ppdInfoRef = ppdRef.pPDInfo;sPPD += ppdInfoRef.languageLevel;sPPD += "\r\tPath: ";


name string The PPD name.

pPDInfo PPDFileInfo object

The PPD file information.



languageLevel string The PostScript language level.

PPDFilePath string Path specification for the PPD file.

screenList array of Screen objects

List of color separation screens.

screenSpotFunctionList array of ScreenSpotFunction objects

List of color separation screen spot functions.



sPPD += ppdInfoRef.PPDFilePath;

var textRef = docRef.textFrames.add();textRef.textRange.characterAttributes.size = 8;textRef.contents = sPPD;textRef.top = (y);textRef.left = x;redraw();

if( (y-=(textRef.height)) <= 30 ) {y = (docRef.height - 30);x += 150;

}}

➤ PPDFileInfo and related screen information

This script accesses Screen and ScreenSpotFunction objects through the PPDFileInfo in a document. It sets and displays properties of all three objects types.

// PPD, PPDInfo, Screen, ScreenInfo, ScreenSpotFunction

var sPPD = "";var docRef = documents.add();var x = 30;var y = (docRef.height - 30);

var iLength = PPDFileList.length;for(var i=0; i<iLength; i++) {

var ppdRef = PPDFileList[i];sPPD = ppdRef.name;sPPD += "\r\tPS Level ";var ppdInfoRef = ppdRef.pPDInfo;sPPD += ppdInfoRef.languageLevel;sPPD += "\r\tPath: "; sPPD += ppdInfoRef.PPDFilePath;

sPPD += "\r\tScreens:\r";var iScreens = ppdInfoRef.screenList.length;for(var c=0; c<iScreens; c++) {

var screenRef = ppdInfoRef.screenList[c];sPPD += "\t\t";sPPD += screenRef.name;var screenInfoRef = screenRef.screenInfo;sPPD += ", Angle = ";sPPD += screenInfoRef.angle;sPPD += ", Frequency = ";sPPD += screenInfoRef.frequency;sPPD += "\r";

}

sPPD += "\r\tScreenSpots:\r";var iScreenSpots = ppdInfoRef.screenSpotFunctionList.length;for(var n=0; n<iScreenSpots; n++) {

var screenSpotRef = ppdInfoRef.screenSpotFunctionList[n];sPPD += "\t\t";


sPPD += screenSpotRef.name;sPPD += ", spotFunction: ";sPPD += screenSpotRef.spotFunction;sPPD += "\r";

}

var textRef = docRef.textFrames.add();textRef.textRange.characterAttributes.size = 8;textRef.contents = sPPD;textRef.top = (y);textRef.left = x;redraw();

y-=(textRef.height);}


PreferencesSpecifies the preferred options for Adobe PDF and Adobe Photoshop files.

Preferences properties



PDFFileOptions PDFFileOptions object

Read-only. Options to use when opening or placing a PDF file.

photoshopFileOptions PhotoshopFileOptions object

Read-only. Options to use when opening or placing a Photoshop file.



PrintColorManagementOptionsInformation used for color management of the document.

PrintColorManagementOptions properties

➤ Managing colors for printing

// Create a PrintColorManagementOptions object and assign it // to a PrintOptions object, then print with each color intent

// Add some symbol items to a new documentvar docRef = documents.add();var y = docRef.height - 30;for(var i=0; i<10; i++) {

symbolRef = docRef.symbols[i]; symbolItemRef1 = docRef.symbolItems.add(symbolRef);

symbolItemRef1.top = y;symbolItemRef1.left = 100;y -= (symbolItemRef1.height + 10);

}redraw();

var colorOptions = new PrintColorManagementOptions();var options = new PrintOptions();options.colorManagementOptions = colorOptions;colorOptions.name = "ColorMatch RGB";

// Print the current document once for each color intent.colorOptions.intent = PrintColorIntent.ABSOLUTECOLORIMETRIC;docRef.print(options);

colorOptions.intent = PrintColorIntent.PERCEPTUALINTENT;docRef.print(options);

colorOptions.intent = PrintColorIntent.RELATIVECOLORIMETRIC;docRef.print(options);

colorOptions.intent = PrintColorIntent.SATURATIONINTENT;docRef.print(options);


colorProfileMode PrintColorProfile The color management profile mode. Default: SOURCEPROFILE

intent PrintColorIntent The color management intent type. Default: RELATIVECOLORIMETRIC

name string The color management profile name.



PrintColorSeparationOptionsInformation about the color separations to be used in printing the document.

PrintColorSeparationOptions properties

➤ Managing color separations for printing

// PrintColorSeparationOptions// Create some simple artwork (symbol items) on a // new document and print it with various separation options.

// Add some symbol items to a new documentvar docRef = documents.add();var y = docRef.height - 30;for(var i=0; i<10; i++) {

symbolRef = docRef.symbols[i];symbolItemRef1 = docRef.symbolItems.add(symbolRef);symbolItemRef1.top = y;symbolItemRef1.left = 100;y -= (symbolItemRef1.height + 10);

} // Print with various separation optionsvar sepOptions = new PrintColorSeparationOptions();var options = new PrintOptions();options.colorSeparationOptions = sepOptions;

sepOptions.convertSpotColors = true;sepOptions.overPrintBlack = true;sepOptions.colorSeparationMode = PrintColorSeparationMode.COMPOSITE;docRef.print(options);

sepOptions.colorSeparationMode = PrintColorSeparationMode.INRIPSEPARATION;docRef.print(options);

sepOptions.convertSpotColors = false;sepOptions.overPrintBlack = false;sepOptions.colorSeparationMode = PrintColorSeparationMode.HOSTBASEDSEPARATION;docRef.print(options);


colorSeparationMode PrintColorSeparationMode The color separation type. Default: COMPOSITE

convertSpotColors boolean If true, all spot colors should be converted to process colors. Default: false

inkList array of Ink objects The list of inks for color separation.

overPrintBlack boolean If true, overprint in black. Default: false



PrintCoordinateOptionsInformation about the media and associated printing parameters.

PrintCoordinateOptions properties

➤ Managing print coordinates

// PrintCoordinateOptions// Create some simple artwork that extends off the pagevar docRef = documents.add();var y = docRef.height + 50;for(var i=0; i<(docRef.symbols.length); i++) {


}redraw();// Print it with various Coordinate Optionsvar coordinateOptions = new PrintCoordinateOptions();var options = new PrintOptions();options.coordinateOptions = coordinateOptions;

coordinateOptions.emulsion = true; // reverse from right to leftcoordinateOptions.fitToMedia = true; // fit artwork to page sizecoordinateOptions.orientation = PrintOrientation.LANDSCAPE;docRef.print(options); coordinateOptions.emulsion = false;coordinateOptions.fitToMedia = false;coordinateOptions.orientation = PrintOrientation.PORTRAIT;coordinateOptions.horizontalScale = 50;coordinateOptions.verticalScale = 50;docRef.print(options);


emulsion boolean If true, flip artwork horizontally. Default: false

fitToPage boolean If true, proportionally scale the artwork to fit on media. Default: false

horizontalScale number (double) The horizontal scaling factor expressed as a percentage (100 = 100%). Range: 1.0 to 10000.0 Default: 100.0

orientation PrintOrientation The artwork orientation. Default: PORTRAIT

position PrintPosition The artwork position on media. Default: TRANSLATECENTER

tiling PrintTiling The page tiling mode. Default: TILESINGLEFULLPAGE


verticalScale number (double) The vertical scaling factor expressed as a percentage (100 = 100%) Range: 1.0 to 10000.0 Default: 100.0


PrinterAssociates an available printer with printer information. To request a list of printers, you must first have a document open or an error is returned.

Printer properties

PrinterInfoConfiguration information about a printer.

PrinterInfo properties


name string The printer name.

printerInfo PrinterInfo object

The printer information.



binaryPrintingSupport boolean If true, the printer supports binary printing.

colorSupport PrinterColorMode The printer color capability.

customPaperSupport boolean If true, the printer supports custom paper size.

customPaperTransverseSupport boolean If true, the printer supports custom paper transverse.

deviceResolution number (double) The printer default resolution.

inRIPSeparationSupport boolean If true, the printer supports InRIP color separation.

maxDeviceResolution number (double) The printer maximum device resolution.

maxPaperHeight number (double) Custom paper’s maximum height.

maxPaperHeightOffset number (double) Custom paper’s maximum height offset.

maxPaperWidth number (double) Custom paper’s maximum width.

maxPaperWidthOffset number (double) Custom paper’s maximum width offset.


➤ Finding available printers

// Display list of available printers with configuration information

var docRef = documents.add();var textRef = docRef.textFrames.add();

var iCount = printerList.length;textRef.contents += "Checking Printers...\r";for( var i=0; i<iCount; i++ ) {

textRef.contents += printerList[i].name;textRef.contents += "\r\t";

textRef.contents += "PS Level = "; textRef.contents += printerList[i].printerInf.postScriptLevel;textRef.contents += "\r\t";

textRef.contents += "Device Resolution = "; textRef.contents += printerList[i].printerInf.deviceResolution;textRef.contents += "\r\t";

textRef.contents += "InRIPSeparation Support = "; textRef.contents += printerList[i].printerInf.inRIPSeparationSupport;textRef.contents += "\r\r";

}textRef.top = 600;textRef.left = 200;redraw();

minPaperHeight number (double) Custom paper’s minimum height.

minPaperHeightOffset number (double) Custom paper’s minimum height offset.

minPaperWidth number (double) Custom paper’s minimum width.

minPaperWidthOffset number (double) Custom paper’s minimum width offset.

paperSizes array of Paper objects The list of supported paper sizes.

postScriptLevel PrinterPostScriptLevelEnum The PostScript Language level.

printerType PrinterTypeEnum The printer type.




PrintFlattenerOptionsContains flattening options for use when Illustrator outputs artwork that contains transparency into a non-native format.

PrintFlattenerOptions properties

➤ Setting print flattening

// Print the current documemt with a range of flattener balance settings.

// Create PrintFlattenerOptions object and assign to a PrintOptions objectvar flatOpts = new PrintFlattenerOptions();var printOpts = new PrintOptions();printOpts.flattenerOptions = flatOpts;// Set other print optionsprintOpts.ClipComplexRegions = true;printOpts.GradientResoultion = 360;printOpts.RasterizatonResotion = 360;

// Print the current document with flattening balance increments of 20var i;for(i=0; i<=100; i+=20) {

flatOpts.flatteningBalance = i;activeDocument.print(printOpts);

}


clipComplexRegions boolean If true, complex regions should be clipped. Default: false

convertStrokesToOutlines boolean If true, convert all strokes to outlines. Default: false

convertTextToOutlines boolean If true, convert all text to outlines. Default: false

flatteningBalance number (long)

The flattening balance. Range: 0.0 to 100.0. Default: 100.0

gradientResolution number (double)

The gradient resolution in dots per inch (dpi). Range: 1.0 to 9600.0 Default: 300.0

overprint PDFOverprint Whether to preserve, discard, or simulate overprinting. Default: PRESERVEPDFOVERPRINT

rasterizationResolution number (double)

The rasterization resolution in dots per inch (dpi). Range: 1.0 to 9600.0 Default: 300.0



PrintFontOptionsContains information about font downloading and substitution for the fonts used for printing the document.

PrintFontOptions properties

➤ Printing with font options

// Print the current documemt with font options.

//Create PrintFontOptions object and assign to a PrintOptions objectvar fontOpts = new PrintFontOptions();var printOpts = new PrintOptions();printOpts.fontOptions = fontOpts;//Set some font optionsfontOpts.downloadFonts = PrintFontDownloadMode.DOWNLOADNONE;fontOpts.fontSubstitution = FontSubstitutionPolicy.SUBSTITUTEDEVICE;

// print itactiveDocument.print(printOpts);


downloadFonts PrintFontDownloadMode The font download mode. Default: DOWNLOADSUBSET

fontSubstitution FontSubstitutionPolicy The font substitution policy. Default: SUBSTITUTEOBLIQUE



PrintJobOptionsContains information about how the job is to be printed.

PrintJobOptions properties

➤ Printing with job options

// PrintJobOptions

// Create simple text items on a variety of// Print/No-Print and Non-Visible layers.var docRef = documents.add();var textRef_0 = docRef.layers[0].textFrames.add();textRef_0.contents = "Visible and Printable";textRef_0.top = 600;textRef_0.left = 200;

var layerRef_1 = docRef.layers.add();var textRef_1 = layerRef_1.textFrames.add();textRef_1.contents = "Visible and Non-Printable";textRef_1.top = 500;textRef_1.left = 250;layerRef_1.printable = false;

var layerRef_2 = docRef.layers.add();var textRef_2 = layerRef_2.textFrames.add();textRef_2.contents = "Non-Visible";textRef_2.top = 400;textRef_2.left = 300;


bitmapResolution number (double) The bitmap resolution. Minimum: 0.0. Default: 0.0

collate boolean If true, collate print pages. Default: false

copies number (long) The number of copies to print. Minimum: 1 Default: 1

designation PrintArtworkDesignation The layers/objects to be printed. Default: VISIBLEPRINTABLELAYERS

file File object The file to which to print.

name string The print job name.

printArea PrintingBounds The printing bounds. Default: ARTBOARDBOUNDS

printAsBitmap boolean If true, print as bitmap. Default: false

reversePages boolean If true, print pages in reverse order. Default: false



layerRef_2.visible = false;redraw();

// Print with various job optionsvar printJobOptions= new PrintJobOptions();var options = new PrintOptions();options.jobOptions = printJobOptions;

printJobOptions.designation = PrintArtworkDesignation.ALLLAYERS;printJobOptions.reverse = true;docRef.print(options);

printJobOptions.collate = false;printJobOptions.designation = PrintArtworkDesignation.VISIBLELAYERS;printJobOptions.reverse = false;docRef.print(options);

printJobOptions.designation = PrintArtworkDesignation.VISIBLEPRINTABLELAYERS;var docPath = new File("~/printJobTest1.ps");printJobOptions.file = docPath;docRef.print(options);


PrintOptionsContains information about all printing options including flattening, color management, coordinates, fonts, and paper.

PrintOptions properties

➤ Setting print options

// PrintOptions// Create a variety of print options, assign to a PrintOptions object,// then print with those options

// Create a new document and add some symbol itemsvar docRef = documents.add();var y = docRef.height - 30;for(var i=0; i<10; i++) {



colorManagementOptions PrintColorManagementOptions object

The printing color management options.

colorSeparationOptions PrintColorSeparationOptions object

The printing color separation options.

coordinateOptions PrintCoordinateOptions object

The printing coordinate options.

flattenerOptions PrintFlattenerOptions object

The printing flattener options.

flattenerPreset string The transparency flattener preset name.

fontOptions PrintFontOptions object The printing font options.

jobOptions PrintJobOptions object The printing job options.

pageMarksOptions PrintPageMarksOptions object

The printing page marks options.

paperOptions PrintPaperOptions object The paper options.

postScriptOptions PrintPostScriptOptions object

The printing PostScript options.

PPDName string The PPD name.

printerName string The printer name.

printPreset string The print style.



} redraw();

// Create multiple options and assign to PrintOptionsvar options = new PrintOptions();

var colorOptions = new PrintColorManagementOptions();colorOptions.name = "ColorMatch RGB";colorOptions.intent = PrintColorIntent.SATURATIONINTENT;options.colorManagementOptions = colorOptions;

var printJobOptions= new PrintJobOptions();printJobOptions.designation = PrintArtworkDesignation.ALLLAYERS;printJobOptions.reverse = true;options.jobOptions = printJobOptions;

var coordinateOptions = new PrintCoordinateOptions();coordinateOptions.fitToMedia = true; options.coordinateOptions = coordinateOptions;

var flatOpts = new PrintFlattenerOptions();flatOpts .ClipComplexRegions = true;flatOpts .GradientResoultion = 60;flatOpts .RasterizatonResotion = 60;options.flattenerOptions = flatOpts;

// Print with optionsdocRef.print(options);


PrintPageMarksOptionsThe options for printing page marks.

PrintPageMarksOptions properties

➤ Setting page mark printing options

// Create a PrintPageMarksOptions object, assign it // to a PrintOptions object, then print the current document.

var docRef = activeDocument;var pageMarkOptions= new PrintPageMarksOptions();var options = new PrintOptions();options.pageMarksOptions = pageMarkOptions;

pageMarkOptions.colorBars = true;pageMarkOptions.pageInfoMarks = true;pageMarkOptions.registrationMarks = true;pageMarkOptions.trimMarks = true;docRef.print(options);


bleedOffsetRect array of 4 numbers

The bleed offset rectangle.

colorBars boolean If true, enable printing of color bars. Default: false

marksOffsetRect array of 4 numbers

The page marks offset rectangle.

pageInfoMarks boolean If true, page info marks printing is enabled. Default: false

pageMarksType PageMarksTypes The page marks style. Default: Roman

registrationMarks boolean If true, registration marks should be printed. Default: false

trimMarks boolean If true, trim marks should be printed. Default: false

trimMarksWeight number (double) Stroke weight of trim marks. Minimum: 0.0 Default: 0.125



PrintPaperOptionsInformation about the paper to be used in the print job.

PrintPaperOptions properties

➤ Setting print paper options

// PrintPaperOptions

// create a simple path item and apply a graphic style to itvar docRef = documents.add();var pathRef = docRef.pathItems.rectangle(600, 200, 200, 200);docRef.graphicStyles[2].applyTo(pathRef);

var paperOpts = new PrintPaperOptions;var printOpts = new PrintOptions;printOpts.paperOptions = paperOpts;

// Print with the 1st paper from the 1st printervar printerRef = printerList[0];var paperRef = printerRef.printerInfo.paperSizes[0];paperOpts.name = paperRef.name;printOpts.printerName = printerRef.name;

docRef.print(printOpts);


height number (double) The custom height (in points) for using the custom paper. Default: 0.0

name string The paper’s name.

offset number (double) Custom offset (in points) for using the custom paper. Default: 0.0

transverse boolean If true, transverse the artwork (rotate 90 degrees) on the custom paper. Default: false


width number (double) The custom width (in points) for using the custom paper. Default: 0.0


PrintPostScriptOptionsOptions for printing to a PostScript printer.

PrintPostScriptOptions properties

➤ Setting PostScript printing options

// Print current document at various PS levels

if(documents.length < 1) { alert("Open a document with text.");}// Create new postscript options object, assign to print optionsvar psOpts = new PrintPostScriptOptions();var printOpts = new PrintOptions();printOpts.postScriptOptions = psOpts;// Assign PS level, printpsOpts.postScriptLevel = PrinterPostScriptLevelEnum.PSLEVEL2;activeDocument.print(printOpts);

psOpts.postScriptLevel = PrinterPostScriptLevelEnum.PSLEVEL3;activeDocument.print(printOpts);


binaryPrinting boolean If true, printing should be in binary mode. Default: false

compatibleShading boolean If true, use PostScript Level 1-compatible gradient and gradient mesh printing. Default: false

forceContinuousTone boolean If true, force continuous tone. Default: false

imageCompression PostScriptImageCompressionType The image compression type. Default: IMAGECOMPRESSIONNONE

negativePrinting boolean If true, print in negative mode. Default: false

postScriptLevel PrinterPostScriptLevelEnum The PostScript language level. Default: LEVEL2

shadingResolution number (double) The shading resolution. Range: 1.0 to 9600.0 Default: 300.0



RasterItemA bitmap art item in a document. A script can create a raster item from an external file, or by copying an existing item with the duplicate method.

RasterItem properties




boundingBox array of 4 numbers Read-only. The dimensions of the placed art item regardless of transformations.

contentVariable Variable object The content variable bound to the item.



embedded boolean If true, the raster art item is embedded in the illustration.

file File object The file containing the artwork.




imageColorSpace ImageColorSpace Read-only. The color space of the raster image.





matrix Matrix object The transformation matrix of the placed artwork.









RasterItem methods

status RasterLinkState Status of the linked image.















colorize

(rasterColor) color objectNothing Colorizes the raster item with a

CMYK or RGB Color.

duplicate



RasterItem object


move



RasterItem object

Moves the object.

remove

()



resize




rotate




trace

()

PluginItem object

Converts the raster art for this object to vector art, using default options. Reorders the raster art into the source art of a plugin group, and converts it into a group of filled and/or stroked paths that resemble the original image.

Creates and returns a PluginItem object that references a TraceObject object.

transform




translate




zOrder





RasterItemsA collection of RasterItem objects.

RasterItems properties

RasterItems methods

➤ Finding and examining a raster item

This script illustrates how to obtain the color space of a raster item.

// Examine the color space of the first raster item in the document

if ( app.documents.length > 0 && app.activeDocument.rasterItems.length > 0 ) {

var rasterArt = app.activeDocument.rasterItems[0];

switch ( rasterArt.imageColorSpace ) {case ImageColorSpace.CMYK:alert("The color space of the first raster item is CMYK");break;

case ImageColorSpace.RGB:alert("The color space of the first raster item is RGB");

break;

case ImageColorSpace.GRAYSCALE:alert("The color space of the first raster item is GRAYSCALE");break;

}}






add

()

RasterItem object


getByName

(name) stringRasterItem object


index

(itemKey) string, numberRasterItem object


removeAll

()



RGBColorAn RGB color specification, used to apply an RGB color to a layer or art item.

If the color space of a document is RGB and you specify the color value for a page item in that document using CMYK, Illustrator will translate the CMYK color specification into an RGB color specification. The same thing happens if the document’s color space is CMYK and you specify colors using RGB. Since this translation can lose information, you should specify colors using the class that matches the document’s actual color space.

RGBColor properties

➤ Setting an RGB color

This script sets the default fill color of the frontmost document to yellow using an RGB object. If the color space of the frontmost document is CMYK, then Illustrator automatically translates the RGB fill color to a CMYK color.

// Set the default fill color to yellow. if ( app.documents.length > 0 ) {

// Define the new colorvar newRGBColor = new RGBColor();

newRGBColor.red = 255;newRGBColor.green = 255;newRGBColor.blue = 0;app.activeDocument.defaultFillColor = newRGBColor;

}


blue number (double) The blue color value. Range: 0.0 to 255.0

green number (double) The green color value. Range: 0.0 to 255.0

red number (double) The red color value. Range: 0.0 to 255.0



ScreenAssociates a color separation screen with information to be used for printing.

Screen properties

ScreenInfoContains information about the angle and frequency of the color separation screen to be used for printing.

ScreenInfo properties

➤ Getting screen information

// Screen, ScreenInfovar sInfo = "";var docRef = documents.add();var ppdRef = PPDFileList[0];sInfo = ppdRef.name;var ppdInfoRef = ppdRef.pPDInfo;sInfo += "\r\tScreens:\r";var iScreens = ppdInfoRef.screenList.length;for(var c=0; c<iScreens; c++) {

var screenRef = ppdInfoRef.screenList[c];sInfo += "\t\t";sInfo += screenRef.name;

var screenInfoRef = screenRef.screenInfo;sInfo += ", Angle = ";sInfo += screenInfoRef.angle;sInfo += ", Frequency = ";sInfo += screenInfoRef.frequency;sInfo += "\r";

}var textRef = docRef.textFrames.add();textRef.textRange.characterAttributes.size = 8;


name string The color separation screen name.

screenInfo ScreenInfo object The color separation screen information.



angle number (double) The screen’s angle in degrees.

defaultScreen boolean If true, it is the default screen.

frequency number (double) The screen’s frequency.



textRef.contents = sInfo;textRef.top = (docRef.height - 30);textRef.left = 30;redraw();


ScreenSpotFunctionContains information about a color separation screen spot function, including its definition in PostScript language code.

ScreenSpotFunction properties

➤ Finding screen spot functions

// Display the screen spot functions for the 1st PPD file.

var docRef = documents.add();var ppdRef = PPDFileList[0];var sInfo = ppdRef.name;var ppdInfoRef = ppdRef.pPDInfo;

sInfo += "\r\tScreenSpots:\r";var iScreenSpots = ppdInfoRef.screenSpotFunctionList.length;for(var n=0; n<iScreenSpots; n++) {

var screenSpotRef = ppdInfoRef.screenSpotFunctionList[n];sInfo += "\t\t";sInfo += screenSpotRef.name;sInfo += ", spotFunction: ";sInfo += screenSpotRef.spotFunction;sInfo += "\r";

}

var textRef = docRef.textFrames.add();textRef.textRange.characterAttributes.size = 8;textRef.contents = sInfo;textRef.top = (docRef.height - 30);textRef.left = 30;redraw();


name string The color separation screen spot function name.

spotFunction string The spot function expressed in PostScript commands.



SpotA custom color definition contained in a SpotColor object. All Illustrator documents contain the spot color [Registration] which can be used to print to all plates of a separation.

If no properties are specified when creating a new spot, default values are provided. However, if specifying the color, you must use the same color space as the document, either CMYK or RGB. Otherwise, an error results. When created, the spot is inserted into the swatch palette at the end.

Spot properties

Spot methods

➤ Creating a new spot color

// Create a new spot color in the frontmost documentif ( app.documents.length > 0 ){

var doc = app.activeDocument;// Create the new spotvar newSpot = doc.spots.add();// Define the new color valuevar newColor = new CMYKColor();newColor.cyan = 35;newColor.magenta = 0;newColor.yellow = 50;newColor.black = 0;// Define a new SpotColor with an 80% tint// of the new Spot's color. The spot color can then// be applied to an art item like any other color.newSpot.name = "Pea-Green";newSpot.colorType = ColorModel.SPOT;newSpot.color = newColor;var newSpotColor = new SpotColor();newSpotColor.spot = newSpot;newSpotColor.tint = 80;alert("Created " + newSpot.name + " " + newSpotColor.tint + "%" );

}


color color object The color information for this spot color.

colorType ColorModel The color model for this custom color.

name string The spot color’s name.

parent Document object Read-only. The document that contains this spot color.



remove

()



SpotColorColor class used to apply the color value of a spot at a specified tint value. Can be used in any property that takes a color object.

SpotColor properties


spot Spot object A reference to the spot color object that defines the color.

tint number (double) The tint of the color. Range: 0.0 to 100.0



SpotsA collection of SpotColor objects in a document.

Spots properties

Spots methods

➤ Removing spot colors

This script illustrates how to remove all spots defined in the frontmost document.

// Remove all spots colors from the frontmost document

if ( app.documents.length > 0 ) {app.activeDocument.spots.removeAll();

}

➤ Creating and applying spot colors

This script shows how to create a new spot, and they applying a tint of that spot to the fill of a path item.

//Define and apply a spot color

if ( app.documents.length > 0 && app.activeDocument.pathItems.length > 0 ) {// Define the new color valuenewRGBColor = new RGBColor();newRGBColor.red = 255;newRGBColor.green = 0;newRGBColor.blue = 0;

// Create the new spotvar newSpot = app.activeDocument.spots.add();// Define the new SpotColor as 80% of the RGB color






add

()

Spot object


getByName

(name) stringSpot object


index

(itemKey) string, numberSpot object


removeAll

()



newSpot.name = "Scripted Red spot";newSpot.tint = 80;newSpot.color = newRGBColor;

// Apply a 50% tint of the new spot color to the frontmost path item.

// Create a spotcolor object, set the tint value,var newSpotColor = new SpotColor();newSpotColor.spot = newSpot;newSpotColor.tint = 50;// Use the spot color to set the fill colorvar frontPath = app.activeDocument.pathItems[0];frontPath.filled = true;frontPath.fillColor = newSpotColor;

}


StoryA contiguous block of text as specified by a text range. A story can contain one or more text frames; if there is more than one, the multiple text frames are linked together to form a single story.

Story properties

➤ Linking text frames into stories

// Create two TextFrames and link the 2nd // to the first to create a single story.// // Create a 3rd non-linked TextFrame to create a 2nd story.

// Create a new document and add 2 area TextFramesvar docRef = documents.add();var itemRef1 = docRef.pathItems.rectangle(600, 200, 50, 30);var textRef1 = docRef.textFrames.areaText(itemRef1);textRef1.selected = true;

// create 2nd text frame and link it the first


characters Characters collection object

Read-only. All the characters in this story.

insertionPoints InsertionPoints collection object

Read-only. All the insertion points in this story.

length number (long) Read-only. The number of characters in the story.

lines Lines collection object

Read-only. All the lines in this story.

paragraphs Paragraphs collection object

Read-only. All the paragraphs in this story.



Read-only. The text frame items in this story.

textRange TextRange object

Read-only. The text range of the story.

textRanges TextRanges collection object

Read-only. All the text ranges in the story.

textSelection array of TextRange objects

Read-only. The selected text ranges in the story.


words Words collection object

Read-only. All the words in the story.


var itemRef2 = docRef.pathItems.rectangle(550, 300, 50, 200);var textRef2 = docRef.textFrames.areaText(itemRef2, TextOrientation.HORIZONTAL, textRef1);textRef2.selected = true;

// Add enough text to the 1st TextFrame to// cause it to flow to the 2nd TextFrame.textRef1.contents = "This is two text frames linked together as one story";redraw();alert("There is " + docRef.stories.length + " story");

// Create a 3rd text frame and count the storiesvar textRef3 = docRef.textFrames.add();textRef3.contents = "Each unlinked textFrame adds a new story."textRef3.top = 650;textRef3.left = 200;redraw();alert("Now there are " + docRef.stories.length + " stories");


StoriesA collection of Story objects in a document.

Stories properties

Stories methods






index

(itemKey) string, numberStory object



SwatchA color swatch definition contained in a document. The swatches correspond to the swatch palette in the Illustrator user interface. A script can create a new swatch. The swatch can hold all types of color data, such as pattern, gradient, CMYK, RGB, gray, and spot.

Swatch properties

Swatch methods

➤ Modifying a swatch

This script illustrates how to change the name of the fifth swatch.

// Change the name of the last swatch

if ( app.documents.length > 0 && app.activeDocument.swatches.length > 0 ) {var lastIndex = app.activeDocument.swatches.length - 1;var lastSwatch = app.activeDocument.swatches[lastIndex];lastSwatch.name = "TheLastSwatch";

}


color color object The color information for this swatch.

name string The swatch’s name.

parent Document object Read-only. The document that contains this swatch.



remove

()



SwatchesA collection of Swatch objects in a document.

Swatches properties

Swatches methods

➤ Finding and deleting a swatch

This script illustrates how to first obtain a swatch by name and then how to delete that swatch.

// Remove the swatch called "Red" in the frontmost document

if ( app.documents.length > 0 ) {try {

swatchToDelete = app.activeDocument.swatches["Red"]; swatchToDelete.remove();

} catch (e) {alert( "The specified swatch doesn’t exist" );}

}






add

()

Swatch object

Creates a new Swatch object.

getByName

(name) stringSwatch object


index

(itemKey) string, numberSwatch object


removeAll

()



SymbolAn art item that is stored in the Symbols Palette, and can be reused one or more times in the document without duplicating the art data. Symbols are contained in documents. Instances of Symbol in a document are associated with SymbolItem objects, which store the art-object properties.

Symbol properties

Symbol methods


name string The symbol’s name.

parent object Read-only. The object that contains the symbol object.



duplicate

()

Symbol object

Create a duplicate of this object.

remove

()



SymbolsThe collection of Symbol objects in the document.

Symbols properties

Symbols methods

➤ Creating a symbol

// Create a simple path item from each graphic style// Add each item as a new symbol

var docRef = documents.add();var y = 750;var x =25;

alert("There are " + docRef.symbols.length + " symbols.");

var iCount = docRef.graphicStyles.length;for(var i=1; i<iCount; i++) {

var pathRef = docRef.pathItems.rectangle( y, x, 20, 20 ); docRef.graphicStyles[i].applyTo(pathRef);

// are we at bottom?


length number Read-only. The number of objects in the collection




add

(sourceArt) art item objectSymbol object

Returns a symbol object created from the source art item, any of the following:

CompoundPathItemsGraphItemsGroupItemsMeshItemsPathItemsPlacedItemsPathItemsRasterItemsSymbolItemsTextFrames

index

(itemKey) string, numberSymbol object


getByName

(name) stringSymbol object


removeAll

()



if( (y-=60) <= 60 ) {y = 750; // go back to the top.x+= 200

}redraw();docRef.symbols.add(pathRef);

}alert("Now there are" + docRef.symbols.length + " symbols.");


SymbolItemAn art item made reusable by adding it to the Symbols palette. A SymbolItem is linked to the Symbol from which it was created and changes if you modify the associated Symbol object.

SymbolItem properties




















symbol Symbol object The symbol that was used to create this symbolItem.








SymbolItem methods









duplicate



SymbolItem object


move



SymbolItem object

Moves the object.

remove

()


resize




rotate





transform




translate




zOrder





SymbolItemsA collection of SymbolItem objects in the document.

SymbolItems properties

SymbolItems methods

➤ Creating symbol items

// Add a symbol item to the document for every symbol available.

var docRef = documents.add();var y = 750;var x = 25;var iCount = docRef.symbols.length;for(var i=1; i<iCount; i++) {

symbolRef = docRef.symbols[i];symbolItemRef1 = docRef.symbolItems.add(symbolRef);symbolItemRef1.top = y;symbolItemRef1.left = x;y-=(symbolItemRef1.height + 20);if( (y) <= 60 ) {

y = 750;x+= 190;

}}






add

(symbol) Symbol objectSymbolItem object

Creates an instance of the specified symbol.

getByName

(name) stringSymbolItem object


index

(itemKey) string, numberSymbolItem object


removeAll

()



TabStopInfoInformation about the alignment, position, and other details for a tab stop in a ParagraphAttributes object.

TabStopInfo properties

➤ Display tab-stop information for a document

// TabStopInfo// Check current document for textFrames.// Display information about each TabStop found.

if ( app.documents.length < 1 ) {alert ( "open a document with paragraphs that contain TabStops." );

}else {

docRef = app.activeDocument;if ( docRef.textFrames.length < 1 ) {

alert ( "open a document with paragraphs that contain TabStops." );}else {

var tabRef, sData = "Tab Stops Found \nTabStop Leader\tTabStop Position\n";

var textRef = docRef.textFrames;

for( var i=0 ; i < textRef.length; i++ ) {// Get all paragraphs in the textFramesparaRef = textRef[i].paragraphs;for ( p=0 ; p < paraRef.length ; p++ ) {

// Get para attributes for all textRanges in paragraphattrRef = paraRef[p].paragraphAttributes;tabRef = attrRef.tabStops;if ( tabRef ) {

sData += tabRef.Leader + "\t";sData += tabRef.Position + "\n";

}}

}}

}alert( sData );


alignment TabStopAlignment The alignment of the tab stop. Default: Left

decimalCharacter string The character used for decimal tab stops. Default: .

leader string The leader dot character.

position number (double) The position of the tab stop expressed in points. Default: 0.0



TagA label associated with a specific piece of artwork. Tags allows you to assign an unlimited number of key-value pairs to any page item in a document.

Tag properties

Tag methods

➤ Using tags

This example illustrates how to list the tags associated with the first selected item.

// Find tags of selected art item, show names and values in separate documentif ( app.documents.length > 0 ) {

doc = app.activeDocument;if ( doc.selection.length > 0 ) {

for ( i = 0; i < selection.length; i++ ) {selectedArt = selection[0];tagList = selectedArt.tags;if (tagList.length == 0) {

alert( "The selected art has no tags" );}else { // Create a document and add a line of text per tag

reportDocument = app.documents.add();top_offset = 400;for ( i = 0; i < tagList.length; i++ ) {

tagText = tagList[i].value;newItem = reportDocument.textFrames.add();newItem.contents = "Tag: (" + tagList[i].name +

" , " + tagText + ")";newItem.position = Array(100, top_offset);newItem.textRange.size = 24;top_offset = top_offset - 20;

}}

}}else { alert( "No art items selected." ); }

}


name string The tag’s name.

parent object Read-only. The object that contains this tag.


value string The data stored in this tag.


remove

()



TagsA collection of Tag objects.

Tags properties

Tags methods

➤ Setting tag values

This example illustrates how to set the URL of all images in a document. It uses the special tag name “AdobeURL” to store the value of the URL.

// Set a URL property on all RasterItems and PlacedItems in the documentif ( app.documents.length > 0 ) {

doc = app.activeDocument;if ( doc.placedItems.length + doc.rasterItems.length > 0 ) {

for ( i = 0; i < doc.pageItems.length; i++ ) {imageArt = doc.pageItems[i];if ( imageArt.typename == "PlacedItem"

|| imageArt.typename == "RasterItem") {// Create a new Tag with the name AdobeURL and the// value of the www linkurlTAG = imageArt.tags.add();urlTAG.name = "AdobeWebSite";urlTAG.value = "http://www.adobe.com/";

}}

}else {

alert( "No placed or raster items in the document" );}

}






add

()

Tag object Creates a new Tag object.

getByName

(name) stringTag object Gets the first element in the collection with the

specified name.

index

(itemKey) string, numberTag object Gets an element from the collection.

removeAll

()



TextFontInformation about a font in the document, found in a CharacterAttributes object.

TextFont properties

➤ Setting the font of text

// Set the font of all the text in the document to the first font

if ( app.documents.length > 0 ) {// Iterate through all text art and apply font 0for ( i = 0; i< app.activeDocument.textFrames.length; i++) {

textArtRange = app.activeDocument.textFrames[i].textRange;textArtRange.characterAttributes.textFont = app.textFonts[0];

}}


family string Read-only. The font’s family name.

name string Read-only. The font’s full name.


style string Read-only. The font’s style name.



TextFontsA collection of TextFont objects.

TextFonts properties

TextFonts methods

➤ Finding fonts

// TextFont, TextFonts// Create a new document and display a list of all available fonts.

var docRef = documents.add();var sFontNames = "";var x = 30;var y = (docRef.height - 30);

var iCount = textFonts.length;for(var i=0; i<iCount; i++) {

sFontNames = textFonts[i].name;sFontNames += " ";sFontNames += textFonts[i].style;

var textRef = docRef.textFrames.add();textRef.textRange.characterAttributes.size = 8;textRef.contents = sFontNames;textRef.top = (y);textRef.left = x;redraw();

if( (y-=(textRef.height)) <= 30 ) {y = (docRef.height - 30);x += 150;

}}






index

(itemKey) string, numberTextFont object

Get an element from the collection.

getByName

(name) stringTextFont object



TextFrameThe basic art item for displaying text. Multiple text frames can be linked together within a story.

TextFrame properties


anchor array of 2 numbers The position of the anchor point, the start of the base line for point text.




Read-only. All the characters in this text range.

columnCount number (long) The column count in the text frame (area text only).

columnGutter number (double) The column gutter in the text frame (area text only).

contents string The text string.

contentVariable Variable object The content variable bound to this text frame item.



endTValue number (double) The end position of text along a path, as a value relative to the path’s segments (path text only).

flowLinksHorizontally boolean Whether to flow text between linked frames horizontally first (area text only).





Read-only. All the insertion points in this text range.

isIsolated boolean If true, the artwork is isolated.

kind TextType The type of a text frame item (area, path or point).




Read-only. All the lines in this text range.



matrix Matrix object Read-only. The transformation matrix for this text frame.


nextFrame TextFrame object The linked text frame following this one.


opticalAlignment boolean If true, the optical alignment feature is active.

orientation TextOrientation The orientation of the text.


Read-only. All the paragraphs in this text range.




previousFrame TextFrame object The linked text frame preceding this one.

rowCount number (long) The row count in the text frame (area text only).

rowGutter number (double) The row gutter in the text frame (area text only).



spacing number (double) The amount of spacing.

startTValue number (double) The start position of text along a path, as a value relative to the path’s segments (path text only).

story Story object Read-only. The story to which the text frame belongs.



textPath TextPath object The path item associated with the text frame (area and path text).

textRange TextRange object Read-only. The text range of the text frame.


Read-only. All the text in this text frame.


Read-only. The selected text ranges in the text frame.







TextFrame methods




Read-only. All the words in this text range.







createOutline

()

GroupItem object

Creates an outline for the frame text.

duplicate



TextRange object


move



TextRange object

Moves the object.

remove

()


resize




rotate





➤ Rotate a text art item

// Rotate the selected text art item

if ( app.documents.length > 0 ) {selectedItems = app.activeDocument.selection;// make sure something is selected.if ( selectedItems.length > 0 ) {

// The selection must be a text art item if ( selectedItems[0].typename == "TextFrame" ) {

// Get the parent of the text art so new text art items // can be inserted in the same group or layerdupSrc = selectedItems[0];textContainer = dupSrc.parent;// Create 5 new versions of the text art each rotated a bitfor ( i = 1; i <= 5; i++ ) {

dupText = dupSrc.duplicate( textContainer, ElementPlacement.PLACEATEND );

dupText.rotate(180 * i/6);}

}}

}

transform




translate




zOrder





TextFramesA collection of TextFrame objects.

TextFrames properties

TextFrames methods

➤ Creating and modifying text frames

// Add a document and create TextFrames of each type// Change the content of each TextFrame.// Remove one TextFrame and display the count.

// create a new documentvar docRef = documents.add();// create 3 new textFrames (area, line, point)






add

()

textFrame object

Creates a point text frame item.

areaText

(textPath[,orientation][,baseFrame][,postFix])

PathItem objectTextOrientationTextFrame objectboolean

TextFrame object

Creates an area text frame item.

getByName

(name) stringTextFrame object


index

(itemKey) string, numbertextFrame object


pathText

(textPath[,startTValue][,endTValue[,orientation][,baseFrame][,postFix])

PathItem objectnumber (double)number (double)TextOrientationTextFrame objectboolean

TextFrame object

Creates an on-path text frame item.

pointText

(anchor[,orientation])

array of 2 numbersTextOrientation

TextFrame object

Creates a point text frame item.

removeAll

()

Nothing Deletes all elements in the object.


// Area Textvar rectRef = docRef.pathItems.rectangle(700, 50, 100, 100);var areaTextRef = docRef.textFrames.areaText(rectRef);areaTextRef.contents = "TextFrame #1";areaTextRef.selected = true;

// Line Textvar lineRef = docRef.pathItems.add();lineRef.setEntirePath( Array(Array(200, 700), Array(300, 550) ) );var pathTextRef = docRef.textFrames.pathText(lineRef);pathTextRef.contents = "TextFrame #2";pathTextRef.selected = true;

// Point Textvar pointTextRef = docRef.textFrames.add();pointTextRef.contents = "TextFrame #3";pointTextRef.top = 700;pointTextRef.left = 400;pointTextRef.selected = true;redraw();

// count the TextFramesvar iCount = docRef.textFrames.length;var sText = "There are " + iCount + " TextFrames.\r"sText += "Changing contents of each TextFrame.";alert(sText);

// change the content of each docRef.textFrames[0].contents = "Area TextFrame.";docRef.textFrames[1].contents = "Path TextFrame.";docRef.textFrames[2].contents = "Point TextFrame.";redraw();

alert("Removing 1 TextFrame.");docRef.textFrames[1].remove();redraw();

// count againvar iCount = docRef.textFrames.length;alert("Now there are " + iCount + " TextFrames.");


TextPathA path or list of paths for area or path text. A path consists of path points that define its geometry.

TextPath properties


area number (double) Read-only. The area of this path in square points. If the area is negative, the path is wound counterclockwise. Self-intersecting paths can contain sub-areas that cancel each other out, which makes this value zero even though the path has apparent area.


clipping boolean If true, this path should be used as a clipping path.


evenodd boolean If true, the even-odd rule should be used to determine insideness.

fillColor color object The fill color of the path.

filled boolean If true, the path be filled.

fillOverprint boolean If true, the art beneath a filled object should be overprinted.

guides boolean If true, this path is a guide object.



note string The note text assigned to the path.




pathPoints PathPoints collection object

Read-only. The path points contained in this path item.

polarity PolarityValues The polarity of the path.


resolution number (double) The resolution of the path in dots per inch (dpi).

selectedPathPoints PathPoints collection object

Read-only. All of the selected path points in the path.

strokeCap StrokeCap The type of line capping.

strokeColor color object The stroke color for the path.

stroked boolean If true, the path should be stroked.


TextPath methods

strokeDashes object Dash lengths. Set to an empty object, {}, for a solid line.

strokeDashOffset number (double) The default distance into the dash pattern at which the pattern should be started.

strokeJoin StrokeJoin Type of joints for the path.

strokeMiterLimit number (double) When a default stroke join is set to mitered, this property specifies when the join will be converted to beveled (squared-off ) by default. The default miter limit of 4 means that when the length of the point reaches four times the stroke weight, the join switches from a miter join to a bevel join. A value of 1 specifies a bevel join. Range: 1 to 500 Default: 4

strokeOverprint boolean If true, the art beneath a stroked object should be overprinted.

strokeWidth number (double) Width of the stroke.






setEntirePath

(pathPoints) PathPoints objectNothing Sets the path using the

specified anchor points.


TextRangeA range of text in a specific text art item. TextRange gives you access to the text contained in text art items.

TextRange properties


characterAttributes CharacterAttributes collection object


characterOffset number (long) Offset of the first character.


Read-only. All the characters in this text range.

characterStyles CharacterStyles collection object

Read-only. All referenced character styles in the text range.

contents string The text string.


Read-only. All the insertion points in this text range.

kerning number (long) Controls the spacing between two characters, in thousandths of an em. An integer.

length number (long) Length of text range. Minimum: 0


Read-only. All the lines in this text range.

paragraphAttributes ParagraphAttributes collection object

Read-only. The paragraph properties for the text range.


Read-only. All the paragraphs in this text range.

paragraphStyles ParagraphStyles collection object

Read-only. All referenced paragraph styles in the text range.

parent TextRange object Read-only. The object’s container.

story Story object Read-only. The story to which the text range belongs.


Read-only. All of the text in this text range.


Read-only. The selected text ranges in the text range.

typename string Read-only. The class name o f the object.


Read-only. All the words contained in this text range.


TextRange methods

➤ Manipulating text

This example illustrates how to obtain a sub-range from a text object.

// Use text ranges and sub ranges to change size // of the first character of each wordif ( app.documents.length > 0 ) {

for ( i = 0; i < app.activeDocument.textFrames.length; i++ ) {text = app.activeDocument.textFrames[i].textRange;for ( j = 0 ; j < text.words.length; j++ ) {

//each word is a textRange object textWord = text.words[j];

// Characters are textRanges too.// Get the first character of each word and increase it’s size.firstChars = textWord.characters[0];firstChars.size = firstChars.size * 1.5;

}}

}

Method Parameter Type Returns What it does

changeCaseTo

(type) CaseChangeType Nothing Changes the capitalization of text.

deSelect

()

Nothing Deselects the text range.

duplicate



TextRange object

Creates a duplicate of this object.

move



TextRange object

Moves the object.

remove

()


select

([addToDocument]) booleanNothing Selects the text range. If

addToDocument is true, adds this to the current selection; otherwise replaces the current selection.


TextRangesA collection of TextRange objects.

TextRanges properties

TextRanges methods






index

(itemKey) string, numberTextRange object

Get an element from the collection

removeAll

()

Nothing Deletes all elements in the object.


TracingObjectA tracing object, which associates source raster art item with a vector-art plugin group created by tracing. Scripts can initiate tracing using PlacedItem.trace or RasterItem.trace. The resulting PluginItem object represents the vector art group, and has this object in its tracing property.

A script can force the tracing operation by calling the document’s redraw method. The operation is asynchronous, so a script should call redraw after creating the tracing object, but before accessing its properties or expanding the tracing to convert it to an art item group.

The read-only properties that describe the tracing result have valid values only after the first tracing operation completes. A value of 0 indicates that the operation has not yet been completed.

TracingObject properties


anchorCount number (long) Read-only. The number of anchors in the tracing result.

areaCount number (long) Read-only. The number of areas in the tracing result.

imageResolution number (real) Read-only. The resolution of the source image in pixels per inch.


pathCount number (long) Read-only. The number of paths in the tracing result.

sourceArt PlacedItem or RasterItem object

The raster art used to create the associated vector-art plugin group.

tracingOptions TracingOptions object The options used to convert the raster artwork to vector art.


usedColorCount number (long) Read-only. The number of colors used in the tracing result.


TracingObject methods


expandTracing

([viewed]) booleanGroupItem object

Converts the vector art into a new group item. The new GroupItem object replaces the PluginItem object in the document. By default, viewed is false, and the new group contains only the tracing result (the filled or stroked paths). If viewed is true, the new group retains additional information that was specified for the viewing mode, such as outlines and overlays.

Deletes this object and its associated PluginItem object. Any group-level attributes that were applied to the plugin item are applied to the top level of the new group item.

releaseTracing

()

PlacedItem or RasterItem object

Reverts the artwork in the document to the original source raster art and removes the traced vector art. Returns the original object used to create the tracing, and deletes this object and its associated PluginItem object.


TracingOptionsA set of options used in converting raster art to vector art by tracing.

TracingOptions properties


cornerAngle number (double) The sharpness, in degrees of a turn in the original image that is considered a corner in the tracing result path. Range: 0 to 180

fills boolean If true, trace with fills. At least one of fills or strokes must be true.

livePaintOutput boolean If true, result is LivePaint art. If false, it is classic art.

Note: A script should only set this value in preparation for a subsequent expand operation. Leaving a tracing on the artboard when this property is true can lead to unexpected application behavior.

maxColors number (long) The maximum number of colors allowed for automatic palette generation. Used only if tracingMode is color or grayscale. Range: 2 to 256

maxStrokeWeight number (double) The maximum stroke weight, when strokes is true. Range: 0.01 to 100.0

minArea number (long) The smallest feature, in square pixels, that is traced. For example, if it is 4, a feature of 2 pixels wide by 2 pixels high is traced.

minStrokeLength number (double) The minimum length in pixels of features in the original image that can be stroked, when strokes is true. Smaller features are omitted. Range: 0.0 to 200.0 Default: 20.0

outputToSwatches boolean If true, named colors (swatches) are generated for each new color created by the tracing result. Used only if tracingMode is color or grayscale.

palette string The name of a color palette to use for tracing. If the empty string, use the automatic palette. Used only if tracingMode is color or grayscale.


pathFitting number (double) The distance between the traced shape and the original pixel shape. Lower values create a tighter path fitting. Higher values create a looser path fitting. Range: 0.0 to 10.0


TracingOptions methods

preprocessBlur number (double) The amount of blur used during preprocessing, in pixels. Blurring helps reduce small artifacts and smooth jagged edges in the tracing result. Range: 0.0 to 2.0

preset string Read-only. The name of a preset file containing these options.

resample boolean If true, resample when tracing. (This setting is not captured in a preset file.)

Always true when the raster source art is placed or linked.

resampleResolution number (double) The resolution to use when resampling in pixels per inch (ppi). Lower resolution increases the speed of the tracing operation. (This setting is not captured in a preset file.)

strokes boolean If true, trace with strokes. At least one of fills or strokes must be true. Used only if tracingMode is black-and-white.

threshold number (long) The threshold value of black-and-white tracing. All pixels with a grayscale value greater than this are converted to black. Used only if tracingMode is black-and-white. Range: 0 to 255

tracingMode TracingModeType The color mode for tracing.


viewRaster ViewRasterType The view for previews of the raster image. (This setting is not captured in a preset file.)

viewVector ViewVectorType The view for previews of the vector result. (This setting is not captured in a preset file.)



loadFromPreset

(presetName) stringboolean Loads a set of options from the specified preset, as

found in the Application.tracingPresetList array.

storeToPreset

(presetName) stringboolean Saves this set of options in the specified preset. Use

a name found in the Application.tracingPresetList array, or a new name to create a new preset. For an existing preset, overwrites an unlocked preset and returns true. Returns false if the preset is locked.


VariableA document-level variable that can be imported or exported. See also Dataset.

Variable properties

Variable methods


kind VariableKind The variable’s type.

name string The name of this variable.


Read-only. All of the artwork n this document.

parent object Read-only. The object that contains the variable.



remove

()

Nothing Removes the variable from the collection of variables.


VariablesThe collection of Variable objects in the document. For an example of how to create variables, see Using variables and datasets.

Variables properties

Variables methods


length number Read-only. The number of variables in the document

parent object Read-only. The object that contains the collection of variables.



add

()

Variable object

Adds a new variable to the collection.

getByName

(name) stringVariable object


index

(itemKey) string, numberVariable object

Get an element from the collection.

removeAll

()



ViewA document view in an Illustrator document, which represents a window view onto a document. Scripts cannot create new views, but can modify some properties of existing views, including the center point, screen mode, and zoom.

View properties

➤ Setting a view to full screen

This example illustrates how to set the first view of the frontmost document to full screen mode.

// Set the first view of the frontmost document to full screen

if ( app.documents.length > 0 ) {app.documents[0].views[0].screenMode = ScreenMode.FULLSCREEN;

}


bounds array of 4 numbers Read-only. The bounding rectangle of this view relative to the current document’s bounds.

centerPoint array of 2 numbers The center point of this view relative to the current document’s bounds.

parent Document object Read-only. The document that contains this view.

screenMode ScreenMode The mode of display for this view.


zoom number (double) The zoom factor of this view, where 100.0 is 100%.


ViewsA collection of View objects in a document.

Views properties

Views methods






index

(itemKey) string, numberView object Gets an element from the collection.


WordsA collection of words in a text item, where each word is a TextRange object. The elements are not named; you must access them by index.

Words properties

Words methods

➤ Counting words

This script displays the total number of words contained in all of the text art items in the current document.

// Count all words in current document and report total

if ( app.documents.length > 0 ) {numWords = 0;for ( i = 0; i < app.activeDocument.textFrames.length; i++) {

numWords += app.activeDocument.textFrames[i].words.length;}alert("There are " + numWords + " words in the document.");

}

➤ Applying attributes to words

// Apply a color to certain words

if ( app.documents.length > 0 && app.activeDocument.textFrames.length > 0 ) {






add

(contents[, relativeObject][, insertionLocation])


TextRange object

Adds a word to the current document at the specified location. If no location is specified, adds it to the containing text frame after the current word selection or insertion point.

addBefore

(contents) stringTextRange object

Adds a word before the current word selection or insertion point.

index



removeAll

()



// Create the color to apply to the wordswordColor = new RGBColor();wordColor.red = 255;wordColor.green = 0;wordColor.blue = 255;// Set the value of the word to look forsearchWord = "the";// Iterate through all words in the document// and color the words that match searchWordfor ( i = 0; i < app.activeDocument.textFrames.length; i++ ) {

textArt = activeDocument.textFrames[i];for ( j = 0; j < textArt.words.length; j++) {

word = textArt.words[j];if ( word.contents == searchWord ) {

word.filled = true;word.fillColor = wordColor;

}}

}}

264

6 File and Folder Object Reference

Overview Because path name syntax is very different in Windows, Mac OS and UNIX, the File and Folder objects are defined to provide platform-independent access to the underlying file system. A File object is associated with a disk file, a Folder object with a directory or folder.

● The Folder object supports file-system functionality such as traversing the hierarchy, creating, renaming or removing files, or resolving file aliases.

● The File object supports I/O functions to read or write files.

File and Folder objects can be used anywhere a path name is required, such as in properties and arguments for files and folders.

For a description of the pathname syntax and object usage, see Chapter 4, “Using File and Folder Objects." This chapter provides detail about the classes and objects, their properties and methods, and the supported encoding names:

● File Object

● Folder Object

● File and Folder Error Messages

● File and Folder Supported Encoding Names

File ObjectRepresents a file in the local file system in an platform-independent manner. All properties and methods resolve file system aliases automatically and act on the original file unless otherwise noted.

File object constructors

To create a File object, use the File function or the new operator. The constructor accepts full or partial path names, and returns the new object. The CRLF sequence for the file is preset to the system default, and the encoding is preset to the default system encoding.

File ([path]); //can return a Folder objectnew File ([path]); //always returns a File object

path Optional. The absolute or relative path to the file associated with this object, specified in platform-specific or URI format; see Specifying Paths. The value stored in the object is the absolute path.

The path need not refer to an existing file. If not supplied, a temporary name is generated.

If the path refers to an existing folder:

● The File function returns a Folder object instead of a File object.

● The new operator returns a File object for a nonexisting file with the same name.

Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 265

File class properties

This property is available as a static property of the File class. It is not necessary to create an instance to access it.

File class functions

These functions are available as static methods of the File class. It is not necessary to create an instance to call them.

fs String The name of the file system. Read-only. One of Windows, Macintosh, or Unix.

decode

File.decode (what)

Decodes the specified string as required by RFC 2396 and returns the decoded string.

what String. The encoded string to decode.

All special characters must be encoded in UTF-8 and stored as escaped characters starting with the percent sign followed by two hexadecimal digits. For example, the string "my%20file" is decoded as "my file".

Special characters are those with a numeric value greater than 127, except the following:

/ - _ . ! ~ * ' ( )

encode

File.encode (what)

Encodes the specified string as required by RFC 2396 and returns the encoded string.

All special characters are encoded in UTF-8 and stored as escaped characters starting with the percent sign followed by two hexadecimal digits. For example, the string "my file" is encoded as "my%20file".


/ - _ . ! ~ * ' ( )

what String. The string to encode.

isEncodingAvailable

File.isEncodingAvailable (name)

Returns true if your system supports the specified encoding, false otherwise.

name String. The encoding name.


openDialog

File.openDialog([prompt][,select])

Opens the built-in platform-specific file-browsing dialog in which a user can select an existing file to open.

If the user clicks OK, returns a File object for the selected file. If the user cancels, returns null.

prompt Optional. A string containing the prompt text, if the dialog allows a prompt.

select Optional. A file or files to be preselected when the dialog opens:

● In Windows, a string containing a comma-separated list of file types with descriptive text, to be displayed in the bottom of the dialog as a drop-down list from which the user can select which types of files to display.

Each element starts with the descriptive text, followed by a colon and the file search masks for this text, separated by semicolons. For example, to display two choices, one labeled Text Files that allows selection of text files with extensions .TXT and .DOC, and the other labeled All files that allows selection of all files:

Text Files:*.TXT;*.DOC,All files:*

● In Mac OS, a string containing the name of a function defined in the current JavaScript scope that takes a File object argument. The function is called for each file about to be displayed in the dialog, and the file is displayed only when the function returns true.

saveDialog

File.saveDialog([prompt][,select])

Opens the built-in platform-specific file-browsing dialog in which a user can select an existing file location to which to save this file.

If the user clicks OK, returns a File object for the selected file, and overwrites the existing file. If the user cancels, returns null.








File object properties

These properties are available for File objects.

absoluteURI String The full path name for the referenced file in URI notation. Read-only.

alias Boolean When true, the object refers to a file system alias or shortcut. Read-only.

created Date The creation date of the referenced file, or null if the object does not refer to a file on disk. Read-only.

creator String The Mac OS file creator as a four-character string. In Windows or UNIX, value is "????". Read-only.

encoding String Gets or sets the encoding for subsequent read/write operations. One of the encoding constants listed in File and Folder Supported Encoding Names. If the value is not recognized, uses the system default encoding.

A special encoder, BINARY, is used to read binary files. It stores each byte of the file as one Unicode character regardless of any encoding. When writing, the lower byte of each Unicode character is treated as a single byte to write.

eof Boolean When true, a read attempt caused the current position to be beyond the end of the file, or the file is not open. Read only.

error String A message describing the last file system error; see File and Folder Error Messages. Setting this value clears any error message and resets the error bit for opened files.

exists Boolean When true, the path name of this object refers to an existing file. Read only.

fsName String The platform-specific name of the referenced file as a full path name. Read-only.

hidden Boolean When true, the file is not shown in the platform-specific file browser. Read/write. If the object references a file-system alias or shortcut, the flag is altered on the alias, not on the original file.

length Number The size of the file in bytes. Can be set only for a file that is not open, in which case it truncates or pads the file with 0-bytes to the new length.

lineFeed String How line feed characters are written. One of:

windows: Windows stylemac: Mac OS styleunix: UNIX style

modified Date The date of the referenced file’s last modification, or null if the object does not refer to a file on disk. Read-only.

name String The name of the referenced file without the path specification. Read-only.

parent Folder The Folder object for the folder that contains this file. Read-only.


File object functions

These functions are available for File objects.

path String The path portion of the absolute URI, or the empty string If the name does not have a path. Read-only.

readonly Boolean When true, prevents the file from being altered or deleted. If the referenced file is a file-system alias or shortcut, the flag is altered on the alias, not on the original file.

relativeURI String The path name for the referenced file in URI notation, relative to the current folder. Read-only.

type String The Mac OS file type as a four-character string. In Windows and UNIX, the value is "????". Read-only.

close

fileObj.close ()

Closes this open file. Returns true on success, false if there are I/O errors.

copy

fileObj.copy (target)

Copies this object’s referenced file to the specified target location. Resolves any aliases to find the source file. If a file exists at the target location, it is overwritten. Returns true if the copy was successful, false otherwise.

target A string with the URI path to the target location, or a File object that references the target location.

createAlias

fileObj.createAlias

(toFile, [isFinderAlias])

Makes this file into a file-system alias or shortcut to the specified file. The referenced file for this object must not yet exist on disk. Returns true if the operation was successful, false otherwise.

toFile The File object for the target of the new alias.

isFinderAlias Optional, Mac OS only. When true, the alias is created as a legacy Finder alias. When false (the default), the alias is created as a Unix symlink.

execute

fileObj.execute ()

Opens this file using the appropriate application (as if it had been double-clicked in a file browser). You can use this method to run scripts, launch applications, and so on.

Returns true immediately if the application launch was successful.

getRelativeURI

fileObj.getRelativeURI([basePath])

Returns a string containing the URI for this file or folder relative to the specified base path, in URI notation. If no base path is supplied, returns the URI relative to the path of the current folder.

basePath Optional. A string containing the base path for the relative URI. Default is the current folder.


open

fileObj.open(mode[,type][,creator])

Open the file for subsequent read/write operations. The method resolves any aliases to find the file. Returns true if the file has been opened successfully, false otherwise.

The method attempts to detect the encoding of the open file. It reads a few bytes at the current location and tries to detect the Byte Order Mark character 0xFFFE. If found, the current position is advanced behind the detected character and the encoding property is set to one of the strings UCS-2BE, UCS-2LE, UCS4-BE, UCS-4LE, or UTF-8. If the marker character is not found, it checks for zero bytes at the current location and makes an assumption about one of the above formats (except UTF-8). If everything fails, the encoding property is set to the system encoding.

Note: Be careful about opening a file more than once. The operating system usually permits you to do so, but if you start writing to the file using two different File objects, you can destroy your data.

mode A string indicating the read/write mode. One of:

r: (read) Opens for reading. If the file does not exist or cannot be found, the call fails.

w: (write) Opens a file for writing. If the file exists, its contents are destroyed. If the file does not exist, creates a new, empty file.

e: (edit) Opens an existing file for reading and writing.

type Optional. In Mac OS, the type of a newly created file, a 4-character string. Ignored in Windows and UNIX.

creator Optional. In Mac OS, the creator of a newly created file, a 4-character string. Ignored in Windows and UNIX.


openDlg

fileObj.OpenDlg([prompt][,select])

Opens the built-in platform-specific file-browsing dialog, in which the user can select an existing file to open. If the user clicks OK, returns a File or Folder object for the selected file or folder. If the user cancels, returns null.

Differs from the class method openDialog() in that it presets the current folder to this File object’s parent folder and the current file to this object’s associated file.







read

fileObj.read ([chars])

Reads the contents of the file starting at the current position, and returns a string that contains up to the specified number of characters.

chars Optional. An integer specifying the number of characters to read. By default, reads from the current position to the end of the file. If the file is encoded, multiple bytes might be read to create single Unicode characters.

readch

fileObj.readch ()

Reads a single text character from the file at the current position, and returns it in a string. Line feeds are recognized as CR, LF, CRLF, or LFCR pairs. If the file is encoded, multiple bytes might be read to create single Unicode characters.

readln

fileObj.readln ()

Reads a single line of text from the file at the current position, and returns it in a string. Line feeds are recognized as CR, LF, CRLF, or LFCR pairs. If the file is encoded, multiple bytes might be read to create single Unicode characters.

remove

fileObj.remove ()

Deletes the file associated with this object from disk, immediately, without moving it to the system trash. Returns true if the file is deleted successfully.

Does not resolve aliases; instead, deletes the referenced alias or shortcut file itself.

Note: Cannot be undone. It is recommended that you prompt the user for permission before deleting.


rename

fileObj.rename (newName)

Renames the associated file. Returns true on success.

Does not resolve aliases, but renames the referenced alias or shortcut file itself.

newName The new file or folder name, with no path.

resolve

fileObj.resolve ()

If this object references an alias or shortcut, this method resolves that alias and returns a new File object that references the file-system element to which the alias resolves.

Returns null if this object does not reference an alias, or if the alias cannot be resolved.

saveDlg

fileObj.saveDlg([prompt][,preset])

Opens the built-in platform-specific file-browsing dialog, in which the user can select an existing file location at which to save this file. If the user clicks OK, returns a File or Folder object for the selected file or folder. If the user cancels, returns null.

Differs from the class method saveDialog() in that it presets the current folder to this File object’s parent folder and the file to this object’s associated file, and prompts the user to confirm before overwriting an existing file.


preset Optional. A file or files to be preselected when the dialog opens:





seek

fileObj.seek (pos, mode)

Seeks to the specified position in the file, and returns true if the position was changed. The new position cannot be less than 0 or greater than the current file size.

pos The new current position in the file as an offset in bytes from the start, current position, or end, depending on the mode.

mode The seek mode, one of:

0: Seek to absolute position, where pos=0 is the first byte of the file.1: Seek relative to the current position.2. Seek backward from the end of the file.

tell

fileObj.tell ()

Returns the current position as a byte offset from the start of the file.


write

fileObj.write (text[, text...]...)

Writes the specified text to the file at the current position. Returns true on success.

For encoded files, writing a single Unicode character may write multiple bytes.

Note: Be careful not to write to a file that is open in another application or object, as this can overwrite existing data.

text One or more strings to write, which are concatenated to form a single string.

writeln

fileObj.writeln (text[, text...]...)

Writes the specified text to the file at the current position, and appends a Line Feed sequence in the style specified by the linefeed property. Returns true on success.

For encoded files, writing a single Unicode character may write multiple bytes.

Note: Be careful not to write to a file that is open in another application or object, as this can overwrite existing data.



Folder Object Represents a file-system folder or directory in a platform-independent manner. All properties and methods resolve file system aliases automatically and act on the original file unless otherwise noted.

Folder object constructors

To create a Folder object, use the Folder function or the new operator. The constructor accepts full or partial path names, and returns the new object.

Folder ([path]); //can return a File objectnew Folder ([path]); //always returns a Folder object

Folder class properties

These properties are available as static properties of the Folder class. It is not necessary to create an instance to access them.

path Optional. The absolute or relative path to the folder associated with this object, specified in URI format; see Specifying Paths. The value stored in the object is the absolute path.

The path need not refer to an existing folder. If not supplied, a temporary name is generated.

If the path refers to an existing file:

● The Folder function returns a File object instead of a Folder object.

● The new operator returns a Folder object for a nonexisting folder with the same name.

appData Folder A Folder object for the folder that contains application data for all users. Read-only.

● In Windows, the value of %APPDATA% (by default, C:\Documents and Settings\All Users\Application Data)

● In Mac OS, /Library/Application Support

commonFiles Folder A Folder object for the folder that contains files common to all programs. Read-only.

● In Windows, the value of %CommonProgramFiles% (by default, C:\Program Files\Common Files)

● In Mac OS,/Library/Application Support

current Folder A Folder object for the current folder. Assign either a Folder object or a string containing the new path name to set the current folder.

fs String The name of the file system. Read-only. One of Windows, Macintosh, or Unix.

myDocuments Folder A Folder object for the default document folder. Read-only.

● In Windows, C:\Documents and Settings\username\My Documents

● In Mac OS, ~/Documents

startup Folder A Folder object for the folder containing the executable image of the running application. Read-only.


Folder class functions

These functions are available as a static methods of the Folder class. It is not necessary to create an instance in order to call them.

system Folder A Folder object for the folder containing the operating system files. Read-only.

● In Windows, the value of %windir% (by default, C:\Windows)

● In Mac OS,/System

temp Folder A Folder object for the default folder for temporary files. Read-only.

trash Folder A Folder object for the folder containing deleted items. Read-only.

userData Folder A Folder object for the folder that contains application data for the current user. Read-only.

● In Windows, the value of %APPDATA% (by default, C:\Documents and Settings\username\Application Data)

● In Mac OS, ~/Library/Application Support

decode

Folder.decode (what)

Decodes the specified string as required by RFC 2396 and returns the decoded string.

what String. The encoded string to decode.

All special characters must be encoded in UTF-8 and stored as escaped characters starting with the percent sign followed by two hexadecimal digits. For example, the string "my%20file" is decoded as "my file".


/ - _ . ! ~ * ' ( )

encode

Folder.encode (what)

Encodes the specified string as required by RFC 2396 and returns the encoded string.

All special characters are encoded in UTF-8 and stored as escaped characters starting with the percent sign followed by two hexadecimal digits. For example, the string "my file" is encoded as "my%20file".


/ - _ . ! ~ * ' ( )

what String. The string to encode.

isEncodingAvailable

File.isEncodingAvailable (name)

Returns true if your system supports the specified encoding, false otherwise.

name String. The encoding name.


Folder object properties

These properties are available for Folder objects.

selectDialog

Folder.selectDialog([prompt][,preset])

Opens the built-in platform-specific file-browsing dialog. If the user clicks OK, returns a Folder object for the selected folder. If the user cancels, returns null.

Differs from the object method selectDlg() in that it does not preselect a folder.


preset Optional. A Folder object for a folder to be preselected when the dialog opens.

absoluteURI String The full path name for the referenced folder in URI notation. Read-only.

alias Boolean When true, the object refers to a file system alias or shortcut. Read-only.

created Date The creation date of the referenced folder, or null if the object does not refer to a folder on disk. Read-only.

error String A message describing the last file system error; see File and Folder Error Messages. Setting this value clears any error message and resets the error bit for opened folders.

exists Boolean When true, the path name of this object refers to an existing folder. Read only.

fsName String The platform-specific name of the referenced folder as a full path name. Read-only.

modified Date The date of the referenced folder's last modification, or null if the object does not refer to a folder on disk. Read-only.

name String The name of the referenced folder without the path specification. Read-only.

parent Folder The Folder object for the folder that contains this folder, or null if this object refers to the root folder of a volume. Read-only.

path String The path portion of the absolute URI, or the empty string If the name does not have a path. Read-only.

relativeURI String The path name for the referenced folder in URI notation, relative to the current folder. Read-only.


Folder object functions

These functions are available for Folder objects.

create

folderObj.create ()

Creates a folder at the location to which the path name points. Returns true if the folder was created successfully.

execute

folderObj.execute ()

Opens this folder in the file browser (as if it had been double-clicked in a file browser). Returns true immediately if the folder was opened successfully.

getFiles

folderObj.getFiles ([mask])

Returns an array of File and Folder objects for the contents of this folder, filtered by the supplied mask, or null if this object’s referenced folder does not exist.

mask Optional. A search mask for file names. A string that can contain question mark (?) and asterisk (*) wild cards. Default is "*", which matches all file names.

Can also be the name of a function that takes a File or Folder object as its argument. It is called for each file or folder found in the search; if it returns true, the object is added to the return array.

Note: In Windows, all aliases end with the extension .lnk, which is stripped from the file name when found to preserve compatibility with other operating systems. You can search for all aliases by supplying the search mask "*.lnk", but note that such code is not portable.

getRelativeURI

folderObj.getRelativeURI([basePath])

Returns a string containing the URI for this folder relative to the specified base path, in URI notation. If no base path is supplied, returns the URI relative to the path of the current folder.

basePath Optional. A string containing the base path for the relative URI. Default is the current folder.

remove

folderObj.remove ()

Deletes the empty folder associated with this object from disk, immediately, without moving it to the system trash. Returns true if the folder is deleted successfully.

● Folders must be empty before they can be deleted.

● Does not resolve aliases; instead, deletes the referenced alias or shortcut file itself.

Note: Cannot be undone. It is recommended that you prompt the user for permission before deleting.

rename

folderObj.rename (newName)

Renames the associated folder. Returns true on success.

● Does not resolve aliases; instead, renames the referenced alias or shortcut file itself.

newName The new folder name, with no path.

resolve

folderObj.resolve ()

If this object references an alias or shortcut, this method resolves that alias and returns a new Folder object that references the file-system element to which the alias resolves.

Returns null if this object does not reference an alias, or if the alias cannot be resolved.


selectDlg

folderObj.selectDlg([prompt][,preset])

Opens the built-in platform-specific file-browsing dialog. If the user clicks OK, returns a File or Folder object for the selected file or folder. If the user cancels, returns null.

Differs from the class method selectDialog() in that it preselects this folder.


preset Optional. A Folder object for a folder to be preselected when the dialog opens.


File and Folder Error Messages The following messages can be returned in the error property.

File or folder does not exist The file or folder does not exist, but the parent folder exists.

File or folder already exists The file or folder already exists.

I/O device is not open An I/O operation was attempted on a file that was closed.

Read past EOF Attempt to read beyond the end of a file.

Conversion error The content of the file cannot be converted to Unicode.

Partial multibyte character found The character encoding of the file data has errors.

Permission denied The OS did not allow the attempted operation.

Cannot change directory Cannot change the current folder.

Cannot create Cannot create a folder.

Cannot rename Cannot rename a file or folder.

Cannot delete Cannot delete a file or folder.

I/O error Unspecified I/O error.

Cannot set size Setting the file size failed.

Cannot open Opening of a file failed.

Cannot close Closing a file failed.

Read error Reading from a file failed.

Write error Writing to a file failed.

Cannot seek Seek failure.

Cannot execute Unable to execute the specified file.


File and Folder Supported Encoding NamesThe following list of names is a basic set of encoding names supported by the File object. Some of the character encoders are built in, while the operating system is queried for most of the other encoders. Depending on the language packs installed, some of the encodings may not be available. Names that refer to the same encoding are listed in one line. Underlines are replaced with dashes before matching an encoding name.

The File object processes an extended Unicode character with a value greater that 65535 as a Unicode surrogate pair (two characters in the range between 0xD700-0xDFFF).

Built-in encodings are:

US-ASCII, ASCII,ISO646-US,I SO-646.IRV:1991, ISO-IR-6,ANSI-X3.4-1968,CP367,IBM367,US,ISO646.1991-IRVUCS-2,UCS2, ISO-10646-UCS-2UCS2LE,UCS-2LE,ISO-10646-UCS-2LEUCS2BE,UCS-2BE,ISO-10646-UCS-2BEUCS-4,UCS4, ISO-10646-UCS-4UCS4LE,UCS-4LE,ISO-10646-UCS-4LEUCS4BE,UCS-4BE,ISO-10646-UCS-4BEUTF-8,UTF8,UNICODE-1-1-UTF-8,UNICODE-2-0-UTF-8,X-UNICODE-2-0-UTF-8UTF16,UTF-16,ISO-10646-UTF-16UTF16LE,UTF-16LE,ISO-10646-UTF-16LEUTF16BE,UTF-16BE,ISO-10646-UTF-16BECP1252,WINDOWS-1252,MS-ANSIISO-8859-1,ISO-8859-1,ISO-8859-1:1987,ISO-IR-100,LATIN1MACINTOSH,X-MAC-ROMANBINARY

The ASCII encoder raises errors for characters greater than 127, and the BINARY encoder simply converts between bytes and Unicode characters by using the lower 8 bits. The latter encoder is convenient for reading and writing binary data.

Additional encodings

In Windows, all encodings use code pages, which are assigned numeric values. The usual Western character set that Windows uses, for example, is the code page 1252. You can select Windows code pages by prepending the number of the code page with "CP" or "WINDOWS": for example, "CP1252" for the code page 1252. The File object has many other built-in encoding names that match predefined code page numbers. If a code page is not present, the encoding cannot be selected.

In Mac OS, you can select encoders by name rather than by code page number. The File object queries Mac OS directly for an encoder. As far as Mac OS character sets are identical with Windows code pages, Mac OS also knows the Windows code page numbers.

In UNIX, the number of available encoders depends on the installation of the iconv library.

Common encoding names

The following encoding names are implemented both in Windows and in Mac OS:

UTF-7,UTF7,UNICODE-1-1-UTF-7,X-UNICODE-2-0-UTF-7ISO-8859-2,ISO-8859-2,ISO-8859-2:1987,ISO-IR-101,LATIN2ISO-8859-3,ISO-8859-3,ISO-8859-3:1988,ISO-IR-109,LATIN3ISO-8859-4,ISO-8859-4,ISO-8859-4:1988,ISO-IR-110,LATIN4,BALTICISO-8859-5,ISO-8859-5,ISO-8859-5:1988,ISO-IR-144,CYRILLICISO-8859-6,ISO-8859-6,ISO-8859-6:1987,ISO-IR-127,ECMA-114,ASMO-708,ARABICISO-8859-7,ISO-8859-7,ISO-8859-7:1987,ISO-IR-126,ECMA-118,ELOT-928,GREEK8,GREEKISO-8859-8,ISO-8859-8,ISO-8859-8:1988,ISO-IR-138,HEBREW


ISO-8859-9,ISO-8859-9,ISO-8859-9:1989,ISO-IR-148,LATIN5,TURKISHISO-8859-10,ISO-8859-10,ISO-8859-10:1992,ISO-IR-157,LATIN6ISO-8859-13,ISO-8859-13,ISO-IR-179,LATIN7ISO-8859-14,ISO-8859-14,ISO-8859-14,ISO-8859-14:1998,ISO-IR-199,LATIN8ISO-8859-15,ISO-8859-15,ISO-8859-15:1998,ISO-IR-203ISO-8859-16,ISO-885,ISO-885,MS-EECP850,WINDOWS-850,IBM850CP866,WINDOWS-866,IBM866CP932,WINDOWS-932,SJIS,SHIFT-JIS,X-SJIS,X-MS-SJIS,MS-SJIS,MS-KANJICP936,WINDOWS-936,GBK,WINDOWS-936,GB2312,GB-2312-80,ISO-IR-58,CHINESECP949,WINDOWS-949,UHC,KSC-5601,KS-C-5601-1987,KS-C-5601-1989,ISO-IR-149,KOREANCP950,WINDOWS-950,BIG5,BIG-5,BIG-FIVE,BIGFIVE,CN-BIG5,X-X-BIG5CP1251,WINDOWS-1251,MS-CYRLCP1252,WINDOWS-1252,MS-ANSICP1253,WINDOWS-1253,MS-GREEKCP1254,WINDOWS-1254,MS-TURKCP1255,WINDOWS-1255,MS-HEBRCP1256,WINDOWS-1256,MS-ARABCP1257,WINDOWS-1257,WINBALTRIMCP1258,WINDOWS-1258CP1361,WINDOWS-1361,JOHABEUC-JP,EUCJP,X-EUC-JPEUC-KR,EUCKR,X-EUC-KRHZ,HZ-GB-2312X-MAC-JAPANESEX-MAC-GREEKX-MAC-CYRILLICX-MAC-LATINX-MAC-ICELANDICX-MAC-TURKISH

Additional Windows encoding namesCP437,IBM850,WINDOWS-437CP709,WINDOWS-709,ASMO-449,BCONV4EBCDICKOI-8RKOI-8UISO-2022-JPISO-2022-KR

Additional Mac OS encoding names

These names are alias names for encodings that Mac OS might know.

TIS-620,TIS620,TIS620-0,TIS620.2529-1,TIS620.2533-0,TIS620.2533-1,ISO-IR-166CP874,WINDOWS-874JP,JIS-C6220-1969-RO,ISO646-JP,ISO-IR-14JIS-X0201,JISX0201-1976,X0201JIS-X0208,JIS-X0208-1983,JIS-X0208-1990,JIS0208,X0208,ISO-IR-87JIS-X0212,JIS-X0212.1990-0,JIS-X0212-1990,X0212,ISO-IR-159CN,GB-1988-80,ISO646-CN,ISO-IR-57ISO-IR-16,CN-GB-ISOIR165KSC-5601,KS-C-5601-1987,KS-C-5601-1989,ISO-IR-149EUC-CN,EUCCN,GB2312,CN-GBEUC-TW,EUCTW,X-EUC-TW

UNIX encodings

In UNIX, the File object looks for the presence of the iconv library, and uses whatever encoding it finds there. If you need a special encoding in UNIX, make sure that there is an iconv encoding module installed that converts between UTF-16 (the internal format that the File object uses) and the desired encoding.

7
Scripting Constants
This section lists and describes the enumerations defined for use with Illustrator JavaScript properties and methods.

Constant Type Values What it means

AlternateGlyphsForm DEFAULTFORMEXPERTFULLWIDTHHALFWIDTHJIS78FORMJIS83FORMPROPORTIONALWIDTHQUARTERWIDTHTHIRDWIDTHTRADITIONAL

AutoKernType AUTONOAUTOKERNOPTICAL

AutoLeadingType BOTTOMTOBOTTOMTOPTOTOP

BaselineDirectionType StandardTateChuYokoVerticalRotated

BlendAnimationType INBUILDINSEQUENCENOBLENDANIMATION

BlendModes COLORBLENDCOLORBURNCOLORDODGEDARKENDIFFERENCEEXCLUSIONHARDLIGHTHUELIGHTENLUMINOSITYMULTIPLYNORMALOVERLAYSATURATIONBLENDSCREENSOFTLIGHT

The blend mode used when compositing an object.

BurasagariTypeEnum ForcedNoneStandard

CaseChangeType LOWERCASESENTENCECASETITLECASEUPPERCASE

281

Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 282

ColorConversion COLORCONVERSIONREPURPOSECOLORCONVERSIONTODESTNone

ColorDestination COLORDESTINATIONDOCCMYKCOLORDESTINATIONDOCRGBCOLORDESTINATIONPROFILECOLORDESTINATIONWORKINGCMYKCOLORDESTINATIONWORKINGRGBNone

ColorDitherMethod DIFFUSIONNOISENOREDUCTIONPATTERNDITHER

The method used to dither colors in exported GIF and PNG8 images.

ColorModel PROCESSREGISTRATIONSPOT

ColorProfile INCLUDEALLPROFILEINCLUDEDESTPROFILEINCLUDERGBPROFILELEAVEPROFILEUNCHANGEDNone

ColorReductionMethod ADAPTIVEPERCEPTUALSELECTIVEWEB

The method used to reduce the number of colors in exported GIF and PNG8 images.

ColorType CMYKGRADIENTGRAYNONEPATTERNRGBSPOT

The color specification for an individual color.

Compatibility ILLUSTRATOR3ILLUSTRATOR8ILLUSTRATOR9ILLUSTRATOR10ILLUSTRATOR11ILLUSTRATOR12JAPANESEVERSION3

The version of the Illustrator file to create when saving an EPS or Illustrator file



CompressionQuality AUTOMATICJPEG2000HIGHAUTOMATICJPEG2000LOSSLESSAUTOMATICJPEG2000LOWAUTOMATICJPEG2000MAXIMUMAUTOMATICJPEG2000MEDIUMAUTOMATICJPEG2000MINIMUMAUTOMATICJPEGHIGHAUTOMATICJPEGLOWAUTOMATICJPEGMAXIMUMAUTOMATICJPEGMEDIUMAUTOMATICJPEGMINIMUMJPEG2000HIGHJPEG2000LOSSLESSJPEG2000LOWJPEG2000MAXIMUMJPEG2000MEDIUMJPEG2000MINIMUMJPEGHIGHJPEGLOWJPEGMAXIMUMJPEGMEDIUMJPEGMINIMUMZIP4BITZIP8BITNone

The quality of bitmap compression used when saving a PDF file

CropOptions JapaneseStandard

The style of a document’s cropping box

DocumentColorSpace CMYKRGB

The color space of a document

DocumentType EPSILLUSTRATORPDF

The file format used to save a file

DownsampleMethod AVERAGEDOWNSAMPLEBICUBICDOWNSAMPLENODOWNSAMPLESUBSAMPLE

ElementPlacement INSIDEPLACEATBEGINNINGPLACEATENDPLACEBEFOREPLACEAFTER

EPSPostScriptLevelEnum LEVEL2LEVEL3

EPSPreview BWMACINTOSHBWTIFFCOLORMACINTOSHCOLORTIFFTRANSPARENTCOLORTIFFNone

The preview image format used when saving an EPS file



ExportType FLASHGIFJPEGPHOTOSHOPPNG24PNG8SVG

The file format used to export a file

FigureStyleType DEFAULTFIGURESTYLEPROPORTIONALPROPORTIONALOLDSTYLETABULARTABULAROLDSTYLE

FlashExportStyle ASFLASHFILELAYERSASFILESLAYERSASFRAMES

The method used to convert Illustrator images when exporting files

FlashImageFormat LOSSLESSLOSSY

The format used to store flash images

FlashJPEGMethod OptimizedStandard

The method used to store JPEG images

FontBaselineOption NORMALBASELINESUBSCRIPTSUPERSCRIPT

FontCapsOption ALLCAPSALLSMALLCAPSNORMALCAPSSMALLCAPS

FontOpenTypePositionOption DENOMINATORNUMERATOROPENTYPEDEFAULTOPENTYPESUBSCRIPTOPENTYPESUPERSCRIPT

FontSubstitutionPolicy SUBSTITUTEDEVICESUBSTITUTEOBLIQUESUBSTITUTETINT

GradientType LINEARRADIAL

The type of gradient

ImageColorSpace CMYKGrayscaleRGB

The color space of a raster item or an exported Photoshop 5 file

InkPrintStatus CONVERTINKDISABLEINKENABLEINK

InkType BLACKINKCUSTOMINKCYANINKMAGENTAINKYELLOWINK

JavaScriptExecutionMode BeforeRunningneverOnRuntimeError



Justification CENTERFULLJUSTIFYFULLJUSTIFYLASTLINECENTERFULLJUSTIFYLASTLINELEFTFULLJUSTIFYLASTLINERIGHTLEFTRIGHT

The alignment or justification for a paragraph of text

KinsokuOrderEnum PUSHINPUSHOUTFIRSTPUSHOUTONLY

KnockoutState DISABLEDENABLEDINHERITEDUnknown

The type of knockout to use on a page item

LanguageType BOKMALNORWEGIANBRAZILLIANPORTUGUESEBULGARIANCANADIANFRENCHCATALANCHINESECZECHDANISHDUTCHENGLISHFINNISHGREEKHUNGARIANICELANDICITALIANJAPANESENYNORSKNORWEGIANOLDGERMANPOLISHRUMANIANRUSSIANSERBIANSPANISHSTANDARDFRENCHSTANDARDGERMANSTANDARDPORTUGUESESWEDISHSWISSGERMANTURKISHUKENGLISHUKRANIAN

LayerOrderType TOPDOWNBOTTOMUP

MonochromeCompression CCIT3CCIT4MONOZIPNoneRUNLENGTH

The type of compression to use on a monochrome bitmap item when saving a PDF file



OutputFlattening PRESERVEAPPEARANCEPRESERVEPATHS

How transparency should be flattened when saving EPS and Illustrator file formats with compatibility set to versions of Illustrator earlier than Illustrator 10

PageMarksTypes JapaneseRoman

PathPointSelection ANCHORPOINTLEFTDIRECTIONLEFTRIGHTPOINTNOSELECTIONRIGHTDIRECTION

Which points, if any, of a path are selected

PDFBoxType PDFARTBOXPDFBLEEDBOXPDFBOUNDINGBOXPDFCROPBOXPDFMEDIABOXPDFTRIMBOX

PDFChangesAllowedEnum CHANGE128ANYCHANGESCHANGE128COMMENTINGCHANGE128EDITPAGECHANGE128FILLFORMCHANGE128NONECHANGE40ANYCHANGESCHANGE40COMMENTINGCHANGE40PAGELAYOUTCHANGE40NONE

PDFCompatibility ACROBAT4ACROBAT5ACROBAT6ACROBAT7

The version of the Acrobat file format to create when saving a PDF file

PDFOverprint DISCARDPDFOVERPRINTPRESERVEPDFOVERPRINT

PDFPrintAllowedEnum PRINT128HIGHRESOLUTIONPRINT128LOWRESOLUTIONPRINT128NONEPRINT40HIGHRESOLUTIONPRINT40NONE

PDFTrimMarkWeight TRIMMARKWEIGHT0125TRIMMARKWEIGHT025TRIMMARKWEIGHT05

PDFXStandard PDFX1A2001PDFX1A2003PDFX32001PDFX32003PDFXNONE

PhotoshopCompatibility PHOTOSHOP5PHOTOSHOP8

PointType CORNERSMOOTH

The type of path point selected



PolarityValues NEGATIVEPOSITIVE

PostScriptImageCompressionType IMAGECOMPRESSIONNONEJPEGRLE

PrintArtworkDesignation ALLLAYERSVISIBLELAYERSVISIBLEPRINTABLELAYERS

PrintColorIntent ABSOLUTECOLORIMETRICPERCEPTUALINTENTRELATIVECOLORIMETRICSATURATIONINTENT

PrintColorProfile CUSTOMPROFILEOLDSTYLEPROFILEPRINTERPROFILESOURCEPROFILE

PrintColorSeparationMode COMPOSITEINRIPSEPARATIONHOSTBASEDSEPARATION

PrinterColorMode BLACKANDWHITEPRINTERCOLORPRINTERGRAYSCALEPRINTER

PrinterPostScriptLevelEnum PSLEVEL1PSLEVEL2PSLEVEL3

PrinterTypeEnum NONPOSTSCRIPTPRINTERPOSTSCRIPTPRINTERUnknown

PrintFontDownloadMode DOWNLOADNONEDOWNLOADSUBSETDOWNLOADCOMPLETE

PrintingBounds ARTBOARDBOUNDSARTWORKBOUNDSCROPBOUNDS

PrintOrientation LANDSCAPEPORTRAITREVERSELANDSCAPEREVERSEPORTRAIT

PrintPosition TRANSLATEBOTTOMTRANSLATEBOTTOMLEFTTRANSLATEBOTTOMRIGHTTRANSLATECENTERTRANSLATELEFTTRANSLATERIGHTTRANSLATETOPTRANSLATETOPLEFTTRANSLATETOPRIGHT

PrintTiling TILEFULLPAGESTILEIMAGEABLEAREASTILESINGLEFULLPAGE



RasterLinkState DATAFROMFILEDATAMODIFIEDNODATA

The status of a raster item’s linked image if the image is stored externally

RulerUnits CentimetersInchesMillimetersPicasPointsQsUnknown

The default measurement units for the rulers of a document

SaveOptions DONOTSAVECHANGESPROMPTTOSAVECHANGESSAVECHANGES

Save options provided when closing a document

ScreenMode DESKTOPFULLSCREENMULTIWINDOW

The mode of display for a view

StrokeCap BUTTENDCAPPROJECTINGENDCAPROUNDENDCAP

The type of line capping for a path stroke

StrokeJoin BEVELENDJOINMITERENDJOINROUNDENDJOIN

The type of joints for a path stroke

StyleRunAlignmentType bottomcentericfBottomicfTopROMANBASELINEtop

SVGCSSPropertyLocation ENTITIESPRESENTATIONATTRIBUTESSTYLEATTRIBUTESSTYLEELEMENTS

How should the CSS properties of the document be included in an exported SVG file

SVGDocumentEncoding ASCIIUTF16UTF8

How should the text in the document be encoded when exporting an SVG file

SVGDTDVersion SVG1_0SVG1_1SVGBASIC1_1SVGTINY1_1SVGTINY1_1PLUS

SVB version compatibility for exported files

SVGFontSubsetting ALLGLYPHSCOMMONENGLISHCOMMONROMANGLYPHSUSEDGLYPHSUSEDPLUSENGLISHGLYPHSUSEDPLUSROMANNone

What font glyphs should be included in exported SVG files

SVGFontType CEFFONTOUTLINEFONTSVGFONT

Types for fonts included in exported SVG files



TabStopAlignment CenterDecimalLeftRight

The alignment of a tab stop

TextOrientation HORIZONTALVERTICAL

The orientation of text in a text art item

TextType AREATEXTPATHTEXTPOINTTEXT

The type of text art displayed by this object

TracingModeType TRACINGMODEBLACKANDWHITETRACINGMODECOLORTRACINGMODEGRAY

Transformation BOTTOMBOTTOMLEFTBOTTOMRIGHTCENTERDOCUMENTORIGINLEFTRIGHTTOPTOPLEFTTOPRIGHT

The point to use as the anchor point about which an object is rotated, resized, or transformed

TrappingType IGNOREOPAQUENORMALTRAPPINGOPAQUETRANSPARENT

UserInteractionLevel DISPLAYALERTSDONTDISPLAYALERTS

User interface settings

VariableKind GRAPHIMAGETEXTUALUnknownVISIBILITY

What type of variables are included in the document

ViewRasterType TRACINGVIEWRASTERADJUSTEDIMAGETRACINGVIEWRASTERNOIMAGETRACINGVIEWRASTERORIGINALIMAGETRACINGVIEWRASTERTRANSPARENTIMAGE

The raster visualization mode for tracing.

ViewVectorType TRACINGVIEWVECTORNOTRACINGRESULTTRACINGVIEWVECTOROUTLINESTRACINGVIEWVECTOROUTLINESWITHTRACINGTRACINGVIEWVECTORTRACINGRESULT

The vector visualization mode for tracing.

WariChuJustificationType CenterLeftRightWARICHUAUTOJUSTIFYWARICHUFULLJUSTIFYWARICHUFULLJUSTIFYLASTLINECENTERWARICHUFULLJUSTIFYLASTLINELEFTWARICHUFULLJUSTIFYLASTLINERIGHT



ZOrderMethod BRINGFORWARDBRINGTOFRONTSENDBACKWARDSENDTOBACK

The method used to arrange an art item’s position in the stacking order of its parent group or layer, as specified with the zOrder method


291

8 ExtendScript Tools and Features

ExtendScript is Adobe’s extended implementation of JavaScript, and is used by all Adobe Creative Suite 2 applications that provide a scripting interface. In addition to implementing the JavaScript language according to the W3C specification, ExtendScript provides certain additional features and utilities.

● For help in developing, debugging, and testing scripts, ExtendScript provides:

● The ExtendScript Toolkit, an interactive development and testing environment for ExtendScript.

● A global debugging object, the Dollar ($) Object.

● A reporting utility for ExtendScript elements, the ExtendScript Reflection Interface.

● In addition, ExtendScript provides these tools and features:

● A localization utility for providing user-interface string values in different languages. See Localizing ExtendScript Strings.

● Global functions for displaying short messages in dialog boxes. See User Notification Helper Functions.

● An object type for specifying measurement values together with their units. See Specifying Measurement Values.

● Tools for combining scripts, such as a #include directive, and import and export statements. See Modular Programming Support.

● Support for extending or overriding math and logical operator behavior on a class-by-class basis. See Operator Overloading.

● ExtendScript provides a common scripting environment for all Adobe Creative Suite 2 applications, and allows interapplication communication through scripts.

● To identify specific Adobe Creative Suite 2 applications, scripts must use Application and Namespace Specifiers.

● Applications can run scripts automatically on startup. See Script Locations and Checking Application Installation.

● For details about interapplication communication, see the Bridge JavaScript Reference, available with Adobe Creative Suite 2.

The ExtendScript ToolkitThe ExtendScript Toolkit provides an interactive development and testing environment for ExtendScript in all Adobe Creative Suite 2 applications. It includes a full-featured, syntax-highlighting editor with Unicode capabilities and multiple undo/redo support. The Toolkit allows you to:

● Single-step through JavaScripts inside a CS2 application.

● Inspect all data for a running script.

● Set and execute breakpoints.

The Toolkit is the default editor for ExtendScript files, which use the extension .jsx. You can use the Toolkit to edit or debug scripts in JS or JSX files.

Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 292

When you double-click a JSX file in the platform’s windowing environment, the script runs in the Toolkit, unless it specifies a particular target application using the #target directive. For more information, see Selecting a debugging target and Preprocessor directives.

Configuring the Toolkit window

The ExtendScript Toolkit initially appears with a default arrangement of panes, containing a default configuration of tabs. You can adjust the relative sizes of the panes by dragging the separators up or down, or right or left. You can regroup the tabs. To move a tab, drag the label into another pane.

If you drag a tab so that the entire destination pane is highlighted, it becomes another stacked tab in that pane. If you drag a tab to the top or bottom of a pane (so that only the top or bottom bar of the destination pane is highlighted), that pane splits to show the tabs in a tiled format.

Drag a tab to a new pane Destination pane is highlighted, and the new tab is added to the tab stack

Select target application Invoke tab flyout menus

Split pane shows Browser and Editor tabs


Each tab has a flyout menu, accessed through the arrow icon in the upper right corner. The same menu is available as a context menu, which you invoke with a right click in the tab. This menu always includes a Hide Pane command to hide that pane. Use the Window menu to show a hidden pane, or to bring it to the front.

The Editor, which has a tab for each script, has an additional context menu for debugging, which appears when you right-click in the line numbers area.

The Toolkit saves the current layout when you exit, and restores it at the next startup. It also saves and restores the open documents, the current positions within the documents, and any breakpoints that have been set.

● If you do not want to restore all settings on startup, hold SHIFT while the Toolkit loads to restore default settings. This reconnects to the last application and engine that was selected.

● If you want to restore the layout settings on startup, but not load the previously open documents, choose Start with a clean workspace in the Preferences dialog.

Selecting a debugging target

The Toolkit can debug multiple applications at one time. If you have more than one Adobe Creative Suite 2 application installed, use the drop-down list at the upper left under the menu bar to select the target application. All installed applications that use ExtendScript are shown in this list. If you select an application that is not running, the Toolkit prompts for permission to run it.

All available engines in the selected target application are shown in a drop-down list to the right of the application list, with an icon that shows the current debugging status of that engine. A target application can have more than one ExtendScript engine, and more than one engine can be active, although only one is current. An active engine is one that is currently executing code, is halted at a breakpoint, or, having executed all scripts, is waiting to receive events. An icon by each engine name indicates whether it is running, halted, or waiting for input:

The current engine is the one whose data and state is displayed in the Toolkit’s panes. If an application has only one engine, its engine becomes current when you select the application as the target. If there is more than one engine available in the target application, you can select an engine in the list to make it current.

When you open the Toolkit, it attempts to reconnect to the same target and engine that was set last time it closed. If that target application is not running, the Toolkit prompts for permission to launch it. If permission is refused, the Toolkit itself becomes the target application.

If the target application that you select is not running, the Toolkit prompts for permission and launches the application. Similarly, if you run a script that specifies a target application that is not running (using the #target directive), the Toolkit prompts for permission to launch it. If the application is running but not selected as the current target, the Toolkit prompts you to switch to it.

running

halted

waiting


If you select an application that cannot be debugged in the Toolkit (such as Adobe Help), an error dialog reports that the Toolkit cannot connect to the selected application.

The ExtendScript Toolkit is the default editor for JSX files. If you double-click a JSX file in a file browser, the Toolkit looks for a #target directive in the file and launches that application to run the script; however, it first checks for syntax errors in the script. If any are found, the Toolkit displays the error in a message box and quits silently, rather than launching the target application. For example:

Selecting scripts

The Scripts tab offers a list of debuggable scripts for the target application, which can be JS or JSX files or (for some applications) HTML files that contain embedded scripts.

Select a script in this tab to load it and display its contents in the editor pane, where you can modify it, save it, or run it within the target application.

Tracking data

The Data Browser tab is your window into the JavaScript engine. It displays all live data defined in the current context, as a list of variables with their current values. If execution has stopped at a breakpoint, it shows variables that have been defined using var in the current function, and the function arguments. To show variables defined in the global or calling scope, use the Call Stack to change the context (see The call stack).

You can use the Data Browser to examine and set variable values.

● Click a variable name to show its current value in the edit field at the top of the tab.

● To change the value, enter a new value and press ENTER. If a variable is read-only, the edit field is disabled.

The flyout menu for this tab lets you control the amount of data displayed:

Display or modify selected variable’s value

Object opened to show properties


● Show Global Functions toggles the display of all global function definitions.

● Show Object Methods toggles the display of all functions that are attached to objects. Most often, the interesting data in an object are its callable methods.

● Show JavaScript Language Elements toggles the display of all data that is part of the JavaScript language standard, such as the Array constructor or the Math object. An interesting property is the __proto__ property, which reveals the JavaScript object prototype chain.

Each variable has a small icon that indicates the data type. An invalid object is a reference to an object that has been deleted. If a variable is undefined, it does not have an icon.

You can inspect the contents of an object by clicking its icon. The list expands to show the object's properties (and methods, if Show Object Methods is enabled), and the triangle points down to indicate that the object is open.

Note: In Photoshop CS2 the Data Browser pane is populated only during the debugging of a JavaScript program within Photoshop.

The JavaScript console

The JavaScript console is a command shell and output window for the currently selected JavaScript engine. It connects you to the global namespace of that engine.

The command line entry field accepts any JavaScript code, and you can use it to evaluate expressions or call functions. Enter any JavaScript statement on the command line and execute it by pressing ENTER. The statement executes within the stack scope of the line highlighted in the Call Stack tab, and the result appears in the output field.

● The command line input field keeps a command history of 32 lines. Use the Up and Down Arrow keys to scroll through the previous entries.

null

Boolean

Number

String

Object

Invalid object

JavaScript command lineJavaScript output


● Commands entered in this field execute with a timeout of one second. If a command takes longer than one second to execute, the Toolkit generates a timeout error and terminates the attempt.

The output field is standard output for JavaScript execution. If any script generates a syntax error, the error is displayed here along with the file name and the line number. The Toolkit displays errors here during its own startup phase. The tab’s flyout menu allows you to clear the contents of the output field and change the size of the font used for output.

The call stack

The Call Stack tab is active while debugging a program. When an executing program stops because of a breakpoint or runtime error, the tab displays the sequence of function calls that led to the current execution point. The Call Stack tab shows the names of the active functions, along with the actual arguments passed in to that function.

For example, this stack pane shows a break occurring at a breakpoint in a function dayOfWeek:

The function containing the breakpoint is highlighted in both the Call Stack and the Editor tabs.

You can click any function in the call hierarchy to inspect it. In the Editor, the line containing the function call that led to that point of execution is marked with a green background. In the example, when you select the line [Top Level] in the call stack, the Editor highlights the line where the dayOfWeek function was called.

Switching between the functions in the call hierarchy allows you to trace how the current function was called. The Console and Data Browser tabs coordinate with the Call Stack pane. When you select a function in the Call Stack:

● The Console pane switches its scope to the execution context of that function, so you can inspect and modify its local variables. These would otherwise be inaccessible to the running JavaScript program from within a called function.

● The Data Browser pane displays all data defined in the selected context.


The Script Editor

You can open any number of Script Editor tabs; each displays one Unicode source code document. The editor supports JavaScript syntax highlighting, JavaScript syntax checking, multiple undo and redo operations, and advanced search and replace functionality.

You can use the mouse or special keyboard shortcuts to move the insertion point or to select text in the editor.

Mouse navigation and selection

Click the left mouse button in the editor to move the position caret.

To select text with the mouse, click in unselected text, then drag over the text to be selected. If you drag above or below the currently displayed text, the text scrolls, continuing to select while scrolling. You can also double-click to select a word, or triple-click to select a line.

To initiate a drag-and-drop of selected text, click in the block of selected text, then drag to the destination. You can drag text from one editor pane to another. You can also drag text out of the Toolkit into another application that accepts dragged text, and drag text from another application into a Toolkit editor.

You can drop files from the Explorer or the Finder onto the Toolkit to open them in an editor.

Keyboard navigation and selection

Besides the usual keyboard input, the editor accepts these special movement keys. You can also select text by using a movement key while pressing SHIFT.

Enter Insert a Line Feed character

Backspace Delete character to the left

Delete Delete character to the right

Left arrow Move insertion point left one character

Right arrow Move insertion point right one character

Up arrow Move insertion point up one line; stay in column if possible

Down arrow Move insertion point down one line; stay in column if possible

Page up Move insertion point one page up

Page down Move insertion point one page down

CTRL + Up arrow Scroll up one line without moving the insertion point

Ctrl + Down arrow Scroll down one line without moving the insertion point

CTRL + Page up Scroll one page up without moving the insertion point

CTRL + page down Scroll one page down without moving the insertion point

CTRL + Left arrow Move insertion point one word to the left

CTRL + right arrow Move insertion point one word to the right


The editor supports extended keyboard input via IME (Windows) or TMS (Mac OS). This is especially important for Far Eastern characters.

Syntax checking

Before running the new script or saving the text as a script file, you can check whether the text contains JavaScript syntax errors. Choose Check Syntax from the Edit menu or from the Editor’s right-click context menu.

● If the script is syntactically correct, the status line shows "No syntax errors".

● If the Toolkit finds a syntax error, such as a missing quote, it highlights the affected text, plays a sound, and shows the error message in the status line so you can fix the error.

Debugging in the Toolkit

You can debug the code in the currently active Editor tab. Select one of the debugging commands to either run or to single-step through the program.

When you run code from the Editor, it runs in the current target application’s selected JavaScript engine. The Toolkit itself runs an independent JavaScript engine, so you can quickly edit and run a script without connecting to a target application.

Evaluation in help tips

If you let your mouse pointer rest over a variable or function in an Editor tab, the result of evaluating that variable or function is displayed as a help tip. When you are not debugging the program, this is helpful only if the variables and functions are already known to the JavaScript engine. During debugging, however, this is an extremely useful way to display the current value of a variable, along with its current data type.

You can turn off the display of help tips using the Display JavaScript variables and Enable UI help tips checkboxes on the Help Options page of the Preferences dialog.

Controlling code execution

The debugging commands are available from the Debug menu, from the Editor’s right-click context menu, through keyboard shortcuts, and from the toolbar buttons. Use these menu commands and buttons to control the execution of code when the JavaScript Debugger is active.

Home Move insertion point to start of line

End Move insertion point to end of line

CTRL + Home Move insertion point to start of text

CTRL + End Move insertion point to end of text


Visual indication of execution states

While the engine is running, an icon in the upper right corner of the Toolkit window indicates that the script is active.

When the execution of a script halts because the script reached a breakpoint, or when the script reaches the next line when stepping line by line, the Editor displays the current script with the current line highlighted in yellow.

If the script encounters a runtime error, the Toolkit halts the execution of the script, displays the current script with the current line highlighted in red, displays the error message in the status line, and plays a sound.

Run Continue

F5 (Windows) Ctrl R (Mac OS)

Starts or resumes execution of a script.

Disabled when script is executing.

Break Ctrl F5 (Windows) Cmd . (Mac OS)

Halts the currently executing script temporarily and reactivates the JavaScript Debugger.

Enabled when a script is executing.

Stop Shift F5 (Windows) Ctrl K (Mac OS)

Stops execution of the script and generates a runtime error.

Enabled when a script is executing.

Step Over F10 (Windows) Ctrl S (Mac OS)

Halts after executing a single JavaScript line in the script. If the statement calls a JavaScript function, executes the function in its entirety before stopping (do not step into the function).

Step Into F11 (Windows) Ctrl T (Mac OS)

Halts after executing a single JavaScript line statement in the script or after executing a single statement in any JavaScript function that the script calls.

Step Out Shift F11 (Windows) Ctrl U (Mac OS)

When paused within the body of a JavaScript function, resumes script execution until the function returns.

When paused outside the body of a function, resumes script execution until the script terminates.


Scripts often use a try/catch clause to execute code that may cause a runtime error, in order to catch the error programmatically rather than have the script terminate. You can choose to allow regular processing of such errors using the catch clause, rather than breaking into the debugger. To set this behavior, choose Debug > Don't Break On Guarded Exceptions. Some runtime errors, such as Out Of Memory, always cause the termination of the script, regardless of this setting.

Setting breakpoints

When debugging a script, it is often helpful to make it stop at certain lines so that you can inspect the state of the environment, whether function calls are nested properly, or whether all variables contain the expected data.

● To stop execution of a script at a given line, click to the left of the line number to set a breakpoint. A filled dot indicates the breakpoint.

● Click a second time to temporarily disable the breakpoint; the icon changes to an outline.

● Click a third time to delete the breakpoint. The icon is removed.

Some breakpoints need to be conditional. For example, if you set a breakpoint in a loop that is executed several thousand times, you would not want to have the program stop each time through the loop, but only on each 1000th iteration.

You can attach a condition to a breakpoint, in the form of a JavaScript expression. Every time execution reaches the breakpoint, it runs the JavaScript expression. If the expression evaluates to a nonzero number or true, execution stops.

To set a conditional breakpoint in a loop, for example, the conditional expression could be "i >= 1000", which means that the program execution halts if the value of the iteration variable i is equal to or greater than 1000.

You can set breakpoints on lines that do not contain any code, such as comment lines. When the Toolkit runs the program, it automatically moves such a breakpoint down to the next line that actually contains code.

Breakpoint icons

Each breakpoint is indicated by an icon to the left of the line number. The icon for a conditional breakpoint is a diamond, while the icon for an unconditional breakpoint is round. Disabled breakpoints are indicated by an outline icon, while active ones are filled.

Unconditional breakpoint. Execution stops here.

Unconditional breakpoint, disabled. Execution does not stop.


The Breakpoints tab

The Breakpoints tab displays all breakpoints set in the current Editor tab. You can use the tab’s flyout menu to add, change, or remove a breakpoint.

You can edit a breakpoint by double-clicking it, or by selecting it and choosing Add or Change from the context menu. A dialog allows you to change the line number, the breakpoint’s enabled state, and the condition statement.

Whenever execution reaches this breakpoint, the debugger evaluates this condition. If it does not evaluate to true, the breakpoint is ignored and execution continues. This allows you to break only when certain conditions are met, such as a variable having a particular value.

Profiling

The Prof7iling tool helps you to optimize program execution. When you turn profiling on, the JavaScript engine collects information about a program while it is running. It counts how often the program executed a line or function, or how long it took to execute a line or function. You can choose exactly which profiling data to display.

Because profiling significantly slows execution time, the Profile menu offers these profiling options.:

Conditional breakpoint. Execution stops if the attached JavaScript expression evaluates to true.

Conditional breakpoint, disabled. Execution does not stop.

Off Profiling turned off. This is the default.

Functions The profiler counts each function call. At the end of execution, displays the total to the left of the line number where the function header is defined.

Lines The profiler counts each time each line is executed. At the end of execution, displays the total to the left of the line number.

Consumes more execution time, but delivers more detailed information.


When execution halts (at termination, at a breakpoint, or due to a runtime error), the Toolkit displays this information in the Editor, line by line. The profiling data is color coded:

● Green indicates the lowest number of hits, or the fastest execution time.

● Red indicates trouble spots, such as a line that has been executed many times, or which line took the most time to execute.

This example displays timing information for the program, where the fastest line took 4 microseconds to execute, and the slowest line took 29 microseconds. The timing might not be accurate down to the microsecond; it depends on the resolution and accuracy of the hardware timers built into your computer.

Add Timing Info Instead of counting the functions or lines, records the time taken to execute each function or line. At the end of execution, displays the total number of microseconds spent in the function or line, to the left of the line number.

This is the most time-consuming form of profiling.

No Profiler Data When selected, do not display profiler data.

Show Hit Count When selected, display hit counts.

Show Timing When selected, display timing data.

Erase Profiler Data Clear all profiling data.

Save Data As Save profiling data as comma-separated values in a CSV file that can be loaded into a spreadsheet program such as Excel.


Dollar ($) Object This global ExtendScript object provides a number of debugging facilities and informational methods. The properties of the $ object allow you to get global information such as the most recent run-time error, and set flags that control debugging and localization behavior. The methods allow you to output text to the JavaScript Console during script execution, control execution and other ExtendScript behavior programmatically, and gather statistics on object use.

Dollar ($) object properties

build Number The ExtendScript build number. Read only.

buildDate Date The date ExtendScript was built. Read only.

error Error String

The most recent run-time error information, contained in a JavaScript Error object.

Assigning error text to this property generates a run-time error; however, the preferred way to generate a run-time error is to throw an Error object.

flags Number Gets or sets low-level debug output flags. A logical AND of the following bit flag values:

0x0002 (2): Displays each line with its line number as it is executed.

0x0040 (64): Enables excessive garbage collection. Usually, garbage collection starts when the number of objects has increased by a certain amount since the last garbage collection. This flag causes ExtendScript to garbage collect after almost every statement. This impairs performance severely, but is useful when you suspect that an object gets released too soon.

0x0080 (128): Displays all calls with their arguments and the return value.

0x0100 (256): Enables extended error handling (see strict).0x0200 (512): Enables the localization feature of the toString

method. Equivalent to the localize property.

global Object Provides access to the global object, which contains the JavaScript global namespace.

level Number Enables or disables the JavaScript debugger. One of:

0: No debugging 1: Break on runtime errors 2: Full debug mode

locale String Gets or sets the current locale. The string contains five characters in the form LL_RR, where LL is an ISO 639 language specifier, and RR is an ISO 3166 region specifier.

Initially, this is the value that the application or the platform returns for the current user. You can set it to temporarily change the locale for testing. To return to the application or platform setting, set to undefined, null, or the empty string.


Dollar ($) object functions

localize Boolean Enable or disable the extended localization features of the built-in toString method. See Localizing ExtendScript Strings.

memCache Number Gets or sets the ExtendScript memory cache size in bytes.

objects Number The total count of all JavaScript objects defined so far. Read only.

os String The current operating system version. Read only.

screens Array An array of objects containing information about the display screens attached to your computer. Each object has the properties left, top, right, and bottom, which contain the four corners of each screen in global coordinates. A property primary is true if that object describes the primary display.

strict Boolean When true, any attempt to write to a read-only property causes a runtime error. Some objects do not permit the creation of new properties when true.

version String The version number of the ExtendScript engine as a three-part number and description; for example: "3.6.5 (debug)" Read only.

about

$.about ()

Displays the About box for the ExtendScript component, and returns the text of the About box as a string.

bp

$.bp ([condition])

Executes a breakpoint at the current position. Returns undefined.

If no condition is needed, it is recommended that you use the JavaScript debugger statement in the script, rather than this method.

condition Optional. A string containing a JavaScript statement to be used as a condition. If the statement evaluates to true or nonzero when this point is reached, execution stops.

clearbp

$.clearbp ([line])

Removes a breakpoint from the current script. Returns undefined.

line Optional. The line at which to clear the breakpoint. If 0 or not supplied, clears the breakpoint at the current line number.

gc

$.gc ()

Initiates garbage collection. Returns undefined.

getenv

$.getenv (envname)

Returns the value of the specified environment variable, or null if no such variable is defined.

envname The name of the environment variable.

list

$.list ([classname])

Collects object information into a table and returns this table as a string. See Object statistics below.

classname Optional. The type of object about which to collect information. If not supplied, collects information about all objects currently defined.


Object statistics

The output from $.list() is formatted as in the following example.

setbp

$.setbp ([line, condition])

Sets a breakpoint in the current script. Returns undefined.

If no arguments are needed, it is recommended that you use the JavaScript debugger statement in the script, rather than this method.

line Optional. The line at which to stop execution. If 0 or not supplied, sets the breakpoint at the current line number.

condition Optional. A string containing a JavaScript statement to be used for a conditional breakpoint. If the statement evaluates to true or nonzero when the line is reached, execution stops.

sleep

$.sleep (milliseconds)

Suspends the calling thread for the given number of milliseconds. Returns undefined.

During a sleep period, checks at 100 millisecond intervals to see whether the sleep should be terminated. This can happen if there is a break request, or if the script timeout has expired.

milliseconds The number of milliseconds to wait.

summary

$.summary ([classname])

Collects a summary of object counts into a table and returns this table as a string. The table shows the number of objects in each specified class. For example:

3 Array5 String

classname Optional. The type of object to count. If not supplied, counts all objects currently defined.

write

$.write (text[, text...]...)

Writes the specified text to the JavaScript Console. Returns undefined.


writeln

$.writeln (text[, text...]...)

Writes the specified text to the JavaScript Console and appends a linefeed sequence. Returns undefined.


Address L Refs Prop Class Name

0092196c 4 0 Function [toplevel]

00976c8c 2 1 Object Object

00991bc4 L 1 1 LOTest LOTest

0099142c L 2 2 Function LOTest

00991294 1 0 Object Object workspace


The columns show the following object information.

Address The physical address of the object in memory.

L This column contains the letter "L" if the object is a LiveObject (which is an internal data type).

Refs The reference count of the object.

Prop A second reference count for the number of properties that reference the object. The garbage collector uses this count to break circular references. If the reference count is not equal to the number of JavaScript properties that reference it, the object is considered to be used elsewhere and is not garbage collected.

Class The class name of the object.

Name The name of the object. This name does not reflect the name of the property the object has been stored into. The name is mostly relevant to Function objects, where it is the name of the function or method. Names in brackets are internal names of scripts. If the object has an ID, the last column displays that ID.


ExtendScript Reflection InterfaceExtendScript provides a reflection interface that allows you to find out everything about an object, including its name, a description, the expected data type for properties, the arguments and return value for methods, and any default values or limitations to the input values.

Reflection Object

Every object has a reflect property that returns a reflection object that reports the contents of the object. You can, for example, show the values of all the properties of an object with code like this:

var f= new File ("myfile");var props = f.reflect.properties;for (var i = 0; i < props.length; i++) { $.writeln('this property ' + props[i].name + ' is ' + f[props[i].name]);}

Reflection object properties

All properties are read only.

Reflection object functions

➤ Examples

This code determines the class name of an object:

obj = new String ("hi");obj.reflect.name; // => String

description String Short text describing the reflected object, or undefined if no description is available.

help String Longer text describing the reflected object more completely, or undefined if no description is available.

methods Array of ReflectionInfo

An Array of ReflectionInfo Objects containing all methods of the reflected object, defined in the class or in the specific instance.

name String The class name of the reflected object.

properties Array of ReflectionInfo

An Array of ReflectionInfo Objects containing all properties of the reflected object, defined in the class or in the specific instance. For objects with dynamic properties (defined at runtime) the list contains only those dynamic properties that have already been accessed by the script. For example, in an object wrapping an HTML tag, the names of the HTML attributes are determined at run time.

find

reflectionObj.find (name)

Returns the ReflectionInfo Object for the named property of the reflected object, or null if no such property exists. Use this method to get information about dynamic properties that have not yet been accessed, but that are known to exist.

name The property for which to retrieve information.


This code gets a list of all methods:

obj = new String ("hi");obj.reflect.methods; //=> indexOf,slice,...obj.reflect.find ("indexOf"); // => the method info

This code gets a list of properties:

Math.reflect.properties; //=> PI,LOG10,...

This code gets the data type of a property:

Math.reflect.find ("PI").type; // => number

ReflectionInfo Object

This object contains information about a property, a method, or a method argument.

● You can access ReflectionInfo objects in a Reflection Object’s properties and methods arrays, by name or index:

obj = new String ("hi");obj.reflect.methods[0];obj.reflect.methods["indexOf"];

● You can access the ReflectionInfo objects for the arguments of a method in the arguments array of the ReflectionInfo object for the method, by index:

obj.reflect.methods["indexOf"].arguments[0];

ReflectionInfo object properties

arguments Array of ReflectionInfo

For a reflected method, an array of ReflectionInfo Objects describing each method argument.

dataType String The data type of the reflected element. One of:

boolean number string Classname: The class name of an object.

Note: Class names start with a capital letter. Thus, the value string stands for a JavaScript string, while String is a JavaScript String wrapper object.

*: Any type. This is the default.null undefined: Return data type for a function that does not

return any value.unknown

defaultValue any The default value for a reflected property or method argument, or undefined if there is no default value, if the property is undefined, or if the element is a method.

description String Short text describing the reflected object, or undefined if no description is available.


help String Longer text describing the reflected object more completely, or undefined if no description is available.

isCollection Boolean When true, the reflected property or method returns a collection; otherwise, false.

max Number The maximum numeric value for the reflected element, or undefined if there is no maximum or if the element is a method.

min Number The minimum numeric value for the reflected element, or undefined if there is no minimum or if the element is a method.

name String Number

The name of the reflected element. A string, or a number for an array index.

type String The type of the reflected element. One of:

readonly: A read-only property.readwrite: A read-write property.createonly: A property that is valid only during creation of an

object.method: A method.


Localizing ExtendScript StringsLocalization is the process of translating and otherwise manipulating an interface so that it looks as if it had been originally designed for a particular language. ExtendScript gives you the ability to localize the strings in your script’s user interface. The language is chosen by the application at startup, according to the current locale provided by the operating system.

For portions of your user interface that are displayed on the screen, you may want to localize the displayed text. You can localize any string explicitly using the Global localize function, which takes as its argument a localization object containing the localized versions of a string.

A localization object is a JavaScript object literal whose property names are locale names, and whose property values are the localized text strings. The locale name is a standard language code with an optional region identifier. For details of the syntax, see Locale names.

In this example, a msg object contains localized text strings for two locales. This object supplies the text for an alert dialog.

msg = { en: "Hello, world", de: "Hallo Welt" }; alert (msg);

ExtendScript matches the current locale and platform to one of the object's properties and uses the associated string. On a German system, for example, the property de: "Hallo Welt" is converted to the string "Hallo Welt".

Variable values in localized strings

Some localization strings need to contain additional data whose position and order may change according to the language used.

You can include variables in the string values of the localization object, in the form %n. The variables are replaced in the returned string with the results of JavaScript expressions, supplied as additional arguments to the localize function. The variable %1 corresponds to the first additional argument, %2 to the second, and so on.

Because the replacement occurs after the localized string is chosen, the variable values are inserted in the correct position. For example:

today = {en: "Today is %1/%2.", de: "Heute ist der %2.%1."};

d = new Date();alert (localize (today, d.getMonth()+1, d.getDate()));

Enabling automatic localization

ExtendScript offers an automatic localization feature. When it is enabled, you can specify a localization object directly as the value of any property that takes a localizable string, without using the localize function. For example:

msg = { en: "Yes", de: "Ja", fr: "Oui" }; alert (msg);


To use automatic translation of localization objects, you must enable localization in your script with this statement:

$.localize = true;

The localize function always performs its translation, regardless of the setting of the $.localize variable. For example:

msg = { en: "Yes", de: "Ja", fr: "Oui" }; //Only works if the $.localize=truealert (msg); //Always works, regardless of $.localize valuealert ( localize (msg));

If you need to include variables in the localized strings, use the localize function.

Locale names

A locale name is an identifier string in that contains an ISO 639 language specifier, and optionally an ISO 3166 region specifier, separated from the language specifier by an underscore.

● The ISO 639 standard defines a set of two-letter language abbreviations, such as en for English and de for German.

● The ISO 3166 standard defines a region code, another two-letter identifier, which you can optionally append to the language identifier with an underscore. For example, en_US identifies U.S. English, while en_GB identifies British English.

This object defines one message for British English, another for all other flavors of English, and another for all flavors of German:

message = {en_GB: "Please select a colour." en: "Please select a colour." de: "Bitte wählen Sie eine Farbe."

};

If you need to specify different messages for different platforms, you can append another underline character and the name of the platform, one of Win, Mac, or Unix. For example, this objects defines one message in British English to be displayed in Mac OS, one for all other flavors of English in Mac OS, and one for all other flavors of English on all other platforms:

pressMsg = {en_GB_Mac: "Press Cmd-S to select a colour.",en_Mac: "Press Cmd-S to select a color.",en: "Press Ctrl-S to select a color."

};

All of these identifiers are case sensitive. For example, EN_US is not valid.

➤ How locale names are resolved

1. ExtendScript gets the hosting application’s locale; for example, en_US.

2. It appends the platform identifier; for example, en_US_Win.

3. It looks for a matching property, and if found, returns the value string.

4. If not found, it removes the platform identifier (for example, en_US) and retries.


5. If not found, it removes the region identifier (for example, en) and retries.

6. If not found, it tries the identifier en (that is, the default language is English).

7. If not found, it returns the entire localizer object.

Testing localization

ExtendScript stores the current locale in the variable $.locale. This variable is updated whenever the locale of the hosting application changes.

To test your localized strings, you can temporarily reset the locale. To restore the original behavior, set the variable to null, false, 0, or the empty string. An example:

$.locale = "ru"; // try your Russian messages$.locale = null; // restore to the locale of the app


Global localize function

The globally available localize function can be used to provide localized strings anywhere a displayed text value is specified.

localize

localize (localization_obj[, args])localize (ZString)

Returns the localized string for the current locale.

localization_obj A JavaScript object literal whose property names are locale names, and whose property values are the localized text strings. The locale name is an identifier as specified in the ISO 3166 standard, a set of two-letter language abbreviations, such as "en" for English and "de" for German.

For example:

btnText = { en: "Yes", de: "Ja", fr: "Oui" }; b1 = w.add ("button", undefined, localize (btnText));

The string value of each property can contain variables in the form %1, %2, and so on, corresponding to additional arguments. The variable is replaced with the result of evaluating the corresponding argument in the returned string.

args Optional. Additional JavaScript expressions matching variables in the string values supplied in the localization object. The first argument corresponds to the variable %1, the second to %2, and so on.

Each expression is evaluated and the result inserted in the variable’s position in the returned string.

➤ Example

today = {en: "Today is %1/%2",de: "Heute ist der %2.%1."};

d = new Date();alert (localize (today, d.getMonth()+1, d.getDate()));

ZString Internal use only. A ZString is an internal Adobe format for localized strings, which you might see in Adobe scripts. It is a string that begins with $$$ and contains a path to the localized string in an installed ZString dictionary. For example:

w = new Window ("dialog", localize ("$$$/UI/title1=Sample"));


User Notification Helper FunctionsExtendScript provides a set of globally available functions that allow you to display short messages to the user in platform-standard dialog boxes. There are three types of message dialogs:

● Alert: Displays a dialog containing a short message and an OK button.

● Confirm: Displays a dialog containing a short message and two buttons, Yes and No, allowing the user to accept or reject an action.

● Prompt: Displays a dialog containing a short message, a text entry field, and OK and Cancel buttons, allowing the user to supply a value to the script.

These dialogs are customizable to a small degree. The appearance is platform specific.

Global alert function

➤ Examples

This figure shows simple alert dialogs in Windows and Mac OS.

This figure shows alert dialogs with error icons.

alert

alert (message[, title, errorIcon]);

Displays a platform-standard dialog containing a short message and an OK button. Returns undefined.

message The string for the displayed message.

title Optional. A string to appear as the title of the dialog, if the platform supports a title. Mac OS does not support titles for alert dialogs. The default title string is "Script Alert".

errorIcon Optional. When true, the platform-standard alert icon is replaced by the platform-standard error icon in the dialog. Default is false.


Global confirm function

➤ Examples

This figure shows simple confirmation dialogs in Windows and Mac OS.

This figure shows confirmation dialogs with No as the default button.

Global prompt function

confirm

confirm (message[,noAsDflt ,title ]);

Displays a platform-standard dialog containing a short message and two buttons labeled Yes and No. Returns true if the user clicked Yes, false if the user clicked No.


noAsDflt Optional. When true, the No button is the default choice, selected when the user types ENTER. Default is false, meaning that Yes is the default choice.

title Optional. A string to appear as the title of the dialog, if the platform supports a title. Mac OS does not support titles for confirmation dialogs. The default title string is "Script Alert".

prompt

prompt (message, preset[, title ]);

Displays a platform-standard dialog containing a short message, a text edit field, and two buttons labeled OK and Cancel. Returns the value of the text edit field if the user clicked OK, null if the user clicked Cancel.


preset The initial value to be displayed in the text edit field.

title Optional. A string to appear as the title of the dialog. In Windows, this appears in the window’s frame, while in Mac OS it appears above the message. The default title string is "Script Prompt".


➤ Examples

This figure shows simple prompt dialogs in Windows and Mac OS.

This figure shows confirmation dialogs with a title value specified.


Specifying Measurement Values ExtendScript provides the UnitValue Object to represent measurement values. The properties and methods of the UnitValue object make it easy to change the value, the unit, or both, or to perform conversions from one unit to another.

UnitValue Object

Represents measurement values that contain both the numeric magnitude and the unit of measurement.

UnitValue object constructor

The UnitValue constructor creates a new UnitValue object. The keyword new is optional:

myVal = new UnitValue (value, unit);myVal = new UnitValue ("value unit");myVal = new UnitValue (value, "unit");

The value is a number, and the unit is specified with a string in abbreviated, singular, or plural form, as shown in the following table.

If an unknown unit type is supplied, the type is set to "?", and the UnitValue object prints as "UnitValue 0.00000".

For example, all of the following formats are equivalent:

myVal = new UnitValue (12, "cm");

Abbreviation Singular Plural Comments

in inch inches 2.54 cm

ft foot feet 30.48 cm

yd yard yards 91.44 cm

mi mile miles 1609.344 m

mm millimeter millimeters

cm centimeter centimeters

m meter meters

km kilometer kilometers

pt point points inches / 72

pc pica picas points * 12

tpt traditional point traditional points inches / 72.27

tpc traditional pica traditional picas 12 tpt

ci cicero ciceros 12.7872 pt

px pixel pixels baseless (see below)

% percent percent baseless (see below)


myVal = new UnitValue ("12 cm");myVal = UnitValue ("12 centimeters");

UnitValue object properties

UnitValue object functions

Converting pixel and percentage values

Converting measurements among different units requires a common base unit. For example, for length, the meter is the base unit. All length units can be converted into meters, which makes it possible to convert any length unit into any other length unit.

Pixels and percentages do not have a standard common base unit. Pixel measurements are relative to display resolution, and percentages are relative to an absolute total size.

● To convert pixels into length units, you must know the size of a single pixel. The size of a pixel depends on the display resolution. A common resolution measurement is 72 dpi, which means that there are 72 pixels to the inch. The conversion base for pixels at 72 dpi is 0.013889 inches (1/72 inch).

● Percentage values are relative to a total measurement. For example, 10% of 100 inches is 10 inches, while 10% of 1 meter is 0.1 meters. The conversion base of a percentage is the unit value corresponding to 100%.

The default baseUnit of a unitValue object is 0.013889 inches, the base for pixels at 72 dpi. If the unitValue is for pixels at any other dpi, or for a percentage value, you must set the baseUnit value accordingly. The baseUnit value is itself a unitValue object, containing both a magnitude and a unit.

baseUnit UnitValue A UnitValue Object that defines the size of one pixel, or a total size to use as a base for percentage values. This is used as the base conversion unit for pixels and percentages; see Converting pixel and percentage values.

Default is 0.013889 inches (1/72 in), which is the base conversion unit for pixels at 72 dpi. Set to null to restore the default.

type String The unit type in abbreviated form; for example, "cm" or "in".

value Number The numeric measurement value.

as

unitValueObj.as (unit)

Returns the numeric value of this object in the given unit.

If the unit is unknown or cannot be computed, generates a run-time error.

unit The unit type in abbreviated form; for example, "cm" or "in".

convert

unitValueObj.convert (unit)

Converts this object to the given unit, resetting the type and value accordingly. Returns true if the conversion is successful. If the unit is unknown or the object cannot be converted, generates a run-time error and returns false.

unit The unit type in abbreviated form; for example, "cm" or "in".


For a system using a different dpi, you can change the baseUnit value in the UnitValue class, thus changing the default for all new unitValue objects. For example, to double the resolution of pixels:

UnitValue.baseUnit = UnitValue (1/144, "in"); //144 dpi

To restore the default, assign null to the class property:

UnitValue.baseUnit = null; //restore default

You can override the default value for any particular unitValue object by setting the property in that object. For example, to create a unitValue object for pixels with 96 dpi:

pixels = UnitValue (10, "px");myPixBase = UnitValue (1/96, "in");pixels.baseUnit = myPixBase;

For percentage measurements, set the baseUnit property to the measurement value for 100%. For example, to create a unitValue object for 40 % of 10 feet:

myPctVal = UnitValue (40, "%");myBase = UnitValue (10, "ft")myPctVal.baseUnit = myBase;

Use the as method to get to a percentage value as a unit value:

myFootVal = myPctVal.as ("ft"); // => 4myInchVal = myPctVal.as ("in"); // => 36

You can convert a unitValue from an absolute measurement to pixels or percents in the same way:

myMeterVal = UnitValue (10, "m"); // 10 metersmyBase = UnitValue (1, "km"); myMeterVal.baseUnit = myBase; //as a percentage of 1 kilometerpctOfKm = myMeterVal.as ('%'); // => 1

myVal = UnitValue ("1 in"); // Define measurement in inches// convert to pixels using default basemyVal.convert ("px"); // => value=72 type=px

Computing with unit values

UnitValue objects can be used in computational JavaScript expressions. The way the value is used depends on the type of operator.

● Unary operators (~, !, +, -)

~unitValue The numeric value is converted to a 32-bit integer with inverted bits.

!unitValue Result is true if the numeric value is nonzero, false if it is not.

+unitValue Result is the numeric value.

-unitValue Result is the negated numeric value.


● Binary operators (+, -, *, /, %)

If one operand is unitValue object and the other is a number, the operation is applied to the number and the numeric value of the object. The expression returns a new unitValue object with the result as its value. For example:

val = new UnitValue ("10 cm");res = val * 20;// res is a UnitValue (200, "cm");

If both operands are unitValue objects, JavaScript converts the right operand to the same unit as the left operand and applies the operation to the resulting values. The expression returns a new unitValue object with the unit of the left operand, and the result value. For example:

a = new UnitValue ("1 m");b = new UnitValue ("10 cm");a + b; // res is a UnitValue (1.1, "m");b + a; // res is a UnitValue (110, "cm");

● Comparisons (=, ==, <, >, <=, >=)

If one operand is a unitValue object and the other is a number, JavaScript compares the number with the unitValue’s numeric value.

If both operands are unitValue objects, JavaScript converts both objects to the same unit, and compares the converted numeric values.

For example:

a = new UnitValue ("98 cm");b = new UnitValue ("1 m");a < b; // => truea < 1; // => falsea == 98; // => true


Modular Programming SupportExtendScript provides support for a modular approach to scripting by allowing you to include one script in another as a resource, and allowing a script to export definitions that can be imported and used in another script.

Preprocessor directives

ExtendScript provides preprocessor directives for including external scripts, naming scripts, specifying an ExtendScript engine, and setting certain flags. You can specify these in two ways:

● With a C-style statement starting with the # character:

#include "file.jsxinc"

● In a comment whose text starts with the @ character:

// @include "file.jsxinc"

When a directive takes one or more arguments, and an argument contains any nonalphanumeric characters, the argument must be enclosed in single or double quotes. This is generally the case with paths and file names, for example, which contain dots and slashes.

#engine name Identifies the ExtendScript engine that runs this script. This allows other engines to refer to the scripts in this engine by importing the exported functions and variables. See Importing and exporting between scripts.

Use JavaScript identifier syntax for the name. Enclosing quotes are optional. For example:

#engine library#engine "$lib"

#include file Includes a JavaScript source file from another location. Inserts the contents of the named file into this file at the location of this statement. The file argument is an Adobe portable file specification. See Specifying Paths.

As a convention, use the file extension .jsxinc for JavaScript include files. For example:

#include "../include/lib.jsxinc"

To set one or more paths for the #include statement to scan, use the #includepath preprocessor directive.

If the file to be included cannot be found, ExtendScript throws a run-time error.

Included source code is not shown in the debugger, so you cannot set breakpoints in it.


Importing and exporting between scripts

The ExtendScript JavaScript language has been extended to support function calls and variable access across various source code modules and ExtendScript engines. A script can use the export statement to make its definitions available to other scripts, which use the import statement to access those definitions.

To use this feature, the exporting script must name its ExtendScript engine using the #engine preprocessor statement. The name must follow JavaScript naming syntax; it cannot be an expression.

#includepath path One or more paths that the #include statement should use to locate the files to be included. The semicolon (;) separates path names.

If a #include file name starts with a slash (/), it is an absolute path name, and the include paths are ignored. Otherwise, ExtendScript attempts to find the file by prefixing the file with each path set by the #includepath statement.

For example:

#includepath "include;../include"#include "file.jsxinc"

Multiple #includepath statements are allowed; the list of paths changes each time an #includepath statement is executed.

As a fallback, ExtendScript also uses the contents of the environment variable JSINCLUDE as a list of include paths.

Some engines can have a predefined set of include paths. If so, the path provided by #includepath is tried before the predefined paths. If, for example, the engine has a predefined path set to predef;predef/include, the preceding example causes the following lookup sequence:

file.jsxinc: literal lookupinclude/file.jsxinc: first #includepath path../include/file.jsxinc: second #includepath pathpredef/file.jsxinc: first predefined engine pathpredef/include/file.jsxinc: second predefined engine path

#script name Names a script. Enclosing quotes are optional, but required for names that include spaces or special characters. For example:

#script SetupPalette#script "Load image file"

The name value is displayed in the Toolkit Editor tab. An unnamed script is assigned a unique name generated from a number.

#strict on Turns on strict error checking. See the Dollar ($) Object’s strict property.

#target name Defines the target application of this JSX file. The name value is an application specifier; see Application and Namespace Specifiers. Enclosing quotes are optional.

If the Toolkit is registered as the handler for files with the .jsx extension (as it is by default), opening the file opens the target application to run the script. If this directive is not present, the Toolkit loads and displays the script. A user can open a file by double-clicking it in a file browser, and a script can open a file using a File object’s execute method.


For example, the following script could serve as a library or resource file. It defines and exports a constant and a function:

#engine libraryexport random, libVersion;const libVersion = "Library 1.0";function random (max) {

return Math.floor (Math.random() * max);}

A script running in a different engine can import the exported elements. The import statement identifies the resource script that exported the variables using the engine name:

import library.random, library.libVersion;print (random (100));

You can use the asterisk wildcard (*) to import all symbols exported by a library:

import library.*

Objects cannot be transferred between engines. You cannot retrieve or store objects, and you cannot call functions with objects as arguments. However, you can use the JavaScript toSource function to serialize objects into strings before passing them. You can then use the JavaScript eval function to reconstruct the object from the string.

For example, this function takes as its argument a serialized string and constructs an object from it:

function myFn (serialized) {var obj = eval (serialized);// continue working…

}

In calling the function, you deconstruct the object you want to pass into a serialized string:

myFn (myObject.toSource()); // pass a serialized object


Operator Overloading ExtendScript allows you to extend or override the behavior of a math or a Boolean operator for a specific class by defining a method in that class with same name as the operator. For example, this code defines the addition (+) operator for the class MyClass. In this case, the addition operator simply adds the operand to the property value:

// define the constructor methodfunction MyClass (initialValue) {

this.value = initialValue;}// define the addition operatorMyClass.prototype ["+"] = function (operand) {

return this.value + operand;}

This allows you to perform the "+" operation with any object of this class:

var obj = new MyClass (5);Result: [object Object]obj + 10;Result: 15

You can override the following operators:

● The operators > and >= are implemented by executing NOT operator <= and NOT operator <.

● Combined assignment operators such as *= are not supported.

All operator overload implementations must return the result of the operation. To perform the default operation, return undefined.

Unary operator functions work on the this object, while binary operators work on the this object and the first argument. The + and - operators have both unary and binary implementations. If the first argument is undefined, the operator is unary; if it is supplied, the operator is binary.

For binary operators, a second argument indicates the order of operands. For noncommutative operators, either implement both order variants in your function or return undefined for combinations that you do not support. For example:

this ["/"] = function (operand, rev) {if (rev) {

// do not resolve operand / thisreturn;

} else {// resolve this / operandreturn this.value / operand;

}}

Unary +, -~

Binary +, -*, /, %, ^<, <=, ==<<, >>, >>>&, |, ===


Application and Namespace SpecifiersAll forms of interapplication communication use Application specifiers to identify Adobe applications.

● In all ExtendScript scripts, the #target directive can use an specifier to identify the application that should run that script. See Preprocessor directives.

● In interapplication messages, the specifier is used as the value of the target property of the message object, to identify the target application for the message.

● Bridge (which is integrated with all Adobe Creative Suite 2 applications) uses an application specifier as the value of the document.owner property, to identify another Creative Suite 2 application that created or opened a Bridge browser window. For details, see the Bridge JavaScript Reference, available with Adobe Creative Suite 2.

When a script for one application invokes Cross-DOM or exported functions, it identifies the exporting application using Namespace specifiers.

Application specifiers

Application specifiers are strings that encode the application name, a version number and a language code. They take the following form:

appname[-version[-locale]]

The following are examples of legal specifiers:

photoshopbridge-1bridge-1.0illustrator-12.2bridge-1-en_usgolive-8-de_de

appname An Adobe application name. One of:

acrobataftereffectsatmosphereauditionbridgeencoregoliveillustratorincopyindesignphotoshoppremiere

version Optional. A number indicating at least a major version. If not supplied, the most recent version is assumed. The number can include a minor version separated from the major version number by a dot; for example, 1.5.

locale Optional. An Adobe locale code, consisting of a 2-letter ISO-639 language code and an optional 2-letter ISO 3166 country code separated by an underscore. Case is significant. For example, en_US, en_UK, ja_JP, de_DE, fr_FR.

If not supplied, ExtendScript uses the current platform locale.

Do not specify a locale for a multilingual application, such as Bridge, that has all locale versions included in a single installation.


Namespace specifiers

When calling cross-DOM and exported functions from other applications, a namespace specifier qualifies the function call, directing it to the appropriate application.

Namespace specifiers consist of an application name, as used in an application specifier, with an optional major version number. Use it as a prefix to an exported function name, with the JavaScript dot notation.

appname[majorVersion].functionName(args)

For example:

● To call the cross-DOM function quit in Photoshop CS2, use photoshop.quit(), and to call it in GoLive® CS2, use golive.quit().

● To call the exported function place, defined for Illustrator CS version 12, call illustrator12.place(myFiles).

For information about the cross-DOM and exported functions, see the Bridge JavaScript Reference, available with Adobe Creative Suite 2.

Script Locations and Checking Application InstallationOn startup, all Adobe Creative Suite 2 applications execute all JSX files that they find in the user startup folder:

● In Windows, the startup folder is:

%APPDATA%\Adobe\StartupScripts

● In Mac OS®, the startup folder is

~/Library/Application Support/Adobe/StartupScripts/

A script in the startup directory is executed on startup by all applications. If you place a script here, it must contain code to check whether it is being run by the intended application. You can do this using the appName static property of the BridgeTalk class. For example:

if( BridgeTalk.appName == "bridge" ) {//continue executing script

}

In addition, individual applications may look for application-specific scripts in a subfolder named with that application’s specifier and version, in the form:

%APPDATA%\Adobe\StartupScripts\appname\version~/Library/Application Support/Adobe/StartupScripts/appname/version/

The name and version in these folder names are specified in the form required for Application specifiers. For example, in Windows, GoLive CS2 version 8.2 would look for scripts in the directory:

%APPDATA%\Adobe\StartupScripts\golive\8.2

The version portion of the Bridge-specific folder path is an exact version number. That is, scripts in the folder bridge/1.5 are executed only by Bridge version 1.5, and so on.

Individual applications may also implement a path in the installation directory for application-specific startup scripts. For example:

IllustratorCS2_install_dir\Startup Scripts


IllustratorCS2_install_dir/Startup Scripts/

If a script that is run by one application will communicate with another application, or add functionality that depends on another application, it must first check whether that application and version is installed. You can do this using the BridgeTalk.getSpecifier static function. For example:

if( BridgeTalk.appName == "bridge" ) {// Check that PS CS2 is installed

if( BridgeTalk.getSpecifier("photoshop",9)){ // add PS automate menu to Bridge UI

}}

For details of interapplication communication, see the Bridge JavaScript Reference, available with Adobe Creative Suite 2.

Index

Aabsolute pathnames 69actions, about 48Adobe Illustrator

Plug-in Software Development Kit Function Reference 62saving to versions 136type library 74

aki properties 66alerts 314aliases, referencing 72anchor points 62, 174application

properties 75specifiers 325

applicationsas script execution targets 322calling exported functions 326communication between 325debugging 293

applying stylesabout 65brush 79graphic 124paragraph 165

arithmetic operators 56art items

bitmaps 214grouped 131mesh 151plugins 192providing access 157raster 214rotating 246symbols 231, 234tags 239

assigning values 55attributes

about 65applying to words 262

Bbackslashes in pathnames 70Boolean value 55brackets, about 74breakpoints 300brushes

about 79counting 80

Ccall stack for execution 296centimeters, conversion 66

character encoding 72character styles

See also fontsabout 65associating attributes 86using 87

characterscounting 85specifying properties 81, 83

classesalphabetical reference 74objects 53spot colors 223

closing documents 103CMYK colors

spot 222swatches 63translating 89, 218

collections, object 53colors

applying to words 262CMYK. See CMYK colorsdocument properties 104gradients. See gradientsgray, using 130none 155patterns 178print management 200removing fill 155RGB. See RGB colorsscreen spot functions 221separation management 201separation screen information 219setting in path items 171specifying 89spot. See spot colorsstop definitions 122swatches. See swatchesusing 63

command linefor JavaScript 295

comments, about 54comparison operators 56compound paths

counting 94creating and modifying 93shared values 90

concatenation operators 56conditional statements 57confirmation dialogs 314console 295constants, scripting 281containers, about 53continuation character 54

328

Adobe Illustrator CS2JavaScript Scripting Reference Index 329

control bounds 68control structures 57coordinates

about 67print 202

counting paragraphs 164cross-DOM

specifying application 326CS2 version changes 50

Ddata, tracking while debugging 294datasets

about 95properties 97using 95

debugging 58call stack 296in ExtendScript Toolkit 298optimization tools 301selecting target application 293setting breakpoints 300

debugging toolsDollar ($) object 303ExtendScript Toolkit 291Reflection object 307

declaring variables 55deleting

layers 144swatches 230

dimensions, page items 67directories, referencing 273directory specifications 69documents

bringing layers to front 142closing 103color model 63color spaces 104copying mesh items between 154counting words 262creating 104default settings 98, 103deselecting objects 103duplicating 77EPS options 105Flash export options 107GIF options 109JPEG options 111opening Photoshop 186page item positioning 67PDF options 180Photoshop options 112placed items 187PNG options 113, 115printing 65save options 136saving to a specific version 136selecting paths 92SVG options 116

SWF options 107Dollar ($) object 303drives, specifying in paths 71duplicating documents 77

Eelements, object 53em space units 67encoding 72engine ExtendScript directive 321engines, JavaScript 293enumeration reference 281EPS files, exporting 105error handling

about 59filesystem 73, 278setting strict 322

executing JavaScriptabout 326in ExtendScript Toolkit 291, 298

executing scripts 49, 50execution call stack 296exported functions

specifying application 326exporting and importing scripts 322exporting files

EPS 105Flash (.SWF) 107GIF 109JPEG 111Photoshop 112PNG8 113PNG24 115SVG 116

ExtendScriptcommand line 295Dollar ($) object 303engines 321multiple engines 293operator overloading 324preprocessor directives 321Reflection object 307

ExtendScript Toolkitabout 58, 291configuring window 292debugging 298editing scripts 297optimization tools 301setting breakpoints 300

FFile object 264files

See also individual file typesdistinguishing from folders 69extensions for valid scripts 49external references 157including in scripts 58name and path specifications 69


opening options 156preferences 199

files and folders, platform-independent reference objects 69filesystem

aliases 72error handling 73, 278object references 69, 264

fill colors, removing 155fixed points 67fixed rectangles 68Flash files, exporting 107flattening options 205Folder object 273fonts

See also character stylesem space units 67finding 242information 241printing options 206setting 241

frames, text. See text framesfull screen, setting views 260functions

call stack for debugging 296functions, about 57

Ggeometric bounds 68GIF files, exporting 109global dialogs 314global localize function 313global object 303gradients

adding stops 123changing color 120color specifications 120creating 63creating and applying 118mesh items 151properties 118removing 121stop definitions 122

graph itemsproperties 126rotating 129

graphic stylesapplying 124counting 125

gray color, using 130group items

about 131creating from plugin items created by tracing 189, 192, 216,

254, 256importing PDFs 135modifying 133

Hhandles, path points 174height, maximum value allowed 67

II/O, unicode 72if statements 57Illustrator, See Adobe Illustratorimporting and exporting scripts 322importing PDFs 135inches, conversion of measurements 66include ExtendScript directive 321include functionality 58includepath ExtendScript directive 322inheritance, objects 53inks, properties 137insertion points, about 139installing scripts 49interapplication communication

about 325checking application installation 327specifying target applications 326

internationalization, ExtendScript utilities 310

JJavaScript

changes in Illustrator CS2 50console 295constants list 281continuation character 54debugging 58, 291editing scripts 297engines 321multiple engines 293resources 59supported features 49type library 74

job options, printing 207JPEG files, exporting 111justifying paragraphs 162

Llayers

about 141bringing to front 142deleting 144

left direction 62legacy text

properties 145, 148updating 156

linescreating 65properties 149

listinginks 137printers 204

local attributes 65locale identifiers 311localization, ExtendScript utilities 310localize function 313locations of startup scripts 326locking mesh items 153


Mmatrices, about 150measurement values 66, 317mesh items

copying between documents 154locking 153properties 151

messaging other applications 325methods

alphabetical reference 74using 63

millimeters, conversion 66

Nnamespaces

global 303specifiers for interapplication communication 326

naming scripts 322naming variables 56nested layers 141notifications 314numberic values 55

Oobject model

basic concepts 52changes in Illustrator CS2 50diagram 60text 64

object referencesabout 53, 61external files 157

objectsabout 52alphabetical reference 74classes 53collections 53container object 75creating in JavaScript 61deselecting 103dimensions 67elements 53file and folder reference 69, 264, 273global object 303hierarchy 60inheritance 53model. See object modelproperties 52, 53references. See object referencesresponse to commands 52retrieving information about 307value type 55

opening filesoptions 156PDFs 180Photoshop 186

operator overloading in ExtendScript 324operators, about 56optimization tools 301

Ppage items

accessing 157bounds 68positioning 67positioning and dimensions 67

page marks, printing 211paper

about 159information 212

paragraphsassociating styles 165attributes 161counting 164creating and applying styles 166justifying 162tab stops 238

parameters, omitting 63path items

complex 172properties 168rectangular 173

path specifications 69pathnames

separator characters 70special characters 70

pathsabout 62compound 90creating compound 93creating from straight lines 171items. See path itemsnames. See path namespoints 174, 175selecting 92setting colors 171

patternscolor specifications 178creating 63defining 176removing 177

PDF filesimporting as group items 135opening 180save options 181setting preferences 199

Photoshop filesexporting 112opening 186setting preferences 199

picas, conversion 66placed items

about 187changing selection state 189collections 191

platform-independent paths 69plugin items

copying 194creating by tracing 189, 192, 216, 254, 256properties 192, 195


PNG files, exportingPNG8 113PNG24 115

pointsconversion 66fixed 67paths 174, 175zero 67

portability of file references 72PostScript print options 213PPD files, about 196printing

about 64associating printers with information 203color management 200color separation screens 219color separations 201coordinates 202flattening 205font options 206job information 207listing printers 204media parameters 202page marks 211paper information 212PostScript options 213printer configuration information 203settings options 65, 209

profiling for script optimization 301prompts 314

QQs (unit), conversion 66

Rraster art

converting to vector art by tracing 189, 192, 216, 254, 256raster items

creating 214finding 217

records, matrix 150rectangles

creating 173fixed 68

Reflection object 307relative pathnames 69RGB colors

about 218spot 222swatches 63translating 89

right direction 62rotating

graph items 129text items 246

Ssaving files

options 136PDF 181

screensgetting information 219spot function 221

script execution, setting target application 322script ExtendScript directive 322scripting

about 47, 52automating 52basic concepts 54comments 54compared to actions 48constant types 281using 48value types 54

scriptsbreaking long lines 54checking application installation 327command line 295debugging 291editing in ExtendScript Toolkit 297executing 49, 50, 326file extensions 49file-inclusion directives 58importing and exporting definitions 322including in other scripts 321installing 49menu 49naming 322output 295startup 50, 326support in Illustrator 49

SDK 62selections

changing state 189duplicating 77using 62

separation screensgetting information 219spot function 221

slashes in pathnames 70soft return character 54Software Development Kit 62spaces, adding 139special characters in pathnames 70spot colors

about 221classes 223creating 63, 222creating and applying 224removing 224

spot functions 221startup script locations 326startup scripts 50stop definitions

adding 123properties 122

storiesabout 64, 226


legacy text 145linking text frames 226properties 228

strict ExtendScript directive 322string translation, ExtendScript utilities 310string values 55styles

character. See character stylesgraphic. See graphic stylesparagraph 165

subclasses, about 53sublayers 141superclasses, about 53SVG files, exporting 116swatches

about 229deleting 230inserting spot colors 222modifying 229using 63

SWF files, exporting 107symbols

about 63, 231creating 232creating items 237items 63, 234

Ttab stops, using 238tags

setting values 240using 239

target ExtendScript directive 322targets

message 325script execution 322selecting application for debugging 293

terminology, object model 52testing

in ExtendScript Toolkit 298scripts 291

testing. See debuggingtext

art items 64font information 241frames. See text framesinsertion points 139legacy 145, 148, 156lines 149linking to stories 226manipulating 252paragraph attributes 161ranges. See text rangesvalues 55

text framescharacter attributes 81creating and modifying 247legacy text 145properties 243

rotating 246types 64

text rangesabout 251content 65properties 253stories 226using text art 64

Toolkit, ExtendScript 291tracing 189, 192, 216, 254, 256

saving and loading preset options 257transformation matrices, about 150translation of UI strings 310troubleshooting. See debuggingtype library, alphabetical listing 74

Uunicode I/O 72units of measurement 66, 317UnitValue object 317URI notation 69user prompts 314

Vvalues

assigning 55enumeration constants 281list of types 54tags 240

variable values during execution 294variables

about 55collecting in datasets 95declaring 55naming 56properties 258, 259using 95

vector artcreating from raster art by tracing 189, 192, 216, 254, 256

views, using 260, 261visible bounds 68volumes, specifying in paths 71

Wwatch windows 58web site, Adobe Solutions Network 63width, maximum value allowed 67words

about 262changing to gray color 130counting 262

XX axis 67

YY axis 67


Zzero point 67

Download - Illustrator CS2 JavaScript Scripting Reference · · 2018-04-28AdobeÆ Illustrator ® CS2 JavaScript ... Application properties ... activeDocument

Top Related