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
Adobe Illustrator CS2JavaScript Scripting Reference 5
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
Adobe Illustrator CS2JavaScript Scripting Reference 6
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
Adobe Illustrator CS2JavaScript Scripting Reference 7
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
Adobe Illustrator CS2JavaScript Scripting Reference 8
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
Adobe Illustrator CS2JavaScript Scripting Reference 9
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
Adobe Illustrator CS2JavaScript Scripting Reference 10
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
Adobe Illustrator CS2JavaScript Scripting Reference 11
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
Adobe Illustrator CS2JavaScript Scripting Reference 12
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
Adobe Illustrator CS2JavaScript Scripting Reference 13
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
Adobe Illustrator CS2JavaScript Scripting Reference 14
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
Adobe Illustrator CS2JavaScript Scripting Reference 15
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
Adobe Illustrator CS2JavaScript Scripting Reference 16
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
Adobe Illustrator CS2JavaScript Scripting Reference 17
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
Adobe Illustrator CS2JavaScript Scripting Reference 18
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
Adobe Illustrator CS2JavaScript Scripting Reference 19
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
Adobe Illustrator CS2JavaScript Scripting Reference 20
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
Adobe Illustrator CS2JavaScript Scripting Reference 21
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
Adobe Illustrator CS2JavaScript Scripting Reference 22
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
Adobe Illustrator CS2JavaScript Scripting Reference 23
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
Adobe Illustrator CS2JavaScript Scripting Reference 24
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
Adobe Illustrator CS2JavaScript Scripting Reference 25
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
Adobe Illustrator CS2JavaScript Scripting Reference 26
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
Adobe Illustrator CS2JavaScript Scripting Reference 27
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
Adobe Illustrator CS2JavaScript Scripting Reference 28
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
Adobe Illustrator CS2JavaScript Scripting Reference 29
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
Adobe Illustrator CS2JavaScript Scripting Reference 30
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
Adobe Illustrator CS2JavaScript Scripting Reference 31
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
Adobe Illustrator CS2JavaScript Scripting Reference 32
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
Adobe Illustrator CS2JavaScript Scripting Reference 33
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
Adobe Illustrator CS2JavaScript Scripting Reference 34
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
Adobe Illustrator CS2JavaScript Scripting Reference 35
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
Adobe Illustrator CS2JavaScript Scripting Reference 36
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
Adobe Illustrator CS2JavaScript Scripting Reference 37
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
Adobe Illustrator CS2JavaScript Scripting Reference 38
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
Adobe Illustrator CS2JavaScript Scripting Reference 39
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
Adobe Illustrator CS2JavaScript Scripting Reference 40
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
Adobe Illustrator CS2JavaScript Scripting Reference 41
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
Adobe Illustrator CS2JavaScript Scripting Reference 42
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
Adobe Illustrator CS2JavaScript Scripting Reference 43
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
Adobe Illustrator CS2JavaScript Scripting Reference 44
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
Adobe Illustrator CS2JavaScript Scripting Reference 45
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
Adobe Illustrator CS2JavaScript Scripting Reference 46
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
IntroductionThis 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.
Adobe Illustrator CS2JavaScript Scripting Reference Introduction 49
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
Adobe Illustrator CS2JavaScript Scripting Reference Introduction 50
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.
Adobe Illustrator CS2JavaScript Scripting Reference Introduction 51
● 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 BasicsWhen 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.
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 54
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:
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 55
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"}
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 56
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.”
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 57
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;
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 58
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.
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Basics 59
● 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 IllustratorThis 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
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 62
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.
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 63
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
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 64
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
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 65
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.
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 66
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
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 67
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
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 68
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.
Adobe Illustrator CS2JavaScript Scripting Reference Using File and Folder Objects 71
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
Adobe Illustrator CS2JavaScript Scripting Reference Using File and Folder Objects 72
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
Adobe Illustrator CS2JavaScript Scripting Reference Using File and Folder Objects 73
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 ReferenceThis 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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 76
Application methods
version string Read-only. The version of the Adobe Illustrator application.
visible boolean Read-only. If true, the application is visible.
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 77
➤ 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).
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 78
}else {
docSelected.selected = false;newItem = docSelected.parent.duplicate( newDoc,
ElementPlacement.PLACEATEND );}
}else {
alert( "Please select one or more art objects" );}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 79
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 );
}}
Property Value type What it is
name string The name of the brush.
parent Document object
Read-only. The document that contains this brush.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
applyTo
(artItem) PageItem objectNothing Applies the brush to a specific art item.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 80
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.");}
Property Value type What it is
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.
Method Parameter type Returns What it does
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 81
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
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 82
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.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 83
➤ 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.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 84
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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 85
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.");}
Property Value type What it is
length number Read-only. The number of characters in the collection.
parent object Read-only. The text art item that contains this character.
typename string Read-only. Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 86
CharacterStyleAssociates character attributes with characters. For an example, see CharacterStyles.
CharacterStyle properties
CharacterStyle methods
Property Value type What it is
characterAttributes CharacterAttributes object
Read-only. The character properties for the text range.
name string The character style’s name.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
applyTo
(textItem [,clearingOverrides])
objectboolean
Nothing Applies the character style to the text object or objects.
remove
()
Nothing Deletes the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 87
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();
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
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
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 88
// 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);
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 89
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;
}
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
yellow number (double) The yellow color value. Range 0.0–100.0. Default: 0.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 90
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
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 91
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.
typename string Read-only. Read-only. The class name of the referenced object.
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.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
Compound-PathItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
Nothing Moves the object.
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 92
➤ 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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 93
}}
}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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 94
CompoundPathItemsA collection of CompoundPathItem objects.
CompoundPathItem methods
CompoundPathItem methods
➤ 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.");}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this collection (either a Layer or a GroupItem).
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
CompountPathItem object
Creates a new CompoundPathItem.
getByName
(name) stringCompountPathItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberCompountPathItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 95
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.
parent Document object
Read-only. The name of the object that contains this dataset.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
display
()
Nothing Displays the dataset.
remove
()
Nothing Deletes this object.
update
()
Nothing Updates the dataset.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 96
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();
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 97
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
parent Document object
Read-only. The name of the object that contains this dataset
typename string Read-only. Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Dataset object
Creates a new dataset object.
getByName
(name) stringDataset object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberDataset object
Gets an element from the collection.
removeAll
()
Nothing Removes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 98
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
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 99
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.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 100
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.
pathItems PathItems collection object
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.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 101
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.
tags Tags collection object
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.
typename string Read-only. Read-only. The class name of the referenced object.
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.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 102
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.
Property Value type What it is
Method Parameter type Returns What it does
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 103
➤ 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.
([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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 104
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 );
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberDocument object
Gets an element from the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 105
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();
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 106
elsesaveDoc = app.activeDocument;
var saveOpts = new EPSSaveOptions();saveOpts.cmykPostScript = true;saveOpts.compatibility = Compatibility.ILLUSTRATOR8;saveOpts.embedAllFonts = true;
saveDoc.saveAs( newFile, saveOpts );
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 107
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
Property Value type What it is
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 108
➤ 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
typename string Read-only. The class name of the referenced object.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 109
ExportOptionsGIFOptions for exporting a document as a GIF 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.
ExportOptionsGIF properties
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 110
➤ 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
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 111
ExportOptionsJPEGOptions for exporting a document as a JPEG 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.
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 );
}
Property Value type What it is
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
blurAmount number (double) The amount of blur to apply to the exported image. Range: 0.0 to 2.0 Default: 0.0
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 should be matted with a color. Default: true
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
typename string Read-only. The class name of the referenced object.
verticalScale number (double) The vertical scaling factor to apply to the exported image. Range: 0.0 to 776.19 Default: 100.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 112
ExportOptionsPhotoshopOptions for exporting a document as an Adobe Photoshop® 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.
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 );
}
Property Value type What it is
antiAliasing boolean If true, the exported image should be anti-aliased. Default: true
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
typename string Read-only. The class name of the referenced object.
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 113
ExportOptionsPNG8Options for exporting a document as an 8-bit PNG 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.
ExportOptionsPNG8 properties
Property Value type What it is
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: 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
horizontalScale number (double) The horizontal scaling factor to apply to the exported image, where 100.0 is 100%. Default: 100.0
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 be saved with an accompanying HTML file. Default: false
transparency boolean If true, the exported image use transparency. Default: true
typename string Read-only. The class name of the referenced object.
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 114
➤ 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 );
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 115
ExportOptionsPNG24Options for exporting a document as a 24-bit PNG 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.
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;
app.activeDocument.exportFile( fileSpec, type, exportOptions );}
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
verticalScale number (double)
The vertical scaling factor to apply to the exported image, where 100.0 is 100. Default: 100.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 116
ExportOptionsSVGOptions for exporting a document as a SVG 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.
ExportOptionsSVG properties
Property Value type What it is
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 117
➤ 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;
app.activeDocument.exportFile( fileSpec, type, exportOptions );}
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
typename string Read-only. The class name of the referenced object.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 118
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;
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Removes the referenced object from the document.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 119
// 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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 120
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;}
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 121
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();}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 122
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
Property Value type What it is
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%.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 123
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;
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
GradientStop object
Creates a new object.
index
(itemKey) numberGradientStop object
Gets an element from the collection.
removeAll
()
Nothing Deletes all objects in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 124
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] );}
}
Property Value type What it is
name string The graphic style name.
parent Document object Read-only. The document that contains this graphic style.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
applyTo
(artItem) ArtItem objectNothing Applies the art style to a specific art item.
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 125
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.");}
Property Value type What it is
length number Read-only. The number of graphic styles in the document.
parent object Read-only. The document that contains this graphic styles collection.
typename string Read-only. The class name of the referenced object.
Method Parameter type: Returns What it does
getByName
(name) stringGroupItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberGroupItem object
Gets an element from the collection.
removeAll
()
Nothing Removes all elements in the referenced collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 126
GraphItemAny graph artwork object. See example Rotating graph items below.
GraphItem properties
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout. You cannot set this value to Unknown.
blendingMode BlendModes The mode used when compositing an object.
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.
isIsolated boolean If true, this object is isolated.
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.
parent Layer object or GroupItem object
Read-only. The parent of this object.
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
tags Tags collection object
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 127
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
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.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
GraphItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
GraphItem object
Moves the object.
remove
()
Nothing Deletes this object.
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%.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 128
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)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 129
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.");}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
getByName
(name) stringGraphItems object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberGraphItems object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 130
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;
}
Property Value type What it is
gray number (double) The tint of the gray. Range: 0.0 to 100.0, where 0.0 is black and 100.0 is white.
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 131
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
clipped boolean If true, the group is clipped to its first path item.
compoundPathItems CompoundPathItems collection object
Read-only. The compound path items contained in this group.
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.
graphItems GraphItems collection object
Read-only. The graph items contained in this group.
groupItems GroupItems collection object
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.
isIsolated boolean If true, this object is isolated.
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.
meshItems MeshItems collection object
Read-only. The mesh items contained in this group.
name string The name of this group item.
opacity number (double) The opacity of the object. Range: 0.0 to 100.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 132
pageItems PageItems collection object
Read-only. The page items (all art item classes) contained in this group.
parent Layer object or GroupItem object
Read-only. The parent of this object.
pathItems PathItems collection object
Read-only. The path items contained in this group.
placedItems PlacedItems collection object
Read-only. The placed items contained in this group.
pluginItems PluginItems collection object
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.
rasterItems RasterItems collection object
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
symbolItems SymbolItems collection object
Read-only. The symbol item objects in this group.
tags Tags collection object
Read-only. The tags contained in this group.
textFrames TextFrames collection object
Read-only. The text art items contained in this group.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this group item.
visibilityVariable Variable object The visibility variable bound to the 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.
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 group object within the stacking order of the group or layer (parent) that contains the group object.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 133
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
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
GroupItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
GroupItem object
Moves the object.
remove
()
Nothing Deletes this object.
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)Transformation
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 134
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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 135
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 );
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
GroupItem object
Creates a new object.
createFromFile
(imageFile) File objectGroupItem object
Places an external vector art file as a group item in the document.
getByName
(name) stringGroupItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberGroupItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 136
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 );
}
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 137
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;
Property Value type What it is
inkInfo InkInfo object The ink information
name string The ink’s name
typename string Read-only. The class name of the object
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 138
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();
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 139
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(" ");}
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
index
(itemKey) string, numberInsertionPoint object
Gets an element from the collection,
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 140
LabColorA color specification in the CIE Lab color space, used where a color object is required.
LabColor properties7
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 141
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout. You cannot set this value to Unknown.
blendingMode BlendModes The mode used when compositing an object.
color RGBColor object The layer’s selection mark color.
compoundPathItems CompoundPathItems collection object
Read-only. The compound path items contained in this layer.
dimPlacedImages boolean If true, placed images should be rendered as dimmed in this layer.
graphItems GraphItems collection object
Read-only. The graph items contained in this layer.
groupItems GroupItems collection object
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.
isIsolated boolean If true, this object is isolated.
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.
meshItems MeshItems collection object
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
pageItems PageItems collection object
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 142
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];
pathItems PathItems collection object
Read-only. The path items contained in this layer.
placedItems PlacedItems collection object
Read-only. The placed items contained in this layer.
pluginItems PluginItems collection object
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.
rasterItems RasterItems collection object
Read-only. The raster items contained in this layer.
sliced boolean If true, the layer item is sliced. Default: false
symbolItems SymbolItems collection object
Read-only. The symbol items contained in the layer.
textFrames TextFrames collection object
Read-only. The text art items contained in this layer.
typename string Read-only. The class name of the referenced object.
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.
Property Value type What it is
Method Parameter type Returns What does it do
move
(relativeObject, insertionLocation)
objectElementPlacement
Layer object
Moves the object.
remove
()
Nothing Deletes this object.
zOrder
(ZOrderCmd) ZOrderMethodNothing Arranges the layer’s position in the
stacking order of the containing layer or document (parent) of this object
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 143
bottomLayer.zOrder(ZOrderMethod.BRINGTOFRONT);}else {
alert("The active document only has only 1 layer") }}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 144
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 );
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Layer object
Creates a new layer in the document.
getByName
(name) stringLayer object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberLayer object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 145
LegacyTextItemThe text frame items in a story which have not been converted to the new format.
LegacyTextItem properties
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
controlBounds array of 4 numbers Read-only. The bounds of the object including stroke width and controls.
converted boolean Read-only. If true, the legacy text item has been updated to a native text frame item.
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 group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 146
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.
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 item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
convertToNative
()
TextFrame object
Create a native text frame from a legacy text item. The original legacy text item is deleted.
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
LegacyTextItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
LegacyTextItem object
Moves the object.
remove
()
Nothing Deletes this object.
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 147
transform
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 148
LegacyTextItemsA collection of LegacyTextItem objects.
LegacyTextItems properties
LegacyTextItems methods
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
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
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 149
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
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
index
(itemKey) numberTextRange object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 150
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 );}
}
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 151
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend 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 group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
visibleBounds array of 4 numbers Read-only. The visible bounds of the item including stroke width.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 152
MeshItem methods
width number (double) The width of the item.
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 item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
MeshItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
MeshItem object
Moves the object.
remove
()
Nothing Deletes this object.
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)Transformation
Nothing Transforms the art item by applying a transformation matrix.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 153
➤ 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
([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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 154
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;
}}
Property Value type What it is
length number Read-only. The number of objects in the collection
parent object Read-only. The parent of this object
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
getByName
(name) stringMeshItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberMeshItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 155
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();
Property Value type What it is
typename string Read-only. The class name of the object
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 156
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);
}
Property Value type What it is
typename string Read-only. The class name of the object.
updateLegacyText boolean Whether to update all legacy text items (from previous versions of Illustrator). Default: false
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 157
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;
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
getByName
(name) stringPageItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberPageItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 158
var sourceName =sourceDoc.name;for ( i = 0; i < sourceDoc.pageItems.length; i++ ) {
artItem = sourceDoc.pageItems[i];switch ( artItem.typename ) {
case "PlacedItem":fileReferences.push( artItem.file.fsName );break;
case "RasterItem":if ( ! artItem.embedded ) {
fileReferences.push( artItem.file.fsName );}break;
}}// Write the file references to a new documentvar reportDoc = documents.add();var areaTextPath = reportDoc.pathItems.rectangle( reportDoc.height,0,
reportDoc.width, reportDoc.height );var fileNameText = reportDoc.textFrames.areaText( areaTextPath );fileNameText.textRange.size = 24;var text = "File references in \'" + sourceName + "\':\r\r";for ( i = 0; i < fileReferences.length; i++ ) {
text += ( fileReferences[i] + "\r" );}fileNameText.contents = text;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 159
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;
Property Value type What it is
name string The paper name.
paperInfo PaperInfo object The paper information.
typename string Read-only. The class name of the object.
Property Value type What it is
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.
typename string Read-only. The class name of the object.
width number (double) The paper’s width in points.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 160
textRef.contents += " x ";textRef.contents += paperInfoRef.width;textRef.contents += "\r";
} redraw();
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 161
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
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 162
➤ 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.
parent object Read-only. The object’s container.
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.
typename string Read-only. The class name of the object.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 163
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;
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 164
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 );
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
(contents [,relativeObject] [,insertionLocation])
stringTextFrame objectElementPlacement
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
(itemKey) numberTextRange object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 165
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
Property Value type What it is
characterAttributes CharacterAttributes object
Read-only. The character properties for the text range.
name string The paragraph style’s name.
paragraphAttributes ParagraphAttributes object
Read-only. The paragraph properties for the text range.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
applyTo
(textItem [,clearingOverrides])
objectboolean
Nothing Applies this paragraph style to the specified text item.
remove
()
Nothing Deletes the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 166
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");
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
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
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 167
// 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();
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 168
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
Property Value type What it is
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.
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
clipping boolean If true, this path should be used as a clipping path.
closed boolean If true, this path is closed.
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.
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.
geometricBounds array of 4 numbers Read-only. The bounds of the object excluding stroke width.
guides boolean If true, this path is a guide object.
height number (double) The height of the group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
name string The name of this item.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 169
note string The note text assigned to the path.
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.
pathPoints PathPoints collection object
Read-only. The path points contained in this path item.
polarity PolarityValues The polarity of the path.
position array of 2 numbers The position of the top left corner of the item.
resolution number (double) The resolution of the path in dots per inch (dpi).
selected boolean If true, this item is selected.
selectedPathPoints PathPoints collection object
Read-only. All of the selected path points in the path.
sliced boolean If true, the item sliced. Default: false
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.
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 170
PathItem 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.
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 item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
MeshItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
MeshItem object
Moves the object.
remove
()
Nothing Deletes this object.
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.
setEntirePath
(pathPoints) PathPoints objectNothing Sets the path using the
specified anchor points.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 171
➤ 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
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 172
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
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
PathItem object
Creates a new 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
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberPathItem object
Gets an element from the collection.
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
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 173
➤ 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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 174
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
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Removes the referenced point from the path.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 175
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;
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
PathPoint object
Creates a new PathPoint object.
index
(itemKey) numberPathPoint object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 176
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
Property Value type What it is
name string The pattern name.
parent Document object
Read-only. The document that contains this pattern.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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.
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Pattern object
Creates a new object.
getByName
(name) stringPattern object
Gets the first element in the collection with the provided name.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 177
➤ 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
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 178
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
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 179
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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 180
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); }
Property Value type What it is
pageToOpen number (long) What page should be used when opening a multipage document. Default: 1
parent object Read-only. The object’s container.
pDFCropToBox PDFBoxType Which box should be used when placing a multipage document. Default: PDFMediaBox
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 181
PDFSaveOptionsOptions for saving a document as an Adobe PDF file, used with the saveAs method. All properties are optional.
PDFSaveOptions properties
Property Value type What it is
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 182
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
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 183
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
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 184
➤ 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
typename string Read-only. The class name of the referenced object.
viewAfterSaving boolean View PDF after saving. Default: false
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 185
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 );
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 186
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); }
Property Value type What it is
parent object Read-only. The parent of this object.
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 187
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
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.
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.
file File object The file containing the artwork.
geometricBounds array of 4 numbers Read-only. The bounds of the object excluding stroke width.
height number (double) The height of the group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
matrix Matrix object The transformation matrix of the placed artwork.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 188
PlacedItem methods
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
visibleBounds array of 4 numbers Read-only. The visible bounds of the item including stroke width.
width number (double) The width of the item.
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 item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
PlacedItem object
Creates a duplicate of the selected object.
embed
()
Nothing Embeds this art in the document. Converts the art to art item objects as needed and deletes this object.
move
(relativeObject, insertionLocation)
objectElementPlacement
PlacedItem object
Moves the object.
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 189
➤ 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
(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.
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
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 190
if ( app.documents.length > 0 ) {for ( i = 0; i < app.activeDocument.placedItems.length; i++ ) {
placedArt = app.activeDocument.placedItems[i];placedArt.selected = !(placedArt.selected);
}}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 191
PlacedItemsA collection of PlacedItem objects in the document.
PlacedItems properties
PlacedItems methods
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberPlacedItem object
Gets an element from the collection.
removeAll
()
none Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 192
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend 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 group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
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.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 193
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.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
visibleBounds array of 4 numbers Read-only. The visible bounds of the item including stroke width.
width number (double) The width of the item.
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 Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
PluginItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
PluginItem object
Moves the object.
remove
()
Nothing Deletes this object.
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%.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 194
➤ 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
(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)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 195
PluginItemsA collection of PluginItem objects in a document. See Copying a plugin item.
PluginItems properties
PluginItems methods
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
getByName
(name) stringPluginItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberPluginItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all objects in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 196
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: ";
Property Value type What it is
name string The PPD name.
pPDInfo PPDFileInfo object
The PPD file information.
typename string Read-only. The class name of the object.
Property Value type What it is
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.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 197
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";
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 198
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);}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 199
PreferencesSpecifies the preferred options for Adobe PDF and Adobe Photoshop files.
Preferences properties
Property Value type What it is
parent object Read-only. The parent of this object.
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.
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 200
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);
Property Value type What it is
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.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 201
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);
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 202
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++) {
symbolRef = docRef.symbols[i];symbolItemRef1 = docRef.symbolItems.add(symbolRef);symbolItemRef1.top = y;symbolItemRef1.left = 100;y -= (symbolItemRef1.height + 20);
}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);
Property Value type What it is
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
typename string Read-only. The class name of the object.
verticalScale number (double) The vertical scaling factor expressed as a percentage (100 = 100%) Range: 1.0 to 10000.0 Default: 100.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 203
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
Property Value type What it is
name string The printer name.
printerInfo PrinterInfo object
The printer information.
typename string Read-only. The class name of the object.
Property Value type What it is
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 204
➤ 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.
typename string Read-only. The class name of the object.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 205
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);
}
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 206
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);
Property Value type What it is
downloadFonts PrintFontDownloadMode The font download mode. Default: DOWNLOADSUBSET
fontSubstitution FontSubstitutionPolicy The font substitution policy. Default: SUBSTITUTEOBLIQUE
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 207
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;
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 208
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);
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 209
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++) {
symbolRef = docRef.symbols[i];symbolItemRef1 = docRef.symbolItems.add(symbolRef);symbolItemRef1.top = y;symbolItemRef1.left = 100;y -= (symbolItemRef1.height + 10);
Property Value type What it is
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.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 210
} 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);
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 211
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);
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 212
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);
Property Value type What it is
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
typename string Read-only. The class name of the object.
width number (double) The custom width (in points) for using the custom paper. Default: 0.0
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 213
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);
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 214
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
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.
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.
embedded boolean If true, the raster art item is embedded in the illustration.
file File object The file containing the artwork.
geometricBounds array of 4 numbers Read-only. The bounds of the object excluding stroke width.
height number (double) The height of the group item.
hidden boolean If true, this item is hidden.
imageColorSpace ImageColorSpace Read-only. The color space of the raster image.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
matrix Matrix object The transformation matrix of the placed artwork.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 215
RasterItem methods
status RasterLinkState Status of the linked image.
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
visibleBounds array of 4 numbers Read-only. The visible bounds of the item including stroke width.
width number (double) The width of the item.
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 Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
colorize
(rasterColor) color objectNothing Colorizes the raster item with a
CMYK or RGB Color.
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
RasterItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
RasterItem object
Moves the object.
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 216
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.
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
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 217
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;
}}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
RasterItem object
Creates a new object.
getByName
(name) stringRasterItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberRasterItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 218
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;
}
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 219
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;
Property Value type What it is
name string The color separation screen name.
screenInfo ScreenInfo object The color separation screen information.
typename string Read-only. The class name of the object.
Property Value type What it is
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.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 220
textRef.contents = sInfo;textRef.top = (docRef.height - 30);textRef.left = 30;redraw();
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 221
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();
Property Value type What it is
name string The color separation screen spot function name.
spotFunction string The spot function expressed in PostScript commands.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 222
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 + "%" );
}
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 223
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
Property Value type What it is
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
typename string Read-only. The class name of the referenced object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 224
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
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Spot object
Creates a new object.
getByName
(name) stringSpot object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberSpot object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 225
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;
}
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 226
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
Property Value type What it is
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.
parent object Read-only. The object’s container.
textFrames TextFrames collection object
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.
typename string Read-only. The class name of the object.
words Words collection object
Read-only. All the words in the story.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 227
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");
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 228
StoriesA collection of Story objects in a document.
Stories properties
Stories methods
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
index
(itemKey) string, numberStory object
Gets an element from the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 229
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";
}
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 230
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" );}
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Swatch object
Creates a new Swatch object.
getByName
(name) stringSwatch object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberSwatch object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 231
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
Property Value type What it is
name string The symbol’s name.
parent object Read-only. The object that contains the symbol object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
duplicate
()
Symbol object
Create a duplicate of this object.
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 232
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?
Property Value type What it is
length number Read-only. The number of objects in the collection
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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
Gets an element from the collection.
getByName
(name) stringSymbol object
Gets the first element in the collection with the specified name.
removeAll
()
Nothing Deletes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 233
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.");
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 234
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
Property Value type What it is
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend 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 group item.
hidden boolean If true, this item is hidden.
isIsolated boolean If true, this object is isolated.
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
locked boolean If true, this item is locked.
name string The name of this 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.
position array of 2 numbers The position of the top left corner of the item.
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
symbol Symbol object The symbol that was used to create this symbolItem.
tags Tags collection object
Read-only. The tags contained in this item.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 235
SymbolItem 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.
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 Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
SymbolItem object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
SymbolItem object
Moves the object.
remove
()
Nothing Deletes this object.
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 236
transform
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 237
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;
}}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
(symbol) Symbol objectSymbolItem object
Creates an instance of the specified symbol.
getByName
(name) stringSymbolItem object
Gets the first element in the collection with the specified name.
index
(itemKey) string, numberSymbolItem object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 238
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 );
Property Value type What it is
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
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 239
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." ); }
}
Property Value type What it is
name string The tag’s name.
parent object Read-only. The object that contains this tag.
typename string Read-only. The class name of the referenced object.
value string The data stored in this tag.
Method Parameter type Returns What it does
remove
()
Nothing Deletes this object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 240
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" );}
}
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
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
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 241
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];
}}
Property Value type What it is
family string Read-only. The font’s family name.
name string Read-only. The font’s full name.
parent object Read-only. The object’s container.
style string Read-only. The font’s style name.
typename string Read-only. The class name of the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 242
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;
}}
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
index
(itemKey) string, numberTextFont object
Get an element from the collection.
getByName
(name) stringTextFont object
Get the first element in the collection with the provided name.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 243
TextFrameThe basic art item for displaying text. Multiple text frames can be linked together within a story.
TextFrame properties
Property Value type What it is
anchor array of 2 numbers The position of the anchor point, the start of the base line for point text.
artworkKnockout KnockoutState Is this object used to create a knockout, and if so, what kind of knockout.
blendingMode BlendModes The blend mode used when compositing an object.
characters Characters collection object
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.
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.
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).
geometricBounds array of 4 numbers Read-only. The bounds of the object excluding stroke width.
height number (double) The height of the group item.
hidden boolean If true, this item is hidden.
insertionPoints InsertionPoints collection object
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).
layer Layer object Read-only. The layer to which this item belongs.
left number (double) The position of the left side of the item.
lines Lines collection object
Read-only. All the lines in this text range.
locked boolean If true, this item is locked.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 244
matrix Matrix object Read-only. The transformation matrix for this text frame.
name string The name of this item.
nextFrame TextFrame object The linked text frame following this one.
opacity number (double) The opacity of the object. Range: 0.0 to 100.0
opticalAlignment boolean If true, the optical alignment feature is active.
orientation TextOrientation The orientation of the text.
paragraphs Paragraphs collection object
Read-only. All the paragraphs in this text range.
parent Layer object or GroupItem object
Read-only. The parent of this object.
position array of 2 numbers The position of the top left corner of the item.
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).
selected boolean If true, this item is selected.
sliced boolean If true, the item sliced. Default: false
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.
tags Tags collection object
Read-only. The tags contained in this item.
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.
textRanges TextRanges collection object
Read-only. All the text in this text frame.
textSelection array of TextRange objects
Read-only. The selected text ranges in the text frame.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
uRL string The value of the Adobe URL tag assigned to this item.
visibilityVariable Variable object The visibility variable bound to the item.
Property Value type What it is
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 245
TextFrame 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.
words Words collection object
Read-only. All the words in this text range.
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 Read-only. The position of this item within the stacking order of the group or layer (parent) that contains the item.
Property Value type What it is
Method Parameter type Returns What it does
createOutline
()
GroupItem object
Creates an outline for the frame text.
duplicate
([relativeObject] [,insertionLocation])
objectElementPlacement
TextRange object
Creates a duplicate of the selected object.
move
(relativeObject, insertionLocation)
objectElementPlacement
TextRange object
Moves the object.
remove
()
Nothing Deletes this object.
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 246
➤ 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
(transformationMatrix[,changePositions][,changeFillPatterns][,changeFillGradients][,changeStrokePattern][,changeLineWidths][,transformAbout])
Matrix objectbooleanbooleanbooleanbooleannumber (double)Transformation
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.
Method Parameter type Returns What it does
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 247
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)
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
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
Gets the first element in the collection with the provided name.
index
(itemKey) string, numbertextFrame object
Gets an element from the collection.
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 248
// 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.");
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 249
TextPathA path or list of paths for area or path text. A path consists of path points that define its geometry.
TextPath properties
Property Value type What it is
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.
blendingMode BlendModes The blend mode used when compositing an object.
clipping boolean If true, this path should be used as a clipping path.
editable boolean Read-only. If true, this item is editable.
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.
height number (double) The height of the group item.
left number (double) The position of the left side of the item.
note string The note text assigned to the path.
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.
pathPoints PathPoints collection object
Read-only. The path points contained in this path item.
polarity PolarityValues The polarity of the path.
position array of 2 numbers The position of the top left corner of the item.
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 250
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.
top number (double) The position of the top of the item.
typename string Read-only. The class name of the referenced object.
width number (double) The width of the item.
Property Value type What it is
Method Parameter type Returns What it does
setEntirePath
(pathPoints) PathPoints objectNothing Sets the path using the
specified anchor points.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 251
TextRangeA range of text in a specific text art item. TextRange gives you access to the text contained in text art items.
TextRange properties
Property Value type What it is
characterAttributes CharacterAttributes collection object
Read-only. The character properties for the text range.
characterOffset number (long) Offset of the first character.
characters Characters collection object
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.
insertionPoints InsertionPoints collection object
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
lines Lines collection object
Read-only. All the lines in this text range.
paragraphAttributes ParagraphAttributes collection object
Read-only. The paragraph properties for the text range.
paragraphs Paragraphs collection object
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.
textRanges TextRanges collection object
Read-only. All of the text in this text range.
textSelection array of TextRange objects
Read-only. The selected text ranges in the text range.
typename string Read-only. The class name o f the object.
words Words collection object
Read-only. All the words contained in this text range.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 252
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
([relativeObject] [,insertionLocation])
objectElementPlacement
TextRange object
Creates a duplicate of this object.
move
(relativeObject, insertionLocation)
objectElementPlacement
TextRange object
Moves the object.
remove
()
Nothing Deletes the object.
select
([addToDocument]) booleanNothing Selects the text range. If
addToDocument is true, adds this to the current selection; otherwise replaces the current selection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 253
TextRangesA collection of TextRange objects.
TextRanges properties
TextRanges methods
Property Value type What it is
length number Read-only. Number of elements in the collection.
parent object Read-only. The object’s container.
typename string Read-only. The class name of the object.
Method Parameter type Returns What it does
index
(itemKey) string, numberTextRange object
Get an element from the collection
removeAll
()
Nothing Deletes all elements in the object.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 254
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
Property Value type What it is
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.
parent object Read-only. The object’s container.
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.
typename string Read-only. The class name of the object.
usedColorCount number (long) Read-only. The number of colors used in the tracing result.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 255
TracingObject methods
Method Parameter type Returns What it does
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 256
TracingOptionsA set of options used in converting raster art to vector art by tracing.
TracingOptions properties
Property Value type What it is
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.
parent object Read-only. The object’s container.
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
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 257
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.
typename string Read-only. The class name of the object.
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.)
Property Value type What it is
Method Parameter type Returns What it does
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.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 258
VariableA document-level variable that can be imported or exported. See also Dataset.
Variable properties
Variable methods
Property Value type What it is
kind VariableKind The variable’s type.
name string The name of this variable.
pageItems PageItems collection object
Read-only. All of the artwork n this document.
parent object Read-only. The object that contains the variable.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
remove
()
Nothing Removes the variable from the collection of variables.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 259
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
Property Value type What it is
length number Read-only. The number of variables in the document
parent object Read-only. The object that contains the collection of variables.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
()
Variable object
Adds a new variable to the collection.
getByName
(name) stringVariable object
Get the first element in the collection with the provided name.
index
(itemKey) string, numberVariable object
Get an element from the collection.
removeAll
()
Nothing Deletes all elements in the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 260
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;
}
Property Value type What it is
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.
typename string Read-only. The class name of the referenced object.
zoom number (double) The zoom factor of this view, where 100.0 is 100%.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 261
ViewsA collection of View objects in a document.
Views properties
Views methods
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
index
(itemKey) string, numberView object Gets an element from the collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 262
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 ) {
Property Value type What it is
length number Read-only. The number of objects in the collection.
parent object Read-only. The parent of this object.
typename string Read-only. The class name of the referenced object.
Method Parameter type Returns What it does
add
(contents[, relativeObject][, insertionLocation])
stringTextFrame objectElementPlacement
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
(itemKey) numberTextRange object
Gets an element from the collection.
removeAll
()
Nothing Deletes all elements in this collection.
Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 263
// 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".
Special characters are those with a numeric value greater than 127, except the following:
/ - _ . ! ~ * ' ( )
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 266
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.
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 267
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 268
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 269
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 270
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.
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.
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 271
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.
prompt Optional. A string containing the prompt text, if the dialog allows a prompt.
preset 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.
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 272
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.
text One or more strings to write, which are concatenated to form a single string.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 273
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 274
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".
Special characters are those with a numeric value greater than 127, except the following:
/ - _ . ! ~ * ' ( )
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".
Special characters are those with a numeric value greater than 127, except the following:
/ - _ . ! ~ * ' ( )
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 275
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.
prompt Optional. A string containing the prompt text, if the dialog allows a prompt.
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 276
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 277
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.
prompt Optional. A string containing the prompt text, if the dialog allows a prompt.
preset Optional. A Folder object for a folder to be preselected when the dialog opens.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 278
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.
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 279
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
Adobe Illustrator CS2JavaScript Scripting Reference File and Folder Object Reference 280
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 ConstantsThis 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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 283
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 284
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 285
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 286
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 287
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 288
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 289
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
Constant Type Values What it means
Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 290
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
Constant Type Values What it means
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 293
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 294
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 295
● 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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 296
● 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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 297
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 298
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 299
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 300
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 301
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 302
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 303
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 304
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 305
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.
text One or more strings to write, which are concatenated to form a single string.
writeln
$.writeln (text[, text...]...)
Writes the specified text to the JavaScript Console and appends a linefeed sequence. Returns undefined.
text One or more strings to write, which are concatenated to form a single string.
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 306
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 307
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 308
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 309
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 310
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);
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 311
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 312
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 313
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"));
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 314
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 315
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.
message The string for the displayed message.
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.
message The string for the displayed message.
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".
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 316
➤ Examples
This figure shows simple prompt dialogs in Windows and Mac OS.
This figure shows confirmation dialogs with a title value specified.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 317
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)
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 318
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".
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 319
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 320
● 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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 321
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 322
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 323
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 324
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 +, -*, /, %, ^<, <=, ==<<, >>, >>>&, |, ===
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 325
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.
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 326
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
Adobe Illustrator CS2JavaScript Scripting Reference ExtendScript Tools and Features 327
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
Adobe Illustrator CS2JavaScript Scripting Reference Index 330
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
Adobe Illustrator CS2JavaScript Scripting Reference Index 331
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
Adobe Illustrator CS2JavaScript Scripting Reference Index 332
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
Adobe Illustrator CS2JavaScript Scripting Reference Index 333
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
Adobe Illustrator CS2JavaScript Scripting Reference Index 334
Zzero point 67
Top Related