Macromedia Illustrator - 10.0 User Guide
A
DOBE
I
LLUSTRATOR
S
CRIPTING
G
® 10
UIDE
Adobe Developer Support
345 Park Avenue
San Jose, CA 95110-2704
408-536-9000
FaxYI: 206-628-5737
ada@adobe.com
http://partners.adobe.com
Europe:
PO Box 12356
Edinburgh EH11 4GJ
United Kingdom
+44.131.458.6800
Fax: +44.131.458 6801
euroADA@adobe.com
ii
Adobe Illustrator 10 Scripting Guide
Copyright 2000 Adobe Systems Incorporated.
All Rights Reserved.
The information in this document 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 this document. 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.
Adobe, Adobe Aft er Effects, Adobe PhotoDeluxe, A dobe Premier e, Adobe Photoshop,
Adobe Illustrator, Adobe InDesign, Adobe Type Manager, ATM and PostScript are
trademarks of Adobe Systems Inc o rporated that ma y be registered in certain jurisdictions.
Macintosh and Apple are registered trademarks, and Mac OS and AppleScript are
trademarks of Apple Computer, Inc. Microsoft, Visual Basic, Windows, Windows 95,
Windows 98, and Windows NT are registered trademarks of Microsoft Corporation. All
other products or name brands are trademarks of their respective holders.
Table of Contents
Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
What is scripting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
Why use scripting? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12
What about actions?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Mac OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Chapter 2: Scripting Basics. . . . . . . . . . . . . . . . . . . . . . . . . . 15
Object model concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
Object classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Object inheritance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Object elements or collections . . . . . . . . . . . . . . . . . . . . . . . . .17
Object references. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Scripting concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
About long script lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Commands and methods . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Conditional statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . .23
Control structures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Handlers and subroutines. . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Testing and troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
About error handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
iii
Table of Contentsiv
Chapter 3: Scripting Illustrator . . . . . . . . . . . . . . . . . . . . . . . . 31
Looking at Illustrator’s objects and commands . . . . . . . . . . . . . . . . . . .31
AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Visual Basic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
The application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Your first Illustrator script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Creating an AppleScript script . . . . . . . . . . . . . . . . . . . . . . . . .34
Creating a Visual Basic script. . . . . . . . . . . . . . . . . . . . . . . . . .35
VBScript. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Adding features to “Hello World” . . . . . . . . . . . . . . . . . . . . . . . . . .38
Measurement units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Unit conversion to points . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Fixed points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Zero point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Fixed rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
Page item positioning and dimensions . . . . . . . . . . . . . . . . . . . . .43
Object references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Object references in AppleScript . . . . . . . . . . . . . . . . . . . . . . . .44
Object references in Visual Basic. . . . . . . . . . . . . . . . . . . . . . . .45
Object containment: document vs. layer . . . . . . . . . . . . . . . . . . . . . .45
Working with selections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Working with paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Working with color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Working with symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Working with symbol items . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Working with text art. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Transformation matrices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Using a matrix in an AppleScript script . . . . . . . . . . . . . . . . . . . . .52
Using a matrix in a Visual Basic script . . . . . . . . . . . . . . . . . . . . .52
Working with variables and datasets . . . . . . . . . . . . . . . . . . . . . . . .53
Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Launching and quitting Illustrator from a script . . . . . . . . . . . . . . . . . . .54
Launching and quitting from AppleScript . . . . . . . . . . . . . . . . . . . .54
Launching and quitting from Visual Basic. . . . . . . . . . . . . . . . . . . .54
Some objects that cannot be created by a script . . . . . . . . . . . . . . . . . .54
User Interaction Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Visual Basic and JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . .55
The Scripts menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Adobe Illustrator 10 Scripting Guide Table of Contents v
Supported scripting languages . . . . . . . . . . . . . . . . . . . . . . . . .56
Script files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Installing scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Executing other scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Chapter 4: AppleScript Reference . . . . . . . . . . . . . . . . . . . . . . 59
About the script examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Illustrator’s object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
art style, art styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
brush, brushes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
character, characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
CMYK color info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
compound path item, compound path items. . . . . . . . . . . . . . . . . . . . .77
dataset, datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
document, documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
ellipse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
EPS save options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
fixed point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
fixed rectangle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Flash export options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
GIF export options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
gradient, gradients. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
gradient color info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
gradient stop, gradient stops . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
gradient stop info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
graph item, graph items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
gray color info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
group item, group items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Illustrator save options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
insertion point, insertion points . . . . . . . . . . . . . . . . . . . . . . . . . . 128
JPEG export options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
layer, layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
line, lines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
mesh item, mesh items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
page item, page items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
paragraph, paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
path item, path items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
path point, path points. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Table of Contentsvi
path point info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
pattern, patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
pattern color info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
PDF open options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
PDF save options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Photoshop options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Photoshop export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
placed item, placed items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
plugin item, plugin items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
PNG24 export options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
PNG8 export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
raster item, raster items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
rectangle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
RGB color info. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
rounded rectangle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
spot, spots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
spot color info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
star. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
SVG export options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
swatch, swatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
symbol, symbols. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
symbol item, symbol items . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
tab stop info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
tag, tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
text art item, text art items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
text face, text faces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
text path, text paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
variable, variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
view, views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Command reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
activate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
apply . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
colorize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
concatenate matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
concatenate rotation matrix. . . . . . . . . . . . . . . . . . . . . . . . . . 242
concatenate scale matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
concatenate translation matrix . . . . . . . . . . . . . . . . . . . . . . . . 243
convert to paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
Adobe Illustrator 10 Scripting Guide Table of Contents vii
copy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244
count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
cut. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246
delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
do javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
do script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
equal matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
exists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
export variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
get identity matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
get rotation matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
get scale matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
get translation matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
end tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
invert matrix. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
make . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
move . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
open. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
redraw. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
rotate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
save. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
singular matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
translate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
update. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Chapter 5: Visual Basic Reference . . . . . . . . . . . . . . . . . . . . . .271
About the script examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Illustrator’s object model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Referencing and creating objects in Visual Basic . . . . . . . . . . . . . . . . . 274
Syntax differences between Sub and Function methods . . . . . . . . . . . 275
Table of Contentsviii
Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
ArtStyle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
ArtStyles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Brush . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Brushes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288
Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
CMYKColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
CompoundPathItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
CompoundPathItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
DataSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
DataSets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
EPSSaveOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
ExportOptionsFlash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
ExportOptionsGIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
ExportOptionsPhotoshop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
ExportOptionsJPEG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
ExportOptionsPNG24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
ExportOptionsPNG8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
ExportOptionsSVG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Gradient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Gradients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
GradientColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
GradientStop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
GradientStops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
GraphItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
GraphItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
GrayColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
GroupItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
GroupItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
IllustratorSaveOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
Layer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Matrix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
MeshItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
MeshItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
PageItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
PageItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Paragraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Adobe Illustrator 10 Scripting Guide Table of Contents ix
Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
PathItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
PathItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
PathPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
PathPoints. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404
PatternColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
PDFOpenOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
PDFSaveOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
PhotoshopFileOptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
PlacedItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412
PlacedItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
PluginItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
PluginItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
RasterItem. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
RasterItems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
RGBColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
Spot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433
Spots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435
SpotColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436
Swatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Swatches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Symbol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
SymbolItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
SymbolItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
TextArtItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
TextArtItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
TextFace. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459
TextFaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460
TextLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
TextLines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
TextPath. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
TextPaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
TextPath_PathItems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
TextRange. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Table of Contentsx
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Word. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Enumerations reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Chapter : Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . .493
AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Internet resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Adobe Systems, Inc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Visual Basic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
1
Introduction
Welcome to scripting, arguably the most exciting new feature of Illustrator. No other
feature, new or old, can save you as much time, effort, and money as scripting.
About this manual
This manual provides an introduction to scripting Adobe Illustrator 10 on Mac OS and
Windows. We realize that not every Illustrator user will be familiar with programming
terms, concepts, and techniques, so we’ve included Chapter 2, “Scripting Basics,” which
contains introductory information that should help get you started with scripting. If you’re
an experienced AppleScript scripter or Visual Basic programmer, you will probably want
to skip to Chapter 3 to get the specifics on scripting Illustrator.
This manual consists of the following chapters:
1. An introduction to scripting.
2. The basics of each platform’s scripting language: AppleScript in Mac OS and
Visual Basic in Windows. If you are new to scripting, be sure to read this
chapter. Beginners are heartily encouraged to consult the Bibliograph y for books
on AppleScript and Visual Basic.
3. A brief introduction to the specifics of scripting Illustrator. Concepts and
approaches specific to the application are covered here, such as measurement
units, matrices, and color models.
4. The Illustrator AppleScript Reference. Here you’ll find details and examples for
every object and command in Illustrator’s AppleScript dictionary.
5. The Illustrator Visual Basic Reference. Details and examples are provided for
every class in Illustrator’s Visual Basic type library.
6. A bibliography of helpful resources for learning more about scripting.
11
What is scripting? Introduction12
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 Illustrator’s 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 Illustrator’s built-in transformation
matrix functions to stretch, scale and distort a series of objects. Without scripting, you’ll
likely miss out on the creative potential of such labor-intensive techniques.
Scripting isn’t just for computer programmers—it’ s f or e v erybody. You don’t need a degree
in computer science or mathematics to write scripts that can automate a wide variety of
common tasks. If you can read this text, you can write scripts.
Why use scripting?
Graphic design is a field characterized by creativity, but aspects of the actual work of
illustration and page layout are anything but creative. When you think about the work that
you do, chances are good you’ll find that you spend most of your time doing the same or
similar production tasks, over and over again. In fact, you’ll probably notice that the time
you spend placing and replacing images, correcting errors in text, and preparing files for
printing at an imagesetting service provider often reduce the time you have available for
doing creative work.
Wouldn’t it be great if you had an assistant—one that wouldn’t mind doing some or all of
the boring, repetitive tasks for you? With that kind of help, you’d have more time to
concentrate on the creative aspects of your work.
With a small investment of time, Illustrator scripting can be the assistant you need. You
can start with short, simple scripts that save you a few seconds every day, and move on
to scripts that work all night while you’re sleeping.
Adobe Illustrator 10 Scripting Guide What about actions? 13
Think about your work—is there a repetitive task that’s driving you crazy? If so, you’ve
identified a candidate for a script. What are the steps involved in performing the task?
What are the conditions in which you need to do the task? Once you understand the
process you go through to perform the task, you’ll be ready to turn it into a script.
What about actions?
Illustrator actions are different from scripts. An Illustrator action is a series of tasks you
have recorded while using the application—menu choices, tool choices, object selection,
and other commands. When you “play” an action, Illustrator performs all of the recorded
commands.
You record, play, edit and delete actions using Illustrator’s 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 an y confusion about
the difference between actions and scripting. Actions and scripts are both ways of
automating repetitive tasks, but the y work v ery differently. The following points summarize
the key differences.
• Actions use a program’s user interface to do their work. As an action runs, menu
choices are executed, objects are selected, and recorded paths are created. Scripts
do not use a program’s user interface to perform tasks, and can execute faster than
actions.
• Actions have very limited facilities for getting and responding to information. You
cannot add conditional logic to an action. Therefore, actions cannot make decisions
based on the current situation. Scripts are capable of getting information and making
decisions and calculations based on the information they receive from Illustrator.
•A script can execute an action, but actions cannot execute scripts.
System requirements
The language you use to write scripts depends on the operating system of the platform
you’re using: AppleScript for Mac OS; Visual Basic for Windows. While the two scripting
systems differ, the ways that they work with Illustrator are very similar. Each example
script shown in this manual will be shown in both systems. Make sure the scripting plug-in
is installed on your system before attempting to script Illustrator.
System requirements Introduction14
Mac OS
To write scripts on Mac OS, you must have Mac OS v ersion 8.6 or later . You will also need
AppleScript and a script editor installed. AppleScript and the Script Editor application
from Apple come installed on all supported versions of Mac OS. The default location for
the Script Editor application is the Apple Extras folder. In the unlikely event that these
items are not installed on your system, reinstall them from your original system software
CD-ROM.
As your scripts become more complex, you may find the need for debugging and
productivity features not found in Script Editor. Third-party script editors, such as Script
Debugger (from Late Night Software, http://www.latenightsw.com) or Scripter (from Main
Event Software, http://www.mainevent.com) provide additional features that aid script
development.
If your script would benefit from a complete user interface, you might want to use
FaceSpan (http://www.facespan.com) or Real Basic (http://www.realsoftware.com)—
programs created in these development environments can have complete graphical user
interfaces as well as send AppleScript commands to Illustrator.
We use the Script Editor from Apple in this manual.
Windows
To use Illustrator scripting in Windows, you must have Windows 98, Windows NT 4.0, or
Windows 2000. You will also need the Microsoft Visual Basic dev elopment en vironment or
one of the applications that contain a Visual Basic editor. Many applications that support
the Visual Basic for Applications (VBA) language contain a built-in editor. Applications
that contain a built-in editor include: Microsoft Word, Microsoft Excel, and Visio. You can
use any Visual Basic editor to create your scripts.
As your scripts become more complex or require a user interface, you will find the need
for a complete development environment than one of the built-in editors. The Microsoft
Visual Basic development environment comes in a variety of package, all of which
provide everything you need to script Illustrator.
In this manual, we use the Microsoft Visual Basic development environment’s editor.
2
Scripting Basics
If you use Illustrator, then you work with documents and their contents. You create
documents, layers, colors, and design elements. If you do all of this, you’ve probably
gotten used to thinking of an Illustrator document as a series of objects.
Automating Illustrator with scripting uses the same object-oriented way of thinking. The
heart of a scriptable application is the object model. In Illustrator, the object model is
comprised of documents, layers, colors, and page items—objects that can appear in an
Illustrator document. Each type of object has its own special properties, and every object
in an Illustrator document has its own identity.
In this chapter, we’ll co v er the basic concepts of scripting f or both AppleScript on Mac OS
and Visual Basic on Windows. This brief introduction to the basic concepts and syntax of
each scripting language is by no means complete or exhaustive. The bibliography
contains references to more complete language guides for both scripting languages.
For detailed information on using your particular scripting system with Illustrator, see the
appropriate reference chapter later in this manual. Experienced scripters may want to
skip to those chapters now.
Object model concepts
The terminology of object oriented programming can be hard to understand, at first.
“Objects” belong to “classes” and have “properties” you manipulate using “commands”
(AppleScript) or “methods” (Visual Basic). What do these words mean in this context?
Here’s a way to think about objects and their properties. Imagine that you live in a house
that responds to your commands (you can think of this house as technologically
advanced, or magical, or both). The house is an object, and its properties might include
the number of rooms, the color of the exterior paint, or the date of its construction.
15
Object classes Object model concepts16
Your house can also contain other objects. Just lik e y our house can contain other objects,
the objects within the house can also contain a number of smaller objects. Each room, for
example, is an object in the house, while each window, door, or appliance is an object
inside of the room.
Each object can respond to various commands according to its capabilities. Windo ws and
doors, for example, can open or close—but the floor and ceiling cannot. Using scripting,
you can talk to each object directly, or you can talk to them as part of the house. You have
to be very specific, though—you can’t tell your house to open a window without telling it
which window you want to open. So windows, just like all other objects, need names or at
least a numbering system so you can refer to them specifically. “Tell the house to open
the north window of the living room,” you might say.
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 y ourself blue.” Because your door can respond to the command “paint,” you’ll
soon have a door of a different color.
Now let’ s apply this object model idea to Illustrator . The Illustrator application is the house,
its documents are the rooms, and the objects in your documents are the windows and
doors. You can tell Illustrator documents to add and remove objects. You can ask objects
to get or change their properties.
Object classes
Objects with the same properties and behaviors are grouped into “classes.” In the house
example, windows and doors belong to their own classes, since they have unique
properties, like number of panes for windows or the door style for doors. In Illustrator,
every type of graphic object—paths, text, meshes, etc.—belongs to its own class, each
with its own set of properties and behaviors. Properties such as
width
, and
height
, for example, are common to all
page items
visible bounds
.
,
Object inheritance
Object classes may also “inherit,” or share, the properties of a parent, or superclass.
When an class inherits properties, we call that class a child, or subclass of the class from
which it inherits properties. So in our house example , windo ws and doors are subclasses
of an openings class, since they are both openings in a house. In Illustrator,
items
page item
Classes will often have properties that aren’t shared with their superclass. In our house,
both a window and door inherit an opened property from the opening class, but a window
, for example, inherit geometric properties like
class.
width
and
height
path
from the
Adobe Illustrator 10 Scripting Guide Scripting concepts 17
has number of panes property which the opening class doesn’t. In Illustrator,
items
, for example, have the property
page item
stroke color
class.
which isn’t inherited from the
path
Object elements or collections
Object elements (AppleScript) or collections (Visual Basic) are objects contained within
other objects. For example, rooms are elements (or collections) of our house, contained
within the house object. In Illustrator, documents are elements of the application object,
and page items are elements of a document object.
Object references
The objects in your documents are arranged in a hierarchy like the house object—page
items are in layers, which are inside a document, which is inside Illustrator. When you
send a command to an Illustrator object, you need to make sure y ou send the message to
the right object. To do this, you identify objects by their position in the hierarchy. You
might, for example, write the following statement.
AppleScript
page item 1 of layer 1 of document 1
Visual Basic
Documents(1).Layers(1).PageItems(1)
When you identify an object in this fashion, you’re creating an
AppleScript and Visual Basic use diff erent wa ys of creating object references , but the idea
is the same—to give the script a way of finding the object you want to work with.
object reference
.
Scripting concepts
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 y ourself or f or 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.
About long script lines Scripting concepts18
AppleScript
To enter a single-line comment in an AppleScript, type “--” to the left of your description.
For multiple line comments, start your comment with the characters “(*” and end it with
“*)”.
-- this is a single-line comment
(* this is a
multiple line comment *)
Visual Basic
In Visual Basic, enter “'” (a single straight quote) to the left of the comment.
' This is a comment
About long script lines
In some cases, individual script lines are too long to print on a single line in this guide.
AppleScript
AppleScript uses the special character (¬) to show that the line continues to the next line .
This continuation character denotes a “soft return” in the script. You can enter this
character in the script editor by pressing Option-Return at the end of the line you wish to
continue.
Visual Basic
Visual Basic uses a special character (_) to show that the line continues to the next line.
This continuation character denotes a “soft return” in the script. You can enter this
character in the editor by pressing Shift--(dash) at the end of the line you wish to
continue.
Values
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.
Adobe Illustrator 10 Scripting Guide Scripting concepts 19
AppleScript
Value type: What it is: Example:
Boolean Logical true or false. true
Integer Whole numbers (no decimal
points). Integers can be
positive or negative.
Real A number which may contain
a decimal point.
String A series of text characters.
Strings appear inside
(straight) quotation marks.
List An ordered list of values. The
values of a list may be any
type.
Object reference A specific reference to an
object.
Record An unordered list of
properties, Each property is
identified by its label.
14
13.9972
"I am a string"
{10.0, 20.0, 30.0, 40.0}
document 1
{name: "you", index: 1}
Visual Basic
Value type: What it is: Example:
Boolean Logical true or false true
Long Whole numbers (no decimal
points). Longs can be positiv e
or negative.
Double A number which may contain
a decimal point.
String A series of text characters.
Strings appear inside
(straight) quotation marks.
Array A list of values. Arrays
contain a single value type
unless the type is defined as
Variant.
Object reference A specific reference to an
object.
User-defined A collection of elements
referenced by a key and
stored as a key-value pair.
14
13.9972
"I am a string"
Array(10.0, 20.0, 30.0, 40.0)
Application.Documents(1)
Var.name = "you"
Var.index = 1
Variables Scripting concepts20
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.
In AppleScript, it is not important to declare your variables before assigning values to
them. In Visual Basic, however, it is considered good form to declare all of your variables
before using them with the
to the variable, which helps us keep our scripts clear and readable. Memory is also used
more efficiently if variables are declared before use. If you start your scripts in Visual
Basic with the line
Option Explicit, you will be required to declare all variables
before assigning data to them.
Dim statement. Using the Dim statement assigns a value type
Visual Basic
Option Explicit
Dim thisNumber As Single
thisNumber = 10
Assigning values to variables is fairly simple, as shown below.
AppleScript
set thisNumber to 10
set thisString to "Hello, World!"
Visual Basic
thisNumber = 10
thisString = "Hello, World!"
Variables can also be used to store references to objects. In AppleScript, a reference is
returned when you create a new object in an Illustrator document. This returned ref erence
Adobe Illustrator 10 Scripting Guide Scripting concepts 21
points to the newly created object. Storing references in variables is just the same as
assigning any other value to the variable.
set thisLayer to make new layer at beginning of document 1
or you can fill the variable with a reference to an existing object:
set thisLayer to layer 1 of document 1
Visual Basic works similarly, however, there is an important distinction to note. If you are
assigning an object reference to a variable you must use the
example, to assign a variable as you create a layer, use
Set thisLayer = Illustrator.Documents(1).Layers.Add
Set command. For
Set:
or in reference to an existing layer, since it is also an object reference, use Set:
Set thisLayer = Illustrator.Documents(1).Layers(1)
If you are simply trying to assign a value to a variable in Visual Basic that is not an object
reference, do not use
set but simply use Visual Basic’s assignment operator, the equals
sign:
thisNumber = 12
Try to use descriptive names for your variables—something like firstPage or
corporateLogo, rather than x or c. While it will take a little more time to type the
longer names, using them will make your scripts much easier to read. The length of a
variable’s name has no effect on the execution speed of your script, so use descriptive
names. You can also give your variable names a standard prefix so that they’ll stand out
from the objects, commands, and keywords of your scripting system. Variable names
must be a single word, but you can use internal capitalization (such as myFirstPage)
or underscore characters (
my_first_page) to create more readable names. Variable
names cannot begin with a number, and they can’t contain punctuation or quotation
marks.
Properties
Both AppleScript and Visual Basic allow you to define properties for your scripts. Script
properties are much like variables, but with additional features and requirements specific
to each language. Since the meaning and usage of script properties differs so greatly
Operators Scripting concepts22
between AppleScript and Visual Basic, please consult the bibliography for appropriate
language references.
Operators
Operators perform calculations (addition, subtraction, multiplication, and division) on
variables or values and return a result. For example:
docWidth/2
would return 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
Would return the value true if docWidth is greater than docHeight, or false, if it
is not.
Some operators differ between AppleScript and Visual Basic. For example, AppleScript
uses the non-equality symbol (
the greater and less than symbols juxtaposed:
Both scripting systems use the ampersand (
strings.
"Pride " & "and Prejudice."
would return the string “Pride and Prejudice.”
≠, use Option- = from keyboard), while Visual Basic uses
<>.
&) as the concatenation operator to join two
Commands and methods
If objects are “nouns” and properties are “adjectives” in our scripting systems, then
commands (AppleScript) or methods (Visual Basic) are the “verbs”—they’re the parts of
the script that make things happen. The type of the object you’re working with determines
which methods you can use to manipulate it.
Adobe Illustrator 10 Scripting Guide Scripting concepts 23
AppleScript
In AppleScript, use the make command to create new objects, the set command to
assign object references to variables and to change object properties, and the
command to retrieve objects and their properties.
Visual Basic
In Visual Basic, use the Add method to create new objects, the Set statement to assign
object references to Visual Basic variables or properties, the assignment operator (
to retrieve and change object properties.
get
= )
Conditional statements
If you could speak to Illustrator in the course of a work session, you might say, “If the
selected object is a path, then set its stroke width to 12 points.” Conditional statements
make decisions—they give your scripts a way to evaluate something (the color of the
selected object, or the number of color swatches in the document, or the date) and then
act according to the result. Most conditional statements start with the word
scripting systems.
The following examples check the number of currently open documents. If no documents
are open, the scripts display a messages in a dialog box.
if in both
Control structures Scripting concepts24
AppleScript
tell application "Adobe Illustrator 10"
activate
set documentCount to count every document
if documentCount = 0 then
display dialog "No Illustrator documents are open!"
end if
end tell
Visual Basic
Private Sub Command1_Click()
Dim documentCount as long
Dim appRef As New Illustrator.Application
documentCount = appRef.Documents.Count
If documentCount = 0 then
MsgBox "No Illustrator documents are open!"
End If
End Sub
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.
Both AppleScript and Visual Basic have 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.
AppleScript
repeat with counter from 1 to 20
display dialog counter
end repeat
Visual Basic
For counter = 1 to 20
MsgBox counter
Next
A more complicated type of control structure includes conditional logic, so that it loops
while or until some condition is true or false.
Adobe Illustrator 10 Scripting Guide Scripting concepts 25
AppleScript
repeat while flag = false
set flag to (button returned of display dialog "Quit?") = "Cancel"
end repeat
repeat until flag = true
set flag to (button returned of display dialog "Quit?") = "OK"
end repeat
Visual Basic
Do While flag = false
flag = (MsgBox ("Quit?", vbOKCancel)) = vbCancel
loop
Do Until flag = true
flag = (MsgBox ("Quit?", vbOKCancel)) = vbOK
loop
Handlers and subroutines
Handlers (in AppleScript) or subroutines (in Visual Basic) are scripting modules you can
refer to from within your script. Handlers and subroutines are ways to re-use parts of
scripts. Typically, you send one or more values to a handler (or subroutine), and it returns
one or more values. Handlers (and subroutines) can be used for performing conversions
from one measurement system to another, or f or calculating the geometric center point of
an object from its geometric bounds.
There’s nothing special about the code used in subroutines and handlers—they are
simply conveniences that save you from having to type the same lines of code over and
over again in your script. If you find yourself typing or pasting the same lines of code into
several different places in a script, you’ve identified a good candidate for a subroutine or
handler.
Handlers and subroutines Scripting concepts26
AppleScript
-- Calculate the geometric center of a selected art item
-- Assumes you have a single art item selected
tell application "Adobe Illustrator 10"
-- Get the selection from the current document
set selectedItems to selection
(* Make sure there is a selected item, and that the selection is not
text *)
if selectedItems ≠ {} and class of selectedItems ≠ text then
-- Get the first item from the list and get it bounds
set firstItem to item 1 of selectedItems
set itemBounds to geometric bounds of firstItem
end if
end tell
set itemCenter to GetItemCenter(itemBounds)
display dialog "Center x:" & item 1 of itemCenter & ", y:" & item 2 of
itemCenter
-- This handler finds the center of an item given its bounds
on GetItemCenter(itemBounds)
-- Assign coordinates from the bounds to individual variables
set {itemLeft, itemTop, itemRight, itemBottom} to itemBounds
-- Calculate the center position
set xCenter to (itemLeft + itemRight) / 2
set yCenter to (itemTop + itemBottom) / 2
return {xCenter, yCenter}
end GetItemCenter
Visual Basic
Private Sub Command1_Click()
' Calculate the geometric center of a selected art item
' Assumes you have a single art item selected
Dim appRef As New Illustrator.Application
Dim selectedObjects As Variant
Dim objectBounds As Variant
Dim objectCenter As Variant
If appRef.Documents.Count > 0 Then
Adobe Illustrator 10 Scripting Guide Testing and troubleshooting 27
selectedObjects = appRef.Documents(1).Selection
If TypeName(selectedObjects) = "Variant()" Then
objectBounds = selectedObjects(0).GeometricBounds
objectCenter = GetItemCenter(objectBounds)
MsgBox ("Center x:" & objectCenter(0) & ", y:" &
objectCenter(1))
End If
End If
End Sub
' The following lines define the function
Function GetItemCenter(sourceBounds As Variant) As Variant
Dim left As Single
Dim top As Single
Dim right As Single
Dim bottom As Single
Dim xCenter As Single
Dim yCenter As Single
left = sourceBounds(0)
top = sourceBounds(1)
right = sourceBounds(2)
bottom = sourceBounds(3)
xCenter = (left + right) / 2
yCenter = (top + bottom) / 2
GetItemCenter = Array(xCenter, yCenter)
End Function
Testing and troubleshooting
Both scripting environments provide tools for monitoring the progress of your script while
it is running—which make it easier for you to track down any problems your script might
be encountering or causing.
AppleScript
While the basic syntax of your script will be checked when compiled, it is possible to
create and compile scripts in AppleScript that will not run properly. The Script Editor
doesn’t have extensive debugging tools, but it does have the an Event Log window.
Handlers and subroutines Testing and troubleshooting28
To watch the commands your script sends and the results it receives, choose Controls >
Open Event Log. The Script Editor displays the Event Log window. Check the Show
Events and Show Ev ents Results options at the top of the Event Log windo w and then run
your script. As the script executes, you’ll see the commands sent to Illustrator, and
Illustrator’s responses.
In addition, the Result window (choose Controls > Show Result) will display the value
from the last script statement evaluated. Third-party editors offer additional debugging
features.
Visual Basic
In Visual Basic, you can stop your script at any point, or step through your script one line
at a time. To stop your script at a particular line, select that line in your script and choose
Adobe Illustrator 10 Scripting Guide About error handling 29
Debug > Toggle Breakpoint. When you run the script, Visual Basic will stop at the
breakpoint you hav e set. Choose Debug > Step Into (or press F8) to execute the ne xt line
of your script, or choose Run > Start (or press F5) to continue normal execution of the
script. You can also observe the values of variables defined in your script using the Watch
window—a very valuable tool for debugging your scripts. To view a variable in the Watch
window, select the variable and choose Debug > Quick Watch. Visual Basic displays the
Quick Watch dialog box. Click the Add button. Visual Basic displays the Watch window.
If you have closed the Watch window, you can display it again by choosing View > Watch
Window.
About error handling
Imagine that you’ve written a script that formats the current text selection. What should
the script do if the current selection turns out not to be text at all, but a path item? “Error
handling” is code you add to your script to respond to conditions other than those you
expect it to encounter.
Handlers and subroutines About error handling30
If you have complete control over the situations in which your script will run, there’s no
need for you to worry about error handling. If not, however, you’ll have to add some error
handling capabilities to your script. The following examples show how to how you can
stop a script from executing when a specific file cannot be found.
AppleScript
--Store a reference to the fifth path item of the document in a variable
--If the object does not exist in the current document, display a message
tell application "Adobe Illustrator 10"
activate
try
set itemCount to count of path items in current document
set fifthItem to path item 5 of current document
on error
display dialog "Couldn't locate 5th path object - Only " ¬
& itemCount & " objects."
end try
end tell
Visual Basic
Private Sub Command1_Click()
' Store a reference to the fifth path item of the document in a
' variable. If the object does not exist in the current document,
' display message.
Dim appRef As New Illustrator.Application
Dim docRef As Illustrator.Document
Dim aiObject As Illustrator.PathItem
Dim numObjects As Single
Dim errorMessage As String
Set docRef = appRef.ActiveDocument
numObjects = docRef.PathItems.Count
On Error GoTo DisplayError
Set aiObject = docRef.PathItems(5)
Exit Sub
DisplayError:
errorMessage = "Couldn't locate 5th path object - Only "
errorMessage = errorMessage & numObjects & " objects."
MsgBox errorMessage
End Sub
Loading...