Illustrator CS2 JavaScript Scripting Reference Illustrator CS2 JavaScript ... Application properties ... activeDocument ...

Download Illustrator CS2 JavaScript Scripting Reference  Illustrator  CS2 JavaScript ... Application properties ... activeDocument ...

Post on 05-May-2018

214 views

Category:

Documents

2 download

TRANSCRIPT

  • bbc

    Adobe I

    llust

    rato

    r 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

    Introduction

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

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

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

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

    Using File and Folder Objects, which describes ExtendScripts 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 ExtendScripts 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, youll likely miss out on the creative potential of such labor-intensive techniques.

    Scripting isnt just for computer programmersits for everybody. You dont 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 youre 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 youll find that you spend most of your time doing the same or similar production tasks, over and over again. In fact, youll 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.

    Wouldnt it be great if you had an assistantone that wouldnt mind doing some or all of the boring, repetitive tasks for you? With that kind of help, youd 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 youre sleeping.

    Think about your workis there a repetitive task thats driving you crazy? If so, youve 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, youll 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 applicationmenu 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 programs 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 programs 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, Adobes 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 CS2s 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 Basics

    When you use Illustrator, you work with documents and their contents. You create documents, layers, colors, and design elements. You probably think of these things as objects, that you can look at and move around, and they are in fact represented by objects in the Illustrator object model. The Illustrator object model contains documents, layers, colors, and page itemsobjects 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?

    Heres 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 closebut 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, thoughyou cant 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, youll soon have a door of a different color.

    Now lets 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 objectpaths, text, meshes, and so onbelongs 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 objectpage 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, youre 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 Adobes 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 objects 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 variablessomething 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 variables 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 theyll 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 verbstheyre the parts of the script that make things happen. The type of the object youre 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 decisionsthey 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 users 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 runningwhich 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 youve 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, theres no need for you to worry about error handling. If not, however, youll 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.; OReilly 2001; ISBN 0-596-00048-0

    JavaScript Programmers Reference; Wootton, C.; Wrox 2001; ISBN 1-861004-59-1

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

  • 3

    Scripting Illustrator

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

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

    Illustrator Scripting Object Model

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

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

    Application

    Text Font

    Document

    Layer

    Group Item

    Page Item

    Path Item

    Text Frame

    Symbol Item

    CompoundPath Item

    Graph Item

    Mesh ItemBrush

    Dataset

    Paragraph Style

    Character Style

    Spot

    Swatch

    Variable

    Symbol

    Pattern

    Gradient

    Graphic Style

    View

    Path Item

    Placed Item

    Plugin Item

    Raster Item

    Path Point

    Story

    Printers

    PPD File List

    Print Preset List

    PDF Preset List

    Flattener Preset List

    Ink ListLegacy Text Item

    60

  • Adobe Illustrator CS2JavaScript Scripting Reference Scripting Illustrator 61

    Referencing and Creating Objects in JavaScript

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

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

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

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

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

    BrushGradientGraphicStylePatternSwatchSymbolVariable

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

    CharactersGradientStopsLinesParagraphsPathPointsWords

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

    frontMostDocument = app.activeDocument;

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

    var newCMYKcolor = new CMYKColor();

    The following objects must be created:

    CMYKColorColorEPSSaveOptionsExportOptionsFlashExportOptionsGIFExportOptionsJPEGExportOptionsPhotoshopExportOptionsPNG8

    ExportOptionsPNG24ExportOptionsPS5ExportOptionsSVGFileFolderGradientColorGrayColorIllustratorSaveOptions

    MatrixPatternColorPDFOpenOptionsPDFOpenOptionsPDFSaveOptionsRGBColorSpotColorNoColor

  • 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 users 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

  • 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, Bzier curves, and path points, refer to the Illustrator Plug-in Software Development Kit Function Reference. This document is available as part of the Illustrator Software Development Kit (SDK), which can be downloaded from the Adobe Solutions Network (ASN) web site:

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

    Working with color

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

    Working with symbols and symbol items

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

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

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

    pathItem

    pathPoint

    rightDirection

    anchor

    leftDirection

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

  • 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 frames 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 objects 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 rulers 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 rulers 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 objects 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 "Brun" 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 platforms 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 objects open method opens the linked file (in /folder1). Calling the File objects 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 Reference

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

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

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

    Notes to explain special issues.

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

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

    74

  • Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 75

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

    Application properties

    Property Value type What it is

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

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

    documents Documents collection object

    Read-only. The documents in the application.

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

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

    name string Read-only. The applications 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 documents 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 objects 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

  • 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 styles name.

    parent object Read-only. The objects 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 objects 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 documents 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 documents 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.0100.0. Default: 0.0

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

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

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

    yellow number (double) The yellow color value. Range 0.0100.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 items 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 settingsthose properties starting with the word defaultare 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 documents 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 documents 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 documents cropping box for output, or null if no value has been set.

    cropStyle CropOptions The style of the documents 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 documents 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 documents 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 documents 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 printers 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.

    print

    ([options]) PrintOptions objectNothing Prints the document.

    save

    ()

    Nothing Saves the document in it current location.

    saveAs

    (saveIn[, options])

    File objectSaveOptions object

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

    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.0112.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: 722400 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 images 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 documents 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 images 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 gradients 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.087.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 items 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

  • 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 items 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 documents 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

  • 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

  • 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.0128.0. Default: 0.0

    b number (double) The b (yellow-blue) color value. Range -128.0128.0. Default: 0.0

    l number (double) The l (lightness) color value. Range -128.0128.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 layers 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 layers 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 items 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 objects 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 objects 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 items 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

  • 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 objects 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 styles name.

    paragraphAttributes ParagraphAttributes object

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

    parent object Read-only. The objects 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 objects 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

  • 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 items 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 points anchor point.

    leftDirection array of 2 numbers The position of this path points 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 points 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 objects 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 images 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 images 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 images 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 items 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 objects 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 items 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

  • 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))

  • 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

  • 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

  • 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

  • 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 papers maximum height.

    maxPaperHeightOffset number (double) Custom papers maximum height offset.

    maxPaperWidth number (double) Custom papers maximum width.

    maxPaperWidthOffset number (double) Custom papers 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

  • 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

  • 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

  • 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 papers 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 items 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 documents 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 documents 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

  • 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

  • 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 colors 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 objects 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 objects 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 swatchs 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 doesnt 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 symbols 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

  • Adobe Illustrator CS2JavaScript Scripting Reference JavaScript Object Reference 233

    if( (y-=60)

  • 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 items 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

  • 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 tags 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 fonts family name.

    name string Read-only. The fonts full name.

    parent object Read-only. The objects container.

    style string Read-only. The fonts 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

  • 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 paths 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 paths 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

  • 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 objects 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 objects 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 its 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 objects 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 documents 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 objects 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 objects 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 variables 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 documents bounds.

    centerPoint array of 2 numbers The center point of this view relative to the current documents 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 files 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 objects 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 objects parent folder and the current file to this objects 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 objects parent folder and the file to this objects 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 objects 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 Constants

    This section lists and describes the enumerations defined for use with Illustrator JavaScript properties and methods.

    Constant Type Values What it means

    AlternateGlyphsForm DEFAULTFORMEXPERTFULLWIDTHHALFWIDTHJIS78FORMJIS83FORMPROPORTIONALWIDTHQUARTERWIDTHTHIRDWIDTHTRADITIONAL

    AutoKernType AUTONOAUTOKERNOPTICAL

    AutoLeadingType BOTTOMTOBOTTOMTOPTOTOP

    BaselineDirectionType StandardTateChuYokoVerticalRotated

    BlendAnimationType INBUILDINSEQUENCENOBLENDANIMATION

    BlendModes COLORBLENDCOLORBURNCOLORDODGEDARKENDIFFERENCEEXCLUSIONHARDLIGHTHUELIGHTENLUMINOSITYMULTIPLYNORMALOVERLAYSATURATIONBLENDSCREENSOFTLIGHT

    The blend mode used when compositing an object.

    BurasagariTypeEnum ForcedNoneStandard

    CaseChangeType LOWERCASESENTENCECASETITLECASEUPPERCASE

    281

  • Adobe Illustrator CS2JavaScript Scripting Reference Scripting Constants 282

    ColorConversion COLORCONVERSIONREPURPOSECOLORCONVERSIONTODESTNone

    ColorDestination COLORDESTINATIONDOCCMYKCOLORDESTINATIONDOCRGBCOLORDESTINATIONPROFILECOLORDESTINATIONWORKINGCMYKCOLORDESTINATIONWORKINGRGBNone

    ColorDitherMethod DIFFUSIONNOISENOREDUCTIONPATTERNDITHER

    The method used to dither colors in exported GIF and PNG8 images.

    ColorModel PROCESSREGISTRATIONSPOT

    ColorProfile INCLUDEALLPROFILEINCLUDEDESTPROFILEINCLUDERGBPROFILELEAVEPROFILEUNCHANGEDNone

    ColorReductionMethod ADAPTIVEPERCEPTUALSELECTIVEWEB

    The method used to reduce the number of colors in exported GIF and PNG8 images.

    ColorType CMYKGRADIENTGRAYNONEPATTERNRGBSPOT

    The color specification for an individual color.

    Compatibility ILLUSTRATOR3ILLUSTRATOR8ILLUSTRATOR9ILLUSTRATOR10ILLUSTRATOR11ILLUSTRATOR12JAPANESEVERSION3

    The version of the Illustrator file to create when saving an EPS or Illustrator file

    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 documents 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 items 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 items 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 FeaturesExtendScript is Adobes 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 platforms 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 Toolkits 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 variables 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 tabs 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 Editors 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 applications 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 Editors 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 tabs 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 breakpoints 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 Objects 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 scripts 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 whlen 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 applications 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 variables 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 windows 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 unitValues 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 ($) Objects 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 objects 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

  • 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 applications 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

    ContentsIntroductionWhat is scripting?Why use scripting?What about actions?

    Script Support in Adobe Illustrator CS2JavaScript supportExecuting scriptsInstalling scriptsExecuting other scripts

    Startup scripts

    Changes Since Earlier Versions

    Scripting BasicsObject model conceptsObject classes and containersObject inheritanceObject elements or collectionsObject references

    Scripting conceptsCommentsLong script linesCase sensitivityValue typesVariablesDeclaring variables and assigning valuesVariable naming

    OperatorsFunctionsConditional statementsControl structuresIncluding Other Script Files

    Testing and troubleshootingAbout error handling

    JavaScript Resources

    Scripting IllustratorThe Illustrator object modelReferencing and Creating Objects in JavaScriptWorking with the Selection ObjectWorking with pathsWorking with colorWorking with symbols and symbol items

    Working with MethodsWorking with Text and PrintingContent of a Text RangeCharacter Style, Character Attributes, Local Character AttributesPrinting Illustrator Documents

    Measurement unitsEm Space UnitsPage item positioning and dimensions

    Using File and Folder ObjectsOverviewSpecifying PathsAbsolute and relative path namesCharacter interpretation in pathsThe home directoryVolume and drive namesMac OS volumesWindows drives

    AliasesPortability issues

    Unicode I/OFile Error Handling

    JavaScript Object ReferenceApplicationApplication propertiesactiveDocumentbrowserAvailabledocumentsflattenerPresetsListfreeMemorynamepathPDFPresetsListPPDFileListpreferencesprinterListprintPresetsListscriptingVersionselectiontextFontstracingPresetListtypenameuserInteractionLevelversionvisible

    Application methodsbeepconcatenateMatrixconcatenateRotationMatrixconcatenateScaleMatrixconcatenateTranslationMatrixgetIdentityMatrixgetRotationMatrixgetScaleMatrixgetTranslationMatrixinvertMatrixisEqualMatrixisSingularMatrixopenquitredrawshowPresetstranslatePlaceholderText

    BrushBrush propertiesnameparenttypename

    Brush methodsapplyTo

    BrushesBrushes propertieslengthparenttypename

    Brushes methodsgetByNameindex

    CharacterAttributesCharacterAttributes propertiesakiLeftakiRightalignmentalternateGlyphsautoLeadingbaselineDirectionbaselinePositionbaselineShiftcapitalizationconnectionFormscontextualLigaturediscretionaryLigaturefigureStylefillColorfractionshorizontalScaleitalicskerningMethodlanguageleadingligaturenoBreakopenTypePositionordinalsornamentsoverprintFilloverprintStrokeparentproportionalMetricsrotationsizestrikeThroughstrokeColorstrokeWeightstylisticAlternatesswashtateChuYokoHorizontaltateChuYokoVerticaltextFonttitlingtrackingTsumetypenameunderlineverticalScalewariChuCharactersAfterBreakwariChuCharactersBeforeBreakwariChuEnabledwariChuJustificationwariChuLineGapwariChuLineswariChuScale

    CharactersCharacters propertieslengthparenttypename

    Characters methodsaddaddBeforeindexremoveAll

    CharacterStyleCharacterStyle propertiescharacterAttributesnameparenttypename

    CharacterStyle methodsapplyToremove

    CharacterStylesCharacterStyles propertieslengthparenttypename

    CharacterStyles methodsaddgetByNameindexremoveAll

    CMYKColorCMYKColor propertiesblackcyanmagentatypenameyellow

    CompoundPathItemCompoundPathItem propertiesartworkKnockoutblendingModecontrolBoundseditablegeometricBoundsheighthiddenisIsolatedlayerleftlockednameopacityparentpathItemspositionselectedslicedtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    CompoundPathItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    CompoundPathItemsCompoundPathItem methodslengthparenttypename

    CompoundPathItem methodsaddgetByNameindexremoveAll

    DatasetDataset propertiesnameparenttypename

    Dataset methodsdisplayremoveupdate

    DatasetsDatasets propertieslengthparenttypename

    Datasets methodsaddgetByNameindexremoveAll

    DocumentDocument propertiesactiveDatasetactiveLayeractiveViewbrushescharacterStylescompoundPathItemscropBoxcropStyledataSetsdefaultFillColordefaultFilleddefaultFillOverprintdefaultStrokeCapdefaultStrokeColordefaultStrokeddefaultStrokeDashesdefaultStrokeDashOffsetdefaultStrokeJoindefaultStrokeMiterLimitdefaultStrokeOverprintdefaultStrokeWidthdocumentColorSpacefullNamegeometricBoundsgradientsgraphicStylesgraphItemsgroupItemsheightinkListkinsokuSetlayerslegacyTextItemsmeshItemsmojikumiSetnameoutputResolutionpageItemspageOriginparagraphStylesparentpathpathItemspatternsplacedItemspluginItemsprintTilesrasterItemsrulerOriginrulerUnitssavedselectionshowPlacedImagessplitLongPathsspotsstationerystoriesswatchessymbolItemssymbolstagstextFramestileFullPagestypenameuseDefaultScreenvariablesvariablesLockedviewsvisibleBoundswidth

    Document methodsactivatecloseexportFileexportPDFPresetexportPrintPresetexportVariablesimportCharacterStylesimportParagraphStylesimportPDFPresetimportPrintPresetimportVariablesprintsavesaveAs

    DocumentsDocuments propertieslengthparenttypename

    Documents methodsaddgetByNameindex

    EPSSaveOptionsEPSSaveOptions propertiescmykPostScriptcompatibilitycompatibleGradientPrintingembedAllFontsembedLinkedFilesflattenOuputincludeDocumentThumbnailsoverprintpostScriptpreviewtypename

    ExportOptionsFlashExportOptionsFlash propertiesartBoardClippingbackgroundColorbackgroundLayersblendAnimationcompressedconvertTextToOutlinescurveQualityexportStyleflattenOutputframeRategenerateHTMLimageFormatjpegMethodjpegQualitylayerOrderloopingreadOnlyreplacingresolutiontypename

    ExportOptionsGIFExportOptionsGIF propertiesantiAliasingartBoardClippingcolorCountcolorDithercolorReductionditherPercenthorizontalScaleinfoLossPercentinterlacedmattematteColorsaveAsHTMLtransparencytypenameverticalScalewebSnap

    ExportOptionsJPEGExportOptionsJPEG propertiesantiAliasingartBoardClippingblurAmounthorizontalScalemattematteColoroptimizationqualitySettingsaveAsHTMLtypenameverticalScale

    ExportOptionsPhotoshopExportOptionsPhotoshop propertiesantiAliasingcompatibilityeditableTextembedICCProfileimageColorSpacemaximumEditabilityresolutiontypenamewarningswriteLayers

    ExportOptionsPNG8ExportOptionsPNG8 propertiesantiAliasingartBoardClippingcolorCountcolorDithercolorReductionditherPercenthorizontalScaleinterlacedmattematteColorsaveAsHTMLtransparencytypenameverticalScalewebSnap

    ExportOptionsPNG24ExportOptionsPNG24 propertiesantiAliasingartBoardClippinghorizontalScalemattematteColorsaveAsHTMLtransparencytypenameverticalScale

    ExportOptionsSVGExportOptionsSVG propertiescompressedcoordinatePrecisioncssPropertiesdocumentEncodingDTDembedRasterImagesfontSubsettingfontTypeincludeFileInfoincludeVariablesAndDatasetsoptimizeForSVGViewerpreserveEditabilityslicessVGAutoKerningsVGTextOnPathtypename

    GradientGradient propertiesgradientStopsnameparenttypetypename

    Gradient methodsremove

    GradientColorGradientColor propertiesanglegradienthiliteAnglehiliteLengthlengthmatrixorigintypename

    GradientsGradients propertieslengthparenttypename

    Gradients methodsaddgetByNameindexremoveAll

    GradientStopGradientStop propertiescolormidPointparentrampPointtypename

    GradientStop methodsremove

    GradientStopsGradientStops propertieslengthparenttypename

    GradientStops methodsaddindexremoveAll

    GraphicStyleGraphicStyle propertiesnameparenttypename

    GraphicStyle methodsapplyToremove

    GraphicStylesGraphicStyles propertieslengthparenttypename

    GraphicStyles methodsgetByNameindexremoveAll

    GraphItemGraphItem propertiesartworkKnockoutblendingModecontentVariablecontrolBoundseditablegeometricBoundsheighthiddenisIsolatedlayerleftlockednameopacityparentpositionselectedslicedtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    GraphItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    GraphItemsGraphItems propertieslengthparenttypename

    GraphItems methodsgetByNameindexremoveAll

    GrayColorGrayColor propertiesgraytypename

    GroupItemGroupItem propertiesartworkKnockoutblendingModeclippedcompoundPathItemscontrolBoundseditablegeometricBoundsgraphItemsgroupItemsheighthiddenisIsolatedlayerleftlegacyTextItemslockedmeshItemsnameopacitypageItemsparentpathItemsplacedItemspluginItemspositionrasterItemsselectedslicedsymbolItemstagstextFramestoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    GroupItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    GroupItemsGroupItems propertieslengthparenttypename

    GroupItems methodsaddcreateFromFilegetByNameindexremoveAll

    IllustratorSaveOptionsIllustratorSaveOptions propertiescompatibilitycompressedembedICCProfileembedLinkedFilesflattenOutputfontSubsetThresholdoverprintpdfCompatibletypename

    InkInk propertiesinkInfonametypename

    InkInfoInkInfo propertiesanglecustomColordensitydotShapefrequencykindprintingStatustrappingtrappingOrdertypename

    InsertionPointInsertionPointsInsertionPoints propertieslengthparenttypename

    InsertionPoints methodsindex

    LabColorLabColor propertiesabltypename

    LayerLayer propertiesartworkKnockoutblendingModecolorcompoundPathItemsdimPlacedImagesgraphItemsgroupItemshasSelectedArtworkisIsolatedlayerslegacyTextItemslockedmeshItemsnameopacitypageItemsparentpathItemsplacedItemspluginItemspreviewprintablerasterItemsslicedsymbolItemstextFramestypenamevisiblezOrderPosition

    Layer methodsmoveremovezOrder

    LayersLayers propertieslengthparenttypename

    Layers methodsaddgetByNameindexremoveAll

    LegacyTextItemLegacyTextItem propertiesartworkKnockoutblendingModecontrolBoundsconvertededitablegeometricBoundsheighthiddenisIsolatedlayerleftlockednameopacityparentpositionselectedslicedtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    LegacyTextItem methodsconvertToNativeduplicatemoveremoveresizerotatetransformtranslatezOrder

    LegacyTextItemsLegacyTextItems propertieslengthparenttypename

    LegacyTextItems methodsconvertToNativegetByNameindexremoveAll

    LinesLines propertieslengthparenttypename

    Lines methodsindexremoveAll

    MatrixMatrix propertiesmValueAmValueBmValueCmValueDmValueTXmValueTYtypename

    MeshItemMeshItem propertiesartworkKnockoutblendingModecontrolBoundseditablegeometricBoundsheighthiddenisIsolatedlayerleftlockednameopacityparentpositionselectedslicedtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    MeshItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    MeshItemsMeshItems propertieslengthparenttypename

    MeshItems methodsgetByNameindexremoveAll

    NoColorNoColor propertiestypename

    OpenOptionsOpenOptions propertiestypenameupdateLegacyText

    PageItemsPageItems propertieslengthparenttypename

    PageItems methodsgetByNameindexremoveAll

    PaperPaper propertiesnamepaperInfotypename

    PaperInfoPaperInfo propertiescustomPaperheightimageableAreatypenamewidth

    ParagraphAttributesParagraphAttributes propertiesautoLeadingAmountbunriKinshiburasagariTypedesiredGlyphScalingdesiredLetterSpacingdesiredWordSpacingeveryLineComposerfirstLineIndenthyphenateCapitalizedWordshyphenationhyphenationPreferencehyphenationZonejustificationkinsokukinsokuOrderkurikaeshiMojiShorileadingTypeleftIndentmaximumConsecutiveHyphensmaximumGlyphScalingmaximumLetterSpacingmaximumWordSpacingminimumAfterHyphenminimumBeforeHyphenminimumGlyphScalingminimumHyphenatedWordSizeminimumLetterSpacingminimumWordSpacingmojikumiparentrightIndentromanHangingsingleWordJustificationspaceAfterspaceBeforetabStopstypename

    ParagraphsParagraphs propertieslengthparenttypename

    Paragraphs methodsaddaddBeforeindexremoveAll

    ParagraphStyleParagraphStyle propertiescharacterAttributesnameparagraphAttributesparenttypename

    ParagraphStyle methodsapplyToremove

    ParagraphStylesParagraphStyles propertieslengthparenttypename

    ParagraphStyles methodsaddgetByNameindexremoveAll

    PathItemPathItem propertiesareaartworkKnockoutblendingModeclippingclosedcontrolBoundseditableevenoddfillColorfilledfillOverprintgeometricBoundsguidesheighthiddenisIsolatedlayerleftlockednamenoteopacityparentpathPointspolaritypositionresolutionselectedselectedPathPointsslicedstrokeCapstrokeColorstrokedstrokeDashesstrokeDashOffsetstrokeJoinstrokeMiterLimitstrokeOverprintstrokeWidthtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    PathItem methodsduplicatemoveremoveresizerotatesetEntirePathtransformtranslatezOrder

    PathItemsPathItems propertieslengthparenttypename

    PathItems methodsaddellipsegetByNameindexpolygonrectangleremoveAllroundedRectanglestar

    PathPointPathPoint propertiesanchorleftDirectionparentpointTyperightDirectionselectedtypename

    PathPoint methodsremove

    PathPointsPathPoints propertieslengthparenttypename

    PathPoints methodsaddindexremoveAll

    PatternPattern propertiesnameparenttypename

    Pattern methodsremovetoString

    PatternsPatterns propertieslengthparenttypename

    Patterns methodsaddgetByNameindexremoveAll

    PatternColorPatternColor propertiesmatrixpatternreflectreflectAnglerotationscaleFactorshearAngleshearAxisshiftAngleshiftDistancetypename

    PDFFileOptionsPDFFileOptions propertiespageToOpenparentpDFCropToBoxtypename

    PDFSaveOptionsPDFSaveOptions propertiesacrobatLayersbleedLinkbleedOffsetRectcolorBarscolorCompressioncolorConversionIDcolorDestinationIDcolorDownsamplingcolorDownsamplingImageThresholdcolorDownsamplingMethodcolorProfileIDcolorTileSizecompatibilitycompressArtdocumentPasswordenableAccessenableCopyenableCopyAccessenablePlainTextflattenerOptionsflattenerPresetfontSubsetThresholdgenerateThumbnailsgrayscaleCompressiongrayscaleDownsamplinggrayscaleDownsamplingImageThresholdgrayscaleDownsamplingMethodgrayscaleTileSizemonochromeCompressionmonochromeDownsamplingmonochromeDownsamplingImageThresholdmonochromeDownsamplingMethodoffsetoptimizationoutputConditionoutputConditionIDpageInformationpageMarksTypepDFAllowPrintingpDFChangesAllowedpDFPresetpDFXStandardpDFXStandardDescriptionpermissionPasswordpreserveEditabilityprinterResolutionregistrationMarksrequireDocumentPasswordrequirePermissionPasswordtrappedtrimMarkstrimMarkWeighttypenameviewAfterSaving

    PhotoshopFileOptionsPhotoshopFileOptions propertiesparentpixelAspectRatioCorrectionpreserveImageMapspreserveLayerspreserveSlicestypename

    PlacedItemPlacedItem propertiesartworkKnockoutblendingModeboundingBoxcontentVariablecontrolBoundseditablefilegeometricBoundsheighthiddenisIsolatedlayerleftlockedmatrixnameopacityparentpositionselectedslicedtagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    PlacedItem methodsduplicateembedmoveremoveresizerotatetracetransformtranslatezOrder

    PlacedItemsPlacedItems propertieslengthparenttypename

    PlacedItems methodsaddgetByNameindexremoveAll

    PluginItemPluginItem propertiesartworkKnockoutblendingModecontrolBoundseditablegeometricBoundsheighthiddenisIsolatedisTracinglayerleftlockednameopacityparentpositionselectedslicedtagstoptracingtypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    PluginItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    PluginItemsPluginItems propertieslengthparenttypename

    PluginItems methodsgetByNameindexremoveAll

    PPDFilePPDFile propertiesnamepPDInfotypename

    PPDFileInfoPPDFileInfo propertieslanguageLevelPPDFilePathscreenListscreenSpotFunctionListtypename

    PreferencesPreferences propertiesparentPDFFileOptionsphotoshopFileOptionstypename

    PrintColorManagementOptionsPrintColorManagementOptions propertiescolorProfileModeintentnametypename

    PrintColorSeparationOptionsPrintColorSeparationOptions propertiescolorSeparationModeconvertSpotColorsinkListoverPrintBlacktypename

    PrintCoordinateOptionsPrintCoordinateOptions propertiesemulsionfitToPagehorizontalScaleorientationpositiontilingtypenameverticalScale

    PrinterPrinter propertiesnameprinterInfotypename

    PrinterInfoPrinterInfo propertiesbinaryPrintingSupportcolorSupportcustomPaperSupportcustomPaperTransverseSupportdeviceResolutioninRIPSeparationSupportmaxDeviceResolutionmaxPaperHeightmaxPaperHeightOffsetmaxPaperWidthmaxPaperWidthOffsetminPaperHeightminPaperHeightOffsetminPaperWidthminPaperWidthOffsetpaperSizespostScriptLevelprinterTypetypename

    PrintFlattenerOptionsPrintFlattenerOptions propertiesclipComplexRegionsconvertStrokesToOutlinesconvertTextToOutlinesflatteningBalancegradientResolutionoverprintrasterizationResolutiontypename

    PrintFontOptionsPrintFontOptions propertiesdownloadFontsfontSubstitutiontypename

    PrintJobOptionsPrintJobOptions propertiesbitmapResolutioncollatecopiesdesignationfilenameprintAreaprintAsBitmapreversePagestypename

    PrintOptionsPrintOptions propertiescolorManagementOptionscolorSeparationOptionscoordinateOptionsflattenerOptionsflattenerPresetfontOptionsjobOptionspageMarksOptionspaperOptionspostScriptOptionsPPDNameprinterNameprintPresettypename

    PrintPageMarksOptionsPrintPageMarksOptions propertiesbleedOffsetRectcolorBarsmarksOffsetRectpageInfoMarkspageMarksTyperegistrationMarkstrimMarkstrimMarksWeighttypename

    PrintPaperOptionsPrintPaperOptions propertiesheightnameoffsettransversetypenamewidth

    PrintPostScriptOptionsPrintPostScriptOptions propertiesbinaryPrintingcompatibleShadingforceContinuousToneimageCompressionnegativePrintingpostScriptLevelshadingResolutiontypename

    RasterItemRasterItem propertiesartworkKnockoutblendingModeboundingBoxcontentVariablecontrolBoundseditableembeddedfilegeometricBoundsheighthiddenimageColorSpaceisIsolatedlayerleftlockedmatrixnameopacityparentpositionselectedslicedstatustagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    RasterItem methodscolorizeduplicatemoveremoveresizerotatetracetransformtranslatezOrder

    RasterItemsRasterItems propertieslengthparenttypename

    RasterItems methodsaddgetByNameindexremoveAll

    RGBColorRGBColor propertiesbluegreenredtypename

    ScreenScreen propertiesnamescreenInfotypename

    ScreenInfoScreenInfo propertiesangledefaultScreenfrequencytypename

    ScreenSpotFunctionScreenSpotFunction propertiesnamespotFunctiontypename

    SpotSpot propertiescolorcolorTypenameparenttypename

    Spot methodsremove

    SpotColorSpotColor propertiesspottinttypename

    SpotsSpots propertieslengthparenttypename

    Spots methodsaddgetByNameindexremoveAll

    StoryStory propertiescharactersinsertionPointslengthlinesparagraphsparenttextFramestextRangetextRangestextSelectiontypenamewords

    StoriesStories propertieslengthparenttypename

    Stories methodsindex

    SwatchSwatch propertiescolornameparenttypename

    Swatch methodsremove

    SwatchesSwatches propertieslengthparenttypename

    Swatches methodsaddgetByNameindexremoveAll

    SymbolSymbol propertiesnameparenttypename

    Symbol methodsduplicateremove

    SymbolsSymbols propertieslengthparenttypename

    Symbols methodsaddindexgetByNameremoveAll

    SymbolItemSymbolItem propertiesartworkKnockoutblendingModecontrolBoundseditablegeometricBoundsheighthiddenisIsolatedlayerleftlockednameopacityparentpositionselectedslicedsymboltagstoptypenameuRLvisibilityVariablevisibleBoundswidthwrapInsidewrapOffsetwrappedzOrderPosition

    SymbolItem methodsduplicatemoveremoveresizerotatetransformtranslatezOrder

    SymbolItemsSymbolItems propertieslengthparenttypename

    SymbolItems methodsaddgetByNameindexremoveAll

    TabStopInfoTabStopInfo propertiesalignmentdecimalCharacterleaderpositiontypename

    TagTag propertiesnameparenttypenamevalue

    Tag methodsremove

    TagsTags propertieslengthparenttypename

    Tags methodsaddgetByNameindexremoveAll

    TextFontTextFont propertiesfamilynameparentstyletypename

    TextFontsTextFonts propertieslengthparenttypename

    TextFonts methodsindexgetByName

    TextFrameTextFrame propertiesanchorartworkKnockoutblendingModecharacterscolumnCountcolumnGuttercontentscontentVariablecontrolBoundseditableendTValueflowLinksHorizontallygeometricBoundsheighthiddeninsertionPointsisIsolatedkindlayerleftlineslockedmatrixnamenextFrameopacityopticalAlignmentorientationparagraphsparentpositionpreviousFramerowCountrowGutterselectedslicedspacingstartTValuestorytagstextPathtextRangetextRangestextSelectiontoptypenameuRLvisibilityVariablevisibleBoundswidthwordswrapInsidewrapOffsetwrappedzOrderPosition

    TextFrame methodscreateOutlineduplicatemoveremoveresizerotatetransformtranslatezOrder

    TextFramesTextFrames propertieslengthparenttypename

    TextFrames methodsaddareaTextgetByNameindexpathTextpointTextremoveAll

    TextPathTextPath propertiesareablendingModeclippingeditableevenoddfillColorfilledfillOverprintguidesheightleftnoteopacityparentpathPointspolaritypositionresolutionselectedPathPointsstrokeCapstrokeColorstrokedstrokeDashesstrokeDashOffsetstrokeJoinstrokeMiterLimitstrokeOverprintstrokeWidthtoptypenamewidth

    TextPath methodssetEntirePath

    TextRangeTextRange propertiescharacterAttributescharacterOffsetcharacterscharacterStylescontentsinsertionPointskerninglengthlinesparagraphAttributesparagraphsparagraphStylesparentstorytextRangestextSelectiontypenamewords

    TextRange methodschangeCaseTodeSelectduplicatemoveremoveselect

    TextRangesTextRanges propertieslengthparenttypename

    TextRanges methodsindexremoveAll

    TracingObjectTracingObject propertiesanchorCountareaCountimageResolutionparentpathCountsourceArttracingOptionstypenameusedColorCount

    TracingObject methodsexpandTracingreleaseTracing

    TracingOptionsTracingOptions propertiescornerAnglefillslivePaintOutputmaxColorsmaxStrokeWeightminAreaminStrokeLengthoutputToSwatchespaletteparentpathFittingpreprocessBlurpresetresampleresampleResolutionstrokesthresholdtracingModetypenameviewRasterviewVector

    TracingOptions methodsloadFromPresetstoreToPreset

    VariableVariable propertieskindnamepageItemsparenttypename

    Variable methodsremove

    VariablesVariables propertieslengthparenttypename

    Variables methodsaddgetByNameindexremoveAll

    ViewView propertiesboundscenterPointparentscreenModetypenamezoom

    ViewsViews propertieslengthparenttypename

    Views methodsindex

    WordsWords propertieslengthparenttypename

    Words methodsaddaddBeforeindexremoveAll

    File and Folder Object ReferenceOverviewFile ObjectFile object constructorsFile class propertiesfs

    File class functionsdecodeencodeisEncodingAvailableopenDialogsaveDialog

    File object propertiesabsoluteURIaliascreatedcreatorencodingeoferrorexistsfsNamehiddenlengthlineFeedmodifiednameparentpathreadonlyrelativeURItype

    File object functionsclosecopycreateAliasexecutegetRelativeURIopenopenDlgreadreadchreadlnremoverenameresolvesaveDlgseektellwritewriteln

    Folder ObjectFolder object constructorsFolder class propertiesappDatacommonFilescurrentfsmyDocumentsstartupsystemtemptrashuserData

    Folder class functionsdecodeencodeisEncodingAvailableselectDialog

    Folder object propertiesabsoluteURIaliascreatederrorexistsfsNamemodifiednameparentpathrelativeURI

    Folder object functionscreateexecutegetFilesgetRelativeURIremoverenameresolveselectDlg

    File and Folder Error MessagesFile and Folder Supported Encoding NamesAdditional encodings

    Scripting ConstantsAlternateGlyphsFormAutoKernTypeAutoLeadingTypeBaselineDirectionTypeBlendAnimationTypeBlendModesBurasagariTypeEnumCaseChangeTypeColorConversionColorDestinationColorDitherMethodColorModelColorProfileColorReductionMethodColorTypeCompatibilityCompressionQualityCropOptionsDocumentColorSpaceDocumentTypeDownsampleMethodElementPlacementEPSPostScriptLevelEnumEPSPreviewExportTypeFigureStyleTypeFlashExportStyleFlashImageFormatFlashJPEGMethodFontBaselineOptionFontCapsOptionFontOpenTypePositionOptionFontSubstitutionPolicyGradientTypeImageColorSpaceInkPrintStatusInkTypeJavaScriptExecutionModeJustificationKinsokuOrderEnumKnockoutStateLanguageTypeLayerOrderTypeMonochromeCompressionOutputFlatteningPageMarksTypesPathPointSelectionPDFBoxTypePDFChangesAllowedEnumPDFCompatibilityPDFOverprintPDFPrintAllowedEnumPDFTrimMarkWeightPDFXStandardPhotoshopCompatibilityPointTypePolarityValuesPostScriptImageCompressionTypePrintArtworkDesignationPrintColorIntentPrintColorProfilePrintColorSeparationModePrinterColorModePrinterPostScriptLevelEnumPrinterTypeEnumPrintFontDownloadModePrintingBoundsPrintOrientationPrintPositionPrintTilingRasterLinkStateRulerUnitsSaveOptionsScreenModeStrokeCapStrokeJoinStyleRunAlignmentTypeSVGCSSPropertyLocationSVGDocumentEncodingSVGDTDVersionSVGFontSubsettingSVGFontTypeTabStopAlignmentTextOrientationTextTypeTracingModeTypeTransformationTrappingTypeUserInteractionLevelVariableKindViewRasterTypeViewVectorTypeWariChuJustificationTypeZOrderMethod

    ExtendScript Tools and FeaturesThe ExtendScript ToolkitConfiguring the Toolkit windowSelecting a debugging targetSelecting scriptsTracking dataThe JavaScript consoleThe call stackThe Script EditorMouse navigation and selectionKeyboard navigation and selectionSyntax checking

    Debugging in the ToolkitEvaluation in help tipsControlling code executionVisual indication of execution statesSetting breakpoints

    Profiling

    Dollar ($) ObjectDollar ($) object propertiesbuildbuildDateerrorflagsgloballevellocalelocalizememCacheobjectsosscreensstrictversion

    Dollar ($) object functionsaboutbpclearbpgcgetenvlistsetbpsleepsummarywritewritelnObject statistics

    ExtendScript Reflection InterfaceReflection ObjectReflection object propertiesdescriptionhelpmethodsnameproperties

    Reflection object functionsfind

    ReflectionInfo ObjectReflectionInfo object propertiesargumentsdataTypedefaultValuedescriptionhelpisCollectionmaxminnametype

    Localizing ExtendScript StringsVariable values in localized stringsEnabling automatic localizationLocale namesTesting localizationGlobal localize functionlocalize

    User Notification Helper FunctionsGlobal alert functionalert

    Global confirm functionconfirm

    Global prompt functionprompt

    Specifying Measurement ValuesUnitValue ObjectUnitValue object constructorUnitValue object propertiesbaseUnittypevalue

    UnitValue object functionsasconvert

    Converting pixel and percentage valuesComputing with unit values

    Modular Programming SupportPreprocessor directives#engine name#include file#includepath path#script name#strict on#target name

    Importing and exporting between scripts

    Operator OverloadingApplication and Namespace SpecifiersApplication specifiersNamespace specifiers

    Script Locations and Checking Application Installation

    Index

Recommended

View more >