Scripting Illustrator

This section provides an overview of how to use scripting objects to perform typical programming tasks in Illustrator.

Basics:
Additional topics:

Accessing and referencing objects

When you write a script, you must first decide which file, or document, the script should act on. To access to Illustrator Application object in ActionScript use this code:

import com.adobe.csawlib.illustrator.Illustrator;
import com.adobe.illustrator.Application;
var app:Application = Illustrator.app;

Through the Application object, the script can create a new document, open an existing document, or act on a document that is already open. To refer to the currently selected document, use the Application object’s activeDocument property. Similarly,  use the Document object’s activeLayer property to refer to the currently selected layer. There are other “active” object properties, like activeDataset or activeView. For details, see the scripting reference documentation.

Through the Document object, the script can create new art-tree objects, operate on objects that the user selected, or operate on objects in one of the object collections.

 Accessing objects in collections

All open documents, as well as the objects in a document, are collected into collection objects for the object type. A collection object contains an array of the objects that you can access by index or name. All numeric collection references in ActionScript are zero-based: the first object in the collection has the index 0.  As a rule, collection index numbers do not shift when you add an object to a collection. There is one exception: documents.index(0) is always the active or front-most document.

The collection object takes the plural form of the object name. For example, the collection object for the Document object is Documents. It is found in the Application object's documents property. Most collection objects must be obtained from a container; for example, a PathItems collection object can be contained by a Document object or a Layer object. To refer to a PathIems object in a document or layer:

app.documents.index(0).pathItems.index(0)
app.documents.index(0).layers.index(0).pathItems.index(0)

The following script sample gets all graphic style objects in the graphic styles collection; that is, it gets all graphic styles available to the active document:

var myStyles:GraphicStyles = app.activeDocument.graphicStyles;

To access the first style in a graphic styles collection, you can use the variable declared in the previous script sample, or you can use the containment hierarchy to refer to the collection:

var firstStyle:GraphicStyle = myStyles.index(0);
var firstStyle:GraphicStyle = app.activeDocument.graphicStyles.index(0);

The following statements assign the name of the first graphic style in the collection to a variable. You can use these statements interchangeably.

var styleName:String = myStyles.index(0).name
var styleName:String = firstStyle.name
var styleName:String = app.activeDocument.graphicStyles.index(0).name

To get the total number of objects in a collection, use the length property:

trace( myStyles.length );

The index of the last graphic style in the collection is myStyles.length-1 (-1 because the collection starts the index count at 0 and the length property counts from 1):

var lastStyle:GraphicStyle = myStyles.index(myStyles.length - 1);

If you know the name of an object, you can access the object in the collections using the name in quotes, surrounded by square brackets; for example:

var getStyle:GraphicStyle = myStyles.getByName("Ice Type");

Each element in the collection is an object of the desired type, and you can access its properties through the collection. For example, to get an object’s name, use the name property:

var styleName:String = app.activeDocument.graphicStyles.index(0).name;

To apply the last style, which we assigned to the variable lastStyle, to the first PageItem in the document, use its applyTo() method:

lastStyle.applyTo( app.activeDocument.pageItems.index(0));

Creating new objects

Some types of objects (besides the Application object itself) cannot be obtained from containers or parent objects. Your script must create the following types of objects explicitly:

Accessing selected objects

Sometimes, you want to write scripts that act on the currently selected object or objects. For example, you might want to apply formatting to selected text or change a selected path’s shape.

To refer to all currently selected objects in a document, use the Document object’s selection property: 

var selectedObjects:Array = app.activeDocument.selection as Array;

This array can contain any type of art objects, depending on what types of objects are selected.  To get or manipulate the properties of the selected art items, you must retrieve the individual items in the array. You must determine the object’s type, so you will know which properties and methods you can use with it. For example:

var selectedobject:Object= app.activeDocument.selection[0];

if (selectedObject is PathItem){...}

The first object in a selection array is the selected object that was most recently added to the page, not the object that was most recently selected.

Renaming objects

Some types of objects can be renamed; that is, their name property is writeable. If a script modifies the name of such an object, references to that object by index can become invalid. The following types of objects can be sorted alphabetically by name in the corresponding Illustrator panel:

Brush
Gradient
GraphicStyle
Pattern
Swatch
Symbol
Variable

Page-item positioning and dimensions

Illustrator uses simple, two-dimensional geometry in the form of points to record the position of PageItem objects in a document. Every PageItem  object in a document has a position property that defines a fixed point as a pair of page coordinates in the format [x, y]. The fixed point is the top-left corner of the object’s bounding box. You can see these coordinates in the Info panel when you select or create an object in Illustrator.

For the artboard, the default coordinate origin, (0,0), is the top-left corner, reflected in the rulerOrigin property of the Artboard object. X coordinate values increase from left to right, and Y values increase from top to bottom. This changed in the CS5 release; to maintain script compatibility, a document created by a script still uses the older system, with the origin at the bottom left of the artboard, and the Y value increasing from bottom to top. The page origin property of a document object defines the bottom-left corner of the printable region of the document as a fixed point.

Each PageItem  object has width and height properties. The maximum value allowed for the width or height of a page item is 16348 points.

Art item bounds

Every PageItem  object has three properties that use fixed rectangles to describe the object’s overall extent:

 ai_pageitems.png

Measurement units

Illustrator uses document points (72 points per inch) as the unit of measurement for almost all distances.  Exceptions include values for properties such as kerning, tracking, and the aki properties (used for Japanese text composition), which use em units.

Illustrator uses document points when communicating with your scripts regardless of the current ruler units. 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 inches for coordinates or measurement units, you must multiply all inch values by 72 when entering the values in your script.

The following table shows conversion formulas for various units of measurement:

Unit

Conversion formula

centimeters 28.346 points = 1 centimeter
inches 72 points = 1 inch
millimeters 2.834645 points = 1 millimeter
picas 12 points = 1 pica
Qs 1 Q (1 Q equals 0.23 millimeter)

Em-space units

Values that use em units instead of points are measured in thousandths of an em. An em is 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. In a 10-point font, a kerning value of 20 em units is equivalent to:

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

Working with text frames

There are three types of text frames;  point, area, and path.

ai_text_types.png

To create a text frame of a specific type, use the TextFrames method whose name corresponds to the type; for example:

var rectRef:PathItem = docRef.pathItems.rectangle(700, 50, 100, 100);

//use the areaText method to create the text frame
var areaTextRef:TextFrame = docRef.textFrames.areaText(rectRef);

areaTextRef.content = "Hello there";

Threaded frames

As in the Illustrator application, you can thread area or path text frames. To thread existing text frames, use the nextFrame or previousFrame property of the TextFrame object.

var app:Application = Illustrator.app;

var myDoc = app.documents.add();

var myPathItem1:PathItem = myDoc.pathItems.rectangle(400, 50, 100, 100);
var myTextFrame1:TextFrame= myDoc.textFrames.areaText(myPathItem1);
var myPathItem2:PathItem = myDoc.pathItems.rectangle(150, 150, 100, 100);
var myTextFrame2:TextFrame = myDoc.textFrames.areaText(myPathItem2);

// use the nextFrame property to thread the text frames
myTextFrame1.nextFrame = myTextFrame2;

var sText:String = ( <![CDATA[

This is two text frames linked together as one story, with text flowing from the first to the last. This is two text frames linked together as one story, with text flowing from the first to the last. This is two text frames linked together as one story.

]]> ).toString();

myTextFrame1.contents = sText;

app.redraw();

Threaded frames make a single story object. To observe this for the threaded frames you just created:

trace("There are " + myDoc.textFrames.length + " text frames.");
trace("There are " + myDoc.stories.length + " stories.");

User-interaction levels

When user feedback is required, an application typically presents a dialog. This is called user interaction. It is useful and expected when you are directly interacting with the application; however, when a script is interacting with an application, a dialog brings the execution of the script to a halt until the dialog is dismissed.

The application object contains a user interaction level property that allows you to control the level of interaction allowed during script execution. You can suppress interaction in an automation environment or allow some interaction where scripts are being used in a more interactive fashion.

There are two possible values for the app.userInteractionLevel property:

Printing Illustrator documents

The Document object’s print() method takes one optional parameter, a PrintOptions object. You can use this feature to capture and automate parts of your print workflow. Scripting exposes the full capabilities of Illustrator printing, some of which may not be accessible through the application’s user interface. Illustrator currently supports at most one print session at a time.

The PrintOptions object allows you to define print settings like PPD, PostScript options, paper options, and color-management options; all of these setting are encapsulated in other options objects. The PrintOptions object also has a printPreset property, which allows you to specify a preset to define your print job.

You can find out which printers, PPDs, print presets, and other items are available by using the Application object’s read-only list properties, such as printerList, PPDFileList, and printPresetsList.

 

 

Copyright © 2011 Adobe Systems Incorporated. All rights reserved.