PathItem
PathItem
Section titled “PathItem”app.activeDocument.pathItems[index]
Description
Section titled “Description”Specifies 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.
Properties
Section titled “Properties”PathItem.area
Section titled “PathItem.area”app.activeDocument.pathItems[index].area
Description
Section titled “Description”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.
Number (double); read-only.
PathItem.artworkKnockout
Section titled “PathItem.artworkKnockout”app.activeDocument.pathItems[index].artworkKnockout
Description
Section titled “Description”Is this object used to create a knockout, and if so, what kind of knockout.
PathItem.blendingMode
Section titled “PathItem.blendingMode”app.activeDocument.pathItems[index].blendingMode
Description
Section titled “Description”The blend mode used when compositing an object.
PathItem.clipping
Section titled “PathItem.clipping”app.activeDocument.pathItems[index].clipping
Description
Section titled “Description”If true, this path should be used as a clipping path.
Boolean
PathItem.closed
Section titled “PathItem.closed”app.activeDocument.pathItems[index].closed
Description
Section titled “Description”If true, this path is closed.
Boolean
PathItem.controlBounds
Section titled “PathItem.controlBounds”app.activeDocument.pathItems[index].controlBounds
Description
Section titled “Description”The bounds of the object including stroke width and controls.
Array of 4 numbers; read-only.
PathItem.editable
Section titled “PathItem.editable”app.activeDocument.pathItems[index].editable
Description
Section titled “Description”If true, this item is editable.
Boolean; read-only.
PathItem.evenodd
Section titled “PathItem.evenodd”app.activeDocument.pathItems[index].evenodd
Description
Section titled “Description”If true, the even-odd rule should be used to determine “insideness.”
Boolean
PathItem.fillColor
Section titled “PathItem.fillColor”app.activeDocument.pathItems[index].fillColor
Description
Section titled “Description”The fill color of the path.
PathItem.filled
Section titled “PathItem.filled”app.activeDocument.pathItems[index].filled
Description
Section titled “Description”If true, the path is filled.
Boolean
PathItem.fillOverprint
Section titled “PathItem.fillOverprint”app.activeDocument.pathItems[index].fillOverprint
Description
Section titled “Description”If true, the art beneath a filled object should be overprinted.
Boolean
PathItem.geometricBounds
Section titled “PathItem.geometricBounds”app.activeDocument.pathItems[index].geometricBounds
Description
Section titled “Description”The bounds of the object excluding stroke width.
Array of 4 numbers; read-only.
PathItem.guides
Section titled “PathItem.guides”app.activeDocument.pathItems[index].guides
Description
Section titled “Description”If true, this path is a guide object.
Boolean
PathItem.height
Section titled “PathItem.height”app.activeDocument.pathItems[index].height
Description
Section titled “Description”The height of the group item.
Number (double)
PathItem.hidden
Section titled “PathItem.hidden”app.activeDocument.pathItems[index].hidden
Description
Section titled “Description”If true, this item is hidden.
Boolean
PathItem.isIsolated
Section titled “PathItem.isIsolated”app.activeDocument.pathItems[index].isIsolated
Description
Section titled “Description”If true, this object is isolated.
Boolean
PathItem.layer
Section titled “PathItem.layer”app.activeDocument.pathItems[index].layer
Description
Section titled “Description”The layer to which this item belongs.
Layer; read-only.
PathItem.left
Section titled “PathItem.left”app.activeDocument.pathItems[index].left
Description
Section titled “Description”The position of the left side of the item (in points, measured from the left side of the page).
Number (double)
PathItem.length
Section titled “PathItem.length”app.activeDocument.pathItems[index].length
Description
Section titled “Description”The length of this path in points.
Number (double)
PathItem.locked
Section titled “PathItem.locked”app.activeDocument.pathItems[index].locked
Description
Section titled “Description”If true, this item is locked.
Boolean
PathItem.name
Section titled “PathItem.name”app.activeDocument.pathItems[index].name
Description
Section titled “Description”The name of this item.
String
PathItem.note
Section titled “PathItem.note”app.activeDocument.pathItems[index].note
Description
Section titled “Description”The note assigned to this item.
String
PathItem.opacity
Section titled “PathItem.opacity”app.activeDocument.pathItems[index].opacity
Description
Section titled “Description”The opacity of the object.
Range: 0.0 to 100.0
Number (double)
PathItem.parent
Section titled “PathItem.parent”app.activeDocument.pathItems[index].parent
Description
Section titled “Description”The parent of this object.
PathItem.pathPoints
Section titled “PathItem.pathPoints”app.activeDocument.pathItems[index].pathPoints
Description
Section titled “Description”The path points contained in this path item.
PathPoints; read-only.
PathItem.pixelAligned
Section titled “PathItem.pixelAligned”app.activeDocument.pathItems[index].pixelAligned
Description
Section titled “Description”true if this item is aligned to the pixel grid.
Boolean
PathItem.polarity
Section titled “PathItem.polarity”app.activeDocument.pathItems[index].polarity
Description
Section titled “Description”The polarity of the path.
PathItem.position
Section titled “PathItem.position”app.activeDocument.pathItems[index].position
Description
Section titled “Description”The position (in points) of the top left corner of the pluginItem object in the format [x, y]. Does not include stroke weight.
Array of 2 numbers; read-only.
PathItem.resolution
Section titled “PathItem.resolution”app.activeDocument.pathItems[index].resolution
Description
Section titled “Description”The resolution of the path in dots per inch (dpi).
Number (double)
PathItem.selected
Section titled “PathItem.selected”app.activeDocument.pathItems[index].selected
Description
Section titled “Description”If true, this item is selected.
Boolean
PathItem.selectedPathPoints
Section titled “PathItem.selectedPathPoints”app.activeDocument.pathItems[index].selectedPathPoints
Description
Section titled “Description”All of the selected path points in the path.
PathPoints; read-only.
PathItem.sliced
Section titled “PathItem.sliced”app.activeDocument.pathItems[index].sliced
Description
Section titled “Description”If true, the item sliced.
Default: false
Boolean
PathItem.strokeCap
Section titled “PathItem.strokeCap”app.activeDocument.pathItems[index].strokeCap
Description
Section titled “Description”The type of line capping.
PathItem.strokeColor
Section titled “PathItem.strokeColor”app.activeDocument.pathItems[index].strokeColor
Description
Section titled “Description”The stroke color for the path.
PathItem.stroked
Section titled “PathItem.stroked”app.activeDocument.pathItems[index].stroked
Description
Section titled “Description”If true, the path should be stroked.
Boolean
PathItem.strokeDashes
Section titled “PathItem.strokeDashes”app.activeDocument.pathItems[index].strokeDashes
Description
Section titled “Description”Dash lengths. Set to an empty object, {}, for a solid line.
Object
PathItem.strokeDashOffset
Section titled “PathItem.strokeDashOffset”app.activeDocument.pathItems[index].strokeDashOffset
Description
Section titled “Description”The default distance into the dash pattern at which the pattern should be started.
Number (double)
PathItem.strokeJoin
Section titled “PathItem.strokeJoin”app.activeDocument.pathItems[index].strokeJoin
Description
Section titled “Description”Type of joints for the path.
PathItem.strokeMiterLimit
Section titled “PathItem.strokeMiterLimit”app.activeDocument.pathItems[index].strokeMiterLimit
Description
Section titled “Description”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
Number (double)
PathItem.strokeOverprint
Section titled “PathItem.strokeOverprint”app.activeDocument.pathItems[index].strokeOverprint
Description
Section titled “Description”If true, the art beneath a stroked object should be overprinted.
Boolean
PathItem.strokeWidth
Section titled “PathItem.strokeWidth”app.activeDocument.pathItems[index].strokeWidth
Description
Section titled “Description”The width of the stroke (in points).
Number (double)
PathItem.tags
Section titled “PathItem.tags”app.activeDocument.pathItems[index].tags
Description
Section titled “Description”The tags contained in this item.
Tags; read-only.
PathItem.top
Section titled “PathItem.top”app.activeDocument.pathItems[index].top
Description
Section titled “Description”The position of the top of the item (in points, measured from the bottom of the page).
Number (double)
PathItem.typename
Section titled “PathItem.typename”app.activeDocument.pathItems[index].typename
Description
Section titled “Description”The class name of the referenced object.
String; read-only.
PathItem.uRL
Section titled “PathItem.uRL”app.activeDocument.pathItems[index].uRL
Description
Section titled “Description”The value of the Adobe URL tag assigned to this item.
String
PathItem.visibilityVariable
Section titled “PathItem.visibilityVariable”app.activeDocument.pathItems[index].visibilityVariable
Description
Section titled “Description”The visibility variable bound to the item.
PathItem.visibleBounds
Section titled “PathItem.visibleBounds”app.activeDocument.pathItems[index].visibleBounds
Description
Section titled “Description”The visible bounds of the item including stroke width.
Array of 4 numbers; read-only.
PathItem.width
Section titled “PathItem.width”app.activeDocument.pathItems[index].width
Description
Section titled “Description”The width of the item.
Number (double)
PathItem.wrapInside
Section titled “PathItem.wrapInside”app.activeDocument.pathItems[index].wrapInside
Description
Section titled “Description”If true, the text frame object should be wrapped inside this object.
Boolean
PathItem.wrapOffset
Section titled “PathItem.wrapOffset”app.activeDocument.pathItems[index].wrapOffset
Description
Section titled “Description”The offset to use when wrapping text around this object.
Number (double)
PathItem.wrapped
Section titled “PathItem.wrapped”app.activeDocument.pathItems[index].wrapped
Description
Section titled “Description”If true, wrap text frame objects around this object (text frame must be above the object).
Boolean
PathItem.zOrderPosition
Section titled “PathItem.zOrderPosition”app.activeDocument.pathItems[index].zOrderPosition
Description
Section titled “Description”The position of this item within the stacking order of the group or layer (parent) that contains the item.
Number; read-only.
Methods
Section titled “Methods”PathItem.duplicate()
Section titled “PathItem.duplicate()”app.activeDocument.pathItems[index].duplicate([relativeObject][, insertionLocation])
Description
Section titled “Description”Creates a duplicate of the selected object.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
relativeObject | Object, optional | Object to duplicate to |
insertionLocation | ElementPlacement, optional | Location to insert element |
Returns
Section titled “Returns”PathItem.move()
Section titled “PathItem.move()”app.activeDocument.pathItems[index].move(relativeObject, insertionLocation)
Description
Section titled “Description”Moves the object.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
relativeObject | Object | Object to move element within |
insertionLocation | ElementPlacement, optional | Location to move element to |
Returns
Section titled “Returns”PathItem.remove()
Section titled “PathItem.remove()”app.activeDocument.pathItems[index].remove()
Description
Section titled “Description”Deletes this object.
Returns
Section titled “Returns”Nothing.
PathItem.resize()
Section titled “PathItem.resize()”app.activeDocument.pathItems[index].resize( scaleX, scaleY [,changePositions] [,changeFillPatterns] [,changeFillGradients] [,changeStrokePattern] [,changeLineWidths] [,scaleAbout])Description
Section titled “Description”Scales the art item where scaleX is the horizontal scaling factor and scaleY is the vertical scaling factor. 100.0 = 100%.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
scaleX | Number (double) | Horizontal scaling factor |
scaleY | Number (double) | Vertical scaling factor |
changePositions | Boolean, optional | Whether to effect art object positions and orientations |
changeFillPatterns | Boolean, optional | Whether to transform fill patterns |
changeFillGradients | Boolean, optional | Whether to transform fill gradients |
changeStrokePattern | Boolean, optional | Whether to transform stroke patterns |
changeLineWidths | Number (double), optional | The amount to scale line widths |
scaleAbout | Transformation, optional | The point to use as anchor, to transform about |
Returns
Section titled “Returns”Nothing.
PathItem.rotate()
Section titled “PathItem.rotate()”app.activeDocument.pathItems[index].rotate( angle [,changePositions] [,changeFillPatterns] [,changeFillGradients] [,changeStrokePattern] [,rotateAbout])Description
Section titled “Description”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.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
angle | Number (double) | The angle amount to rotate the element |
changePositions | Boolean, optional | Whether to effect art object positions and orientations |
changeFillPatterns | Boolean, optional | Whether to transform fill patterns |
changeFillGradients | Boolean, optional | Whether to transform fill gradients |
changeStrokePattern | Boolean, optional | Whether to transform stroke patterns |
rotateAbout | Transformation, optional | The point to use as anchor, to transform about |
Returns
Section titled “Returns”Nothing.
PathItem.setEntirePath()
Section titled “PathItem.setEntirePath()”app.activeDocument.pathItems[index].setEntirePath(pathPoints)
Description
Section titled “Description”Sets the path using an array of [x, y] coordinate pairs.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
pathPoints | Array of [x, y] coordinate pairs | Array of point coordinates to set |
Returns
Section titled “Returns”Nothing.
PathItem.transform()
Section titled “PathItem.transform()”app.activeDocument.pathItems[index].transform( transformationMatrix [, changePositions] [, changeFillPatterns] [, changeFillGradients] [, changeStrokePattern] [, changeLineWidths] [, transformAbout])Description
Section titled “Description”Transforms the art item by applying a transformation matrix.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
transformationMatrix | Matrix | Transformation matrix to apply |
changePositions | Boolean, optional | Whether to change Positions |
changeFillPatterns | Boolean, optional | Whether to change Fill Patterns |
changeFillGradients | Boolean, optional | Whether to change Fill Gradients |
changeStrokePattern | Boolean, optional | Whether to change Stroke Pattern |
changeLineWidths | Number (double), optional | The amount to scale line widths |
transformAbout | Transformation, optional | The point to use as anchor, to transform about |
Returns
Section titled “Returns”Nothing.
PathItem.translate()
Section titled “PathItem.translate()”app.activeDocument.pathItems[index].translate( [deltaX] [, deltaY] [, transformObjects] [, transformFillPatterns] [, transformFillGradients] [, transformStrokePatterns])Description
Section titled “Description”Repositions the art item relative to the current position, where deltaX is the horizontal offset and deltaY is the vertical offset.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
deltaX | Number (double), optional | Horizontal offset |
deltaY | Number (double), optional | Vertical offset |
transformObjects | Boolean, optional | Whether to transform Objects |
transformFillPatterns | Boolean, optional | Whether to transform Fill Patterns |
transformFillGradients | Boolean, optional | Whether to transform Fill Gradients |
transformStrokePatterns | Boolean, optional | Whether to transform Stroke Patterns |
Returns
Section titled “Returns”Nothing.
PathItem.zOrder()
Section titled “PathItem.zOrder()”app.activeDocument.pathItems[index].zOrder(zOrderCmd)
Description
Section titled “Description”Arranges the art item’s position in the stacking order of the group or layer (parent) of this object.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
zOrderCmd | ZOrderMethod | Stacking order arrangement method |
Returns
Section titled “Returns”Nothing.
Example
Section titled “Example”Setting colors in a path
Section titled “Setting colors in a path”// Sets the stroke and fill of a path item to colors of a randomly selected swatchif (app.documents.length > 0 && app.activeDocument.pathItems.length > 0) { var doc = app.activeDocument;
for (var i = 0; i < doc.pathItems.length; i++) { var pathRef = doc.pathItems[i]; pathRef.filled = true; pathRef.stroked = true;
var 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
Section titled “Creating a path from straight lines”// This script illustrates the use of the setEntirePath method.// Creates a new open path consisting of 10 straight linesif (app.documents.length > 0) { var lineList = [];
for (i = 0; i < lineList.length; i++) { lineList.push([i * 10 + 50, ((i - 5) ^ 2) * 5 + 50]; }
app.defaultStroked = true; newPath = app.activeDocument.pathItems.add(); newPath.setEntirePath(lineList);}