CompoundPath
A compound path is a complex path that is made up of one or more simple sub-paths. It can have the nonzero
fill rule, or the evenodd
rule applied. Both rules use mathematical equations to determine if any region is outside or inside the final shape. The evenodd
rule is more predictable: Every other region within a such a compound path is a hole, regardless of path direction.
All the paths in a compound path take on the style of the compound path and can be accessed through its item.children
list.
Constructors
CompoundPath(object)
Creates a new compound path item from an object description and places it at the top of the active layer.
Parameters:
object:
Object
β an object containing properties to be set on the path
Returns:
CompoundPath
β the newly created path
Example:
CompoundPath(pathData)
Creates a new compound path item from SVG path-data and places it at the top of the active layer.
Parameters:
pathData:
String
β the SVG path-data that describes the geometry of this path
Returns:
CompoundPath
β the newly created path
Example:
Properties
closed
Specifies whether the compound-path is fully closed, meaning all its contained sub-paths are closed path.
Type:
Boolean
See also:
path.closed
firstSegment
The first Segment contained within the compound-path, a short-cut to calling
path.firstSegment
onitem.firstChild
.Read only.
Type:
Segment
lastSegment
The last Segment contained within the compound-path, a short-cut to calling
path.lastSegment
onitem.lastChild
.Read only.
Type:
Segment
curves
All the curves contained within the compound-path, from all its child
Path
items.Read only.
Type:
Array of
Curve
objects
firstCurve
The first Curve contained within the compound-path, a short-cut to calling
path.firstCurve
onitem.firstChild
.Read only.
Type:
Curve
lastCurve
The last Curve contained within the compound-path, a short-cut to calling
path.lastCurve
onitem.lastChild
.Read only.
Type:
Curve
area
The area that the compound-pathβs geometry is covering, calculated by getting the
path.area
of each sub-path and it adding up. Note that self-intersecting paths and sub-paths of different orientation can result in areas that cancel each other out.Read only.
Type:
Number
length
The total length of all sub-paths in this compound-path, calculated by getting the
path.length
of each sub-path and it adding up.Read only.
Type:
Number
Properties inherited from Item
Item
id
The unique id of the item.
Read only.
Type:
Number
className
The class name of the item as a string.
Values:
'Group'
,'Layer'
,'Path'
,'CompoundPath'
,'Shape'
,'Raster'
,'SymbolItem'
,'PointText'
Type:
String
name
The name of the item. If the item has a name, it can be accessed by name through its parentβs children list.
Type:
String
Example:
style
The path style of the item.
Type:
Style
Example:Applying several styles to an item in one go, by passing an object to its style property:
Example:Copying the style of another item:
Example:Applying the same style object to multiple items:
locked
Specifies whether the item is locked. When set to
true
, item interactions with the mouse are disabled.Default:
false
Type:
Boolean
Example:
visible
Specifies whether the item is visible. When set to
false
, the item wonβt be drawn.Default:
true
Type:
Boolean
Example:Hiding an item:
blendMode
The blend mode with which the item is composited onto the canvas. Both the standard canvas compositing modes, as well as the new CSS blend modes are supported. If blend-modes cannot be rendered natively, they are emulated. Be aware that emulation can have an impact on performance.
Values:
'normal'
,'multiply'
,'screen'
,'overlay'
,'soft-light'
,'hard- light'
,'color-dodge'
,'color-burn'
,'darken'
,'lighten'
,'difference'
,'exclusion'
,'hue'
,'saturation'
,'luminosity'
,'color'
,'add'
,'subtract'
,'average'
,'pin-light'
,'negation'
,'source-over'
,'source-in'
,'source-out'
,'source-atop'
,'destination-over'
,'destination-in'
,'destination-out'
,'destination-atop'
,'lighter'
,'darker'
,'copy'
,'xor'
Default:
'normal'
Type:
String
Example:Setting an item's blend mode:
opacity
The opacity of the item as a value between
0
and1
.Default:
1
Type:
Number
Example:Making an item 50% transparent:
selected
Specifies whether the item is selected. This will also return
true
forGroup
items if they are partially selected, e.g. groups containing selected or partially selected paths.Paper.js draws the visual outlines of selected items on top of your project. This can be useful for debugging, as it allows you to see the construction of paths, position of path curves, individual segment points and bounding boxes of symbol and raster items.
Default:
false
Type:
Boolean
See also:
project.selectedItems
segment.selected
curve.selected
point.selected
Example:Selecting an item:
clipMask
Specifies whether the item defines a clip mask. This can only be set on paths and compound paths, and only if the item is already contained within a clipping group.
Default:
false
Type:
Boolean
data
A plain javascript object which can be used to store arbitrary data on the item.
Type:
Object
Example:
Example:
Example:
Example:
Position and Bounding Boxes
position
The itemβs position within the parent itemβs coordinate system. By default, this is the
rectangle.center
of the itemβsbounds
rectangle.Type:
Point
Example:Changing the position of a path:
Example:Changing the x coordinate of an item's position:
pivot
The itemβs pivot point specified in the item coordinate system, defining the point around which all transformations are hinging. This is also the reference point for
position
. By default, it is set tonull
, meaning therectangle.center
of the itemβsbounds
rectangle is used as pivot.Default:
null
Type:
Point
bounds
The bounding rectangle of the item excluding stroke width.
Type:
Rectangle
strokeBounds
The bounding rectangle of the item including stroke width.
Type:
Rectangle
handleBounds
The bounding rectangle of the item including handles.
Type:
Rectangle
internalBounds
The bounding rectangle of the item without any matrix transformations.
Typical use case would be drawing a frame around the object where you want to draw something of the same size, position, rotation, and scaling, like a selection frame.
Type:
Rectangle
rotation
The current rotation angle of the item, as described by its
matrix
. Please note that this only returns meaningful values for items withapplyMatrix
set tofalse
, meaning they do not directly bake transformations into their content.Type:
Number
scaling
The current scale factor of the item, as described by its
matrix
. Please note that this only returns meaningful values for items withapplyMatrix
set tofalse
, meaning they do not directly bake transformations into their content.Type:
Point
matrix
The itemβs transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.
Type:
Matrix
globalMatrix
The itemβs global transformation matrix in relation to the global project coordinate space. Note that the viewβs transformations resulting from zooming and panning are not factored in.
Read only.
Type:
Matrix
viewMatrix
The itemβs global matrix in relation to the view coordinate space. This means that the viewβs transformations resulting from zooming and panning are factored in.
Read only.
Type:
Matrix
applyMatrix
Controls whether the transformations applied to the item (e.g. through
transform(matrix)
,rotate(angle)
,scale(scale)
, etc.) are stored in itsmatrix
property, or whether they are directly applied to its contents or children (passed on to the segments inPath
items, the children ofGroup
items, etc.).Default:
true
Type:
Boolean
Project Hierarchy
project
The project that this item belongs to.
Read only.
Type:
Project
view
The view that this item belongs to.
Read only.
Type:
View
layer
The layer that this item is contained within.
Read only.
Type:
Layer
parent
The item that this item is contained within.
Type:
Item
Example:
Example:Setting the parent of the item to another item
Example:Setting the parent of an item in the constructor
children
The children items contained within this item. Items that define a
name
can also be accessed by name.Please note: The children array should not be modified directly using array functions. To remove single items from the children list, use
item.remove
(), to remove all items from the children list, useitem.removeChildren
(). To add items to the children list, useitem.addChild(item)
oritem.insertChild(index, item)
.Type:
Array of
Item
objects
Example:Accessing items in the children array:
Example:Accessing children by name:
Example:Passing an array of items to item.children:
firstChild
The first item contained within this item. This is a shortcut for accessing
item.children[0]
.Read only.
Type:
Item
lastChild
The last item contained within this item.This is a shortcut for accessing
item.children[item.children.length - 1]
.Read only.
Type:
Item
nextSibling
The next item on the same level as this item.
Read only.
Type:
Item
previousSibling
The previous item on the same level as this item.
Read only.
Type:
Item
index
The index of this item within the list of its parentβs children.
Read only.
Type:
Number
Stroke Style
strokeColor
The color of the stroke.
Type:
Color
βnull
Example:Setting the stroke color of a path:
strokeWidth
The width of the stroke.
Type:
Number
Example:Setting an item's stroke width:
strokeCap
The shape to be used at the beginning and end of open
Path
items, when they have a stroke.Values:
'round'
,'square'
,'butt'
Default:
'butt'
Type:
String
Example:A look at the different stroke caps:
strokeJoin
The shape to be used at the segments and corners of
Path
items when they have a stroke.Values:
'miter'
,'round'
,'bevel'
Default:
'miter'
Type:
String
Example:A look at the different stroke joins:
dashOffset
The dash offset of the stroke.
Default:
0
Type:
Number
strokeScaling
Specifies whether the stroke is to be drawn taking the current affine transformation into account (the default behavior), or whether it should appear as a non-scaling stroke.
Default:
true
Type:
Boolean
dashArray
Specifies an array containing the dash and gap lengths of the stroke.
Default:
[]
Type:
Array of
Numbers
Example:
miterLimit
The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for
item.strokeJoin
, it is possible for the miter to extend far beyond theitem.strokeWidth
of the path. The miterLimit imposes a limit on the ratio of the miter length to theitem.strokeWidth
.Default:
10
Type:
Number
Fill Style
fillColor
The fill color of the item.
Type:
Color
βnull
Example:Setting the fill color of a path to red:
fillRule
The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than
'nonzero'
.Values:
'nonzero'
,'evenodd'
Default:
'nonzero'
Type:
String
Shadow Style
shadowColor
The shadow color.
Type:
Color
βnull
Example:Creating a circle with a black shadow:
shadowBlur
The shadowβs blur radius.
Default:
0
Type:
Number
shadowOffset
The shadowβs offset.
Default:
0
Type:
Point
Selection Style
selectedColor
The color the item is highlighted with when selected. If the item does not specify its own color, the color defined by its layer is used instead.
Type:
Color
βnull
Event Handlers
onFrame
Item level handler function to be called on each frame of an animation. The function receives an event object which contains information about the frame event:
Type:
Function
βnull
Options:
event.count: Number
β the number of times the frame event was firedevent.time: Number
β the total amount of time passed since the first frame event in secondsevent.delta: Number
β the time passed in seconds since the last frame eventSee also:
view.onFrame
Example:Creating an animation:
onMouseDown
The function to be called when the mouse button is pushed down on the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseDown
Example:Press the mouse button down on the circle shaped path, to make it red:
Example:Press the mouse on the circle shaped paths to remove them:
onMouseDrag
The function to be called when the mouse position changes while the mouse is being dragged over the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseDrag
Example:Press and drag the mouse on the blue circle to move it:
onMouseUp
The function to be called when the mouse button is released over the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseUp
Example:Release the mouse button over the circle shaped path, to make it red:
onClick
The function to be called when the mouse clicks on the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onClick
Example:Click on the circle shaped path, to make it red:
Example:Click on the circle shaped paths to remove them:
onDoubleClick
The function to be called when the mouse double clicks on the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onDoubleClick
Example:Double click on the circle shaped path, to make it red:
Example:Double click on the circle shaped paths to remove them:
onMouseMove
The function to be called repeatedly while the mouse moves over the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseMove
Example:Move over the circle shaped path, to change its opacity:
onMouseEnter
The function to be called when the mouse moves over the item. This function will only be called again, once the mouse moved outside of the item first. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseEnter
Example:When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.
Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set back to black.
onMouseLeave
The function to be called when the mouse moves out of the item. The function receives a
MouseEvent
object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy and will reach the view, unless they are stopped withevent.stopPropagation
() or by returningfalse
from the handler.Type:
Function
βnull
See also:
view.onMouseLeave
Example:Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:
Methods inherited from Item
Item
set(props)
Sets the properties of the passed object literal on this item to the values defined in the object literal, if the item has property of the given name (or a setter defined for it).
Parameters:
props:
Object
Returns:
Item
β the item itself
Example:Setting properties through an object literal
clone([options])
Clones the item within the same project and places the copy above the item.
Options:
insert: undefined
β specifies whether the copy should be inserted into the scene graph. When set totrue
, it is inserted above the original β default:true
deep: undefined
β specifies whether the itemβs children should also be cloned β default:true
Parameters:
options:
Object
β optional, default:{ insert: true, deep: true }
Returns:
Item
β the newly cloned item
Example:Cloning items:
copyContent(source)
Copies the content of the specified item over to this item.
Parameters:
source:
Item
β the item to copy the content from
copyAttributes(source, excludeMatrix)
Copies all attributes of the specified item over to this item. This includes its style, visibility, matrix, pivot, blend-mode, opacity, selection state, data, name, etc.
Parameters:
source:
Item
β the item to copy the attributes fromexcludeMatrix:
Boolean
β whether to exclude the transformation matrix when copying all attributes
Geometric Tests
contains(point)
Checks whether the itemβs geometry contains the given point.
Parameters:
point:
Point
β the point to check forReturns:
Boolean
Example:Click within and outside the star below Create a star shaped path:
isInside(rect)
Parameters:
rect:
Rectangle
β the rectangle to check againstReturns:
Boolean
intersects(item)
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
Hit-testing, Fetching and Matching Items
hitTest(point[, options])
Performs a hit-test on the item and its children (if it is a
Group
orLayer
) at the location of the specified point, returning the first found hit.The options object allows you to control the specifics of the hit- test and may contain a combination of the following values:
Options:
options.tolerance: Number
β the tolerance of the hit-test β default:paperScope.settings
.hitToleranceoptions.class: Function
β only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which aninstanceof
check is performed:Group
,Layer
,Path
,CompoundPath
,Shape
,Raster
,SymbolItem
,PointText
, β¦options.match: Function
β a match function to be called for each found hit result: Returntrue
to return the result,false
to keep searchingoptions.fill: Boolean
β hit-test the fill of items β default:true
options.stroke: Boolean
β hit-test the stroke of path items, taking into account the setting of stroke color and width β default:true
options.segments: Boolean
β hit-test forsegment.point
ofPath
items β default:true
options.curves: Boolean
β hit-test the curves of path items, without taking the stroke color or width into accountoptions.handles: Boolean
β hit-test for the handles (segment.handleIn
/segment.handleOut
) of path segments.options.ends: Boolean
β only hit-test for the first or last segment points of open path itemsoptions.position: Boolean
β hit-test theitem.position
of of items, which depends on the setting ofitem.pivot
options.center: Boolean
β hit-test therectangle.center
of the bounding rectangle of items (item.bounds
)options.bounds: Boolean
β hit-test the corners and side-centers of the bounding rectangle of items (item.bounds
)options.guides: Boolean
β hit-test items that haveItem#guide
set totrue
options.selected: Boolean
β only hit selected itemsParameters:
point:
Point
β the point where the hit-test should be performed (in global coordinates system).options:
Object
β optional, default:{ fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }
Returns:
HitResult
β a hit result object describing what exactly was hit ornull
if nothing was hit
hitTestAll(point[, options])
Performs a hit-test on the item and its children (if it is a
Group
orLayer
) at the location of the specified point, returning all found hits.The options object allows you to control the specifics of the hit- test. See
hitTest(point[, options])
for a list of all options.Parameters:
point:
Point
β the point where the hit-test should be performed (in global coordinates system).options:
Object
β optional, default:{ fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }
Returns:
Array of HitResult
objects β hit result objects for all hits, describing what exactly was hit ornull
if nothing was hitSee also:
hitTest(point[, options])
;
matches(options)
Checks whether the item matches the criteria described by the given object, by iterating over all of its properties and matching against their values through
matches(name, compare)
.See
project.getItems(options)
for a selection of illustrated examples.Parameters:
options:
Object
βFunction
β the criteria to match againstReturns:
Boolean
βtrue
if the item matches all the criteria,false
otherwiseSee also:
getItems(options)
matches(name, compare)
Checks whether the item matches the given criteria. Extended matching is possible by providing a compare function or a regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x-coordinate to match all points with that x-value). Partial matching does work for
item.data
.See
project.getItems(options)
for a selection of illustrated examples.Parameters:
name:
String
β the name of the state to match againstcompare:
Object
β the value, function or regular expression to compare againstReturns:
Boolean
βtrue
if the item matches the state,false
otherwiseSee also:
getItems(options)
getItems(options)
Fetch the descendants (children or children of children) of this item that match the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for
item.data
.Matching items against a rectangular area is also possible, by setting either
options.inside
oroptions.overlapping
to a rectangle describing the area in which the items either have to be fully or partly contained.See
project.getItems(options)
for a selection of illustrated examples.Options:
options.recursive: Boolean
β whether to loop recursively through all children, or stop at the current level β default:true
options.match: Function
β a match function to be called for each item, allowing the definition of more flexible item checks that are not bound to properties. If no other match properties are defined, this function can also be passed instead of theoptions
objectoptions.class: Function
β the constructor function of the item type to match againstoptions.inside: Rectangle
β the rectangle in which the items need to be fully containedoptions.overlapping: Rectangle
β the rectangle with which the items need to at least partly overlapParameters:
options:
Object
βFunction
β the criteria to match againstReturns:
Array of Item
objects β the list of matching descendant itemsSee also:
matches(options)
getItem(options)
Fetch the first descendant (child or child of child) of this item that matches the properties in the specified object. Extended matching is possible by providing a compare function or regular expression. Matching points, colors only work as a comparison of the full object, not partial matching (e.g. only providing the x- coordinate to match all points with that x-value). Partial matching does work for
item.data
. Seeproject.getItems(match)
for a selection of illustrated examples.Parameters:
options:
Object
βFunction
β the criteria to match againstReturns:
Item
β the first descendant item matching the given criteriaSee also:
getItems(options)
Importing / Exporting JSON and SVG
exportJSON([options])
Exports (serializes) the item with its content and child items to a JSON data string.
Options:
options.asString: Boolean
β whether the JSON is returned as aObject
or aString
β default:true
options.precision: Number
β the amount of fractional digits in numbers used in JSON data β default:5
Parameters:
options:
Object
β the serialization options β optionalReturns:
String
β the exported JSON data
importJSON(json)
Imports (deserializes) the stored JSON data into this item. If the data describes an item of the same class or a parent class of the item, the data is imported into the item itself. If not, the imported item is added to this itemβs
item.children
list. Note that not all type of items can have children.Parameters:
json:
String
β the JSON data to import fromReturns:
Item
exportSVG([options])
importSVG(svg[, options])
Converts the provided SVG content into Paper.js items and adds them to the this itemβs children list. Note that the item is not cleared first. You can call
item.removeChildren
() to do so.Options:
options.expandShapes: Boolean
β whether imported shape items should be expanded to path items β default:false
options.onLoad: Function
β the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converteditem
and the originalsvg
data as a string. Only required when loading from external resources.options.onError: Function
β the callback function to call if an error occurs during loading. Only required when loading from external resources.options.insert: Boolean
β whether the imported items should be added to the item thatimportSVG()
is called on β default:true
options.applyMatrix: Boolean
β whether the imported items should have their transformation matrices applied to their contents or not β default:paperScope.settings
.applyMatrixParameters:
svg:
SVGElement
βString
β the SVG content to import, either as a SVG DOM node, a string containing SVG content, or a string describing the URL of the SVG file to fetch.options:
Object
β the import options β optionalReturns:
Item
β the newly created Paper.js item containing the converted SVG content
importSVG(svg, onLoad)
Imports the provided external SVG file, converts it into Paper.js items and adds them to the this itemβs children list. Note that the item is not cleared first. You can call
item.removeChildren
() to do so.Parameters:
svg:
SVGElement
βString
β the URL of the SVG file to fetch.onLoad:
Function
β the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converteditem
and the originalsvg
data as a string. Only required when loading from external files.Returns:
Item
β the newly created Paper.js item containing the converted SVG content
Hierarchy Operations
addChild(item)
Adds the specified item as a child of this item at the end of the its
children
list. You can use this function for groups, compound paths and layers.Parameters:
item:
Item
β the item to be added as a childReturns:
Item
β the added item, ornull
if adding was not possible
insertChild(index, item)
Inserts the specified item as a child of this item at the specified index in its
children
list. You can use this function for groups, compound paths and layers.Parameters:
index:
Number
β the index at which to insert the itemitem:
Item
β the item to be inserted as a childReturns:
Item
β the inserted item, ornull
if inserting was not possible
addChildren(items)
Adds the specified items as children of this item at the end of the its children list. You can use this function for groups, compound paths and layers.
Parameters:
items:
Array ofItem
objects β the items to be added as childrenReturns:
Array of Item
objects β the added items, ornull
if adding was not possible
insertChildren(index, items)
Inserts the specified items as children of this item at the specified index in its
children
list. You can use this function for groups, compound paths and layers.Parameters:
index:
Number
items:
Array ofItem
objects β the items to be appended as childrenReturns:
Array of Item
objects β the inserted items, ornull
if inserted was not possible
insertAbove(item)
Inserts this item above the specified item.
Parameters:
item:
Item
β the item above which it should be insertedReturns:
Item
β the inserted item, ornull
if inserting was not possible
insertBelow(item)
Inserts this item below the specified item.
Parameters:
item:
Item
β the item below which it should be insertedReturns:
Item
β the inserted item, ornull
if inserting was not possible
sendToBack()
Sends this item to the back of all other items within the same parent.
bringToFront()
Brings this item to the front of all other items within the same parent.
addTo(owner)
Adds it to the specified owner, which can be either a
Item
or aProject
.Parameters:
owner:
Project
βLayer
βGroup
βCompoundPath
β the item or project to add the item toReturns:
Item
β the item itself, if it was successfully added
copyTo(owner)
Clones the item and adds it to the specified owner, which can be either a
Item
or aProject
.Parameters:
owner:
Project
βLayer
βGroup
βCompoundPath
β the item or project to copy the item toReturns:
Item
β the new copy of the item, if it was successfully added
reduce(options)
If this is a group, layer or compound-path with only one child-item, the child-item is moved outside and the parent is erased. Otherwise, the item itself is returned unmodified.
Parameters:
options:
Returns:
Item
β the reduced item
remove()
Removes the item and all its children from the project. The item is not destroyed and can be inserted again after removal.
Returns:
Boolean
βtrue
if the item was removed,false
otherwise
replaceWith(item)
Replaces this item with the provided new item which will takes its place in the project hierarchy instead.
Parameters:
item:
Item
β the item that will replace this itemReturns:
Boolean
βtrue
if the item was replaced,false
otherwise
removeChildren()
Removes all of the itemβs
children
(if any).Returns:
Array of Item
objects β an array containing the removed items
removeChildren(start[, end])
Removes the children from the specified
start
index to and excluding theend
index from the parentβschildren
array.Parameters:
start:
Number
β the beginning index, inclusiveend:
Number
β the ending index, exclusive β optional, default:children.length
Returns:
Array of Item
objects β an array containing the removed items
reverseChildren()
Reverses the order of the itemβs children
Tests
isEmpty([recursively])
Specifies whether the item has any content or not. The meaning of what content is differs from type to type. For example, a
Group
with no children, aTextItem
with no text content and aPath
with no segments all are considered empty.Parameters:
recursively:
Boolean
β whether an item with children should be considered empty if all its descendants are empty β optional, default:false
Returns:
Boolean
Style Tests
hasFill()
Checks whether the item has a fill.
Returns:
Boolean
βtrue
if the item has a fill,false
otherwise
hasStroke()
Checks whether the item has a stroke.
Returns:
Boolean
βtrue
if the item has a stroke,false
otherwise
hasShadow()
Checks whether the item has a shadow.
Returns:
Boolean
βtrue
if the item has a shadow,false
otherwise
Hierarchy Tests
hasChildren()
Checks if the item contains any children items.
Returns:
Boolean
βtrue
it has one or more children,false
otherwise
isInserted()
Checks whether the item and all its parents are inserted into scene graph or not.
Returns:
Boolean
βtrue
if the item is inserted into the scene graph,false
otherwise
isAbove(item)
Checks if this item is above the specified item in the stacking order of the project.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if it is above the specified item,false
otherwise
isBelow(item)
Checks if the item is below the specified item in the stacking order of the project.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if it is below the specified item,false
otherwise
isParent(item)
Checks whether the specified item is the parent of the item.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if it is the parent of the item,false
otherwise
isChild(item)
Checks whether the specified item is a child of the item.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
it is a child of the item,false
otherwise
isDescendant(item)
Checks if the item is contained within the specified item.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if it is inside the specified item,false
otherwise
isAncestor(item)
Checks if the item is an ancestor of the specified item.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if the item is an ancestor of the specified item,false
otherwise
isSibling(item)
Checks if the item is an a sibling of the specified item.
Parameters:
item:
Item
β the item to check againstReturns:
Boolean
βtrue
if the item is aa sibling of the specified item,false
otherwise
isGroupedWith(item)
Checks whether the item is grouped with the specified item.
Parameters:
item:
Item
Returns:
Boolean
βtrue
if the items are grouped together,false
otherwise
Transform Functions
translate(delta)
Translates (moves) the item by the given offset views.
Parameters:
delta:
Point
β the offset to translate the item by
rotate(angle[, center])
Rotates the item by a given angle around the given center point.
Angles are oriented clockwise and measured in degrees.
Parameters:
angle:
Number
β the rotation anglecenter:
Point
β optional, default:item.position
See also:
matrix.rotate(angle[, center])
Example:Rotating an item:
Example:Rotating an item around a specific point:
scale(scale[, center])
Scales the item by the given value from its center point, or optionally from a supplied point.
Parameters:
scale:
Number
β the scale factorcenter:
Point
β optional, default:item.position
Example:Scaling an item from its center point:
Example:Scaling an item from a specific point:
scale(hor, ver[, center])
Scales the item by the given values from its center point, or optionally from a supplied point.
Parameters:
hor:
Number
β the horizontal scale factorver:
Number
β the vertical scale factorcenter:
Point
β optional, default:item.position
Example:Scaling an item horizontally by 300%:
shear(shear[, center])
Shears the item by the given value from its center point, or optionally by a supplied point.
Parameters:
shear:
Point
β the horizontal and vertical shear factors as a pointcenter:
Point
β optional, default:item.position
See also:
matrix.shear(shear[, center])
shear(hor, ver[, center])
Shears the item by the given values from its center point, or optionally by a supplied point.
Parameters:
hor:
Number
β the horizontal shear factorver:
Number
β the vertical shear factorcenter:
Point
β optional, default:item.position
See also:
matrix.shear(hor, ver[, center])
skew(skew[, center])
Skews the item by the given angles from its center point, or optionally by a supplied point.
Parameters:
skew:
Point
β the horizontal and vertical skew angles in degreescenter:
Point
β optional, default:item.position
See also:
matrix.shear(skew[, center])
skew(hor, ver[, center])
Skews the item by the given angles from its center point, or optionally by a supplied point.
Parameters:
hor:
Number
β the horizontal skew angle in degreesver:
Number
β the vertical sskew angle in degreescenter:
Point
β optional, default:item.position
See also:
matrix.shear(hor, ver[, center])
transform(matrix)
Transform the item.
Parameters:
matrix:
Matrix
β the matrix by which the item shall be transformed
globalToLocal(point)
Converts the specified point from global project coordinate space to the itemβs own local coordinate space.
Parameters:
point:
Point
β the point to be transformedReturns:
Point
β the transformed point as a new instance
localToGlobal(point)
Converts the specified point from the itemβs own local coordinate space to the global project coordinate space.
Parameters:
point:
Point
β the point to be transformedReturns:
Point
β the transformed point as a new instance
parentToLocal(point)
Converts the specified point from the parentβs coordinate space to itemβs own local coordinate space.
Parameters:
point:
Point
β the point to be transformedReturns:
Point
β the transformed point as a new instance
localToParent(point)
Converts the specified point from the itemβs own local coordinate space to the parentβs coordinate space.
Parameters:
point:
Point
β the point to be transformedReturns:
Point
β the transformed point as a new instance
fitBounds(rectangle[, fill])
Transform the item so that its
bounds
fit within the specified rectangle, without changing its aspect ratio.Parameters:
rectangle:
Rectangle
fill:
Boolean
β optional, default:false
Example:Fitting an item to the bounding rectangle of another item's bounding rectangle:
Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true:
Example:Fitting an item to the bounding rectangle of the view
Event Handling
on(type, function)
Attaches an event handler to the item.
Parameters:
type:
String
β the type of event:βframeβ
,mousedownβ
,βmouseupβ
,βmousedragβ
,βclickβ
,βdoubleclickβ
,βmousemoveβ
,βmouseenterβ
,βmouseleaveβ
function:
Function
β the function to be called when the event occurs, receiving aMouseEvent
orEvent
object as its sole argumentReturns:
Item
β this item itself, so calls can be chained
Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.
on(object)
Attaches one or more event handlers to the item.
Parameters:
object:
Object
β an object containing one or more of the following properties:frame
,mousedown
,mouseup
,mousedrag
,click
,doubleclick
,mousemove
,mouseenter
,mouseleave
Returns:
Item
β this item itself, so calls can be chained
Example:Change the fill color of the path to red when the mouse enters its shape and back to black again, when it leaves its shape.
Example:When you click the mouse, you create new circle shaped items. When you move the mouse over the item, its fill color is set to red. When you move the mouse outside again, its fill color is set black.
off(type, function)
Detach an event handler from the item.
Parameters:
type:
String
β the type of event:βframeβ
,mousedownβ
,βmouseupβ
,βmousedragβ
,βclickβ
,βdoubleclickβ
,βmousemoveβ
,βmouseenterβ
,βmouseleaveβ
function:
Function
β the function to be detachedReturns:
Item
β this item itself, so calls can be chained
off(object)
Detach one or more event handlers to the item.
Parameters:
object:
Object
β an object containing one or more of the following properties:frame
,mousedown
,mouseup
,mousedrag
,click
,doubleclick
,mousemove
,mouseenter
,mouseleave
Returns:
Item
β this item itself, so calls can be chained
emit(type, event)
Emit an event on the item.
Parameters:
type:
String
β the type of event:βframeβ
,mousedownβ
,βmouseupβ
,βmousedragβ
,βclickβ
,βdoubleclickβ
,βmousemoveβ
,βmouseenterβ
,βmouseleaveβ
event:
Object
β an object literal containing properties describing the eventReturns:
Boolean
βtrue
if the event had listeners,false
otherwise
responds(type)
Check if the item has one or more event handlers of the specified type.
Parameters:
type:
String
β the type of event:βframeβ
,mousedownβ
,βmouseupβ
,βmousedragβ
,βclickβ
,βdoubleclickβ
,βmousemoveβ
,βmouseenterβ
,βmouseleaveβ
Returns:
Boolean
βtrue
if the item has one or more event handlers of the specified type,false
otherwise
Remove On Event
removeOn(options)
Removes the item when the events specified in the passed options object occur.
Options:
options.move: undefined
β {Boolean) remove the item when the nexttool.onMouseMove
event is fired.options.drag: undefined
β {Boolena) remove the item when the nexttool.onMouseDrag
event is fired.options.down: undefined
β {Boolean) remove the item when the nexttool.onMouseDown
event is fired.options.up: undefined
β {Boolean) remove the item when the nexttool.onMouseUp
event is fired.Parameters:
options:
Object
Example:Click and drag below:
removeOnMove()
Removes the item when the next
tool.onMouseMove
event is fired.Example:Move your mouse below:
removeOnDown()
Removes the item when the next
tool.onMouseDown
event is fired.Example:Click a few times below:
removeOnDrag()
Removes the item when the next
tool.onMouseDrag
event is fired.Example:Click and drag below:
removeOnUp()
Removes the item when the next
tool.onMouseUp
event is fired.Example:Click a few times below:
Tweening Functions
tween(from, to, options)
Tween item between two states.
Options:
options.duration: Number
β the duration of the tweeningoptions.easing: Function
βString
β an easing function or the type of the easing:βlinearβ βeaseInQuadβ βeaseOutQuadβ βeaseInOutQuadβ βeaseInCubicβ βeaseOutCubicβ βeaseInOutCubicβ βeaseInQuartβ βeaseOutQuartβ βeaseInOutQuartβ βeaseInQuintβ βeaseOutQuintβ βeaseInOutQuintβ
β default:βlinearβ
options.start: Boolean
β whether to start tweening automatically β default:true
Parameters:
from:
Object
β the state at the start of the tweeningto:
Object
β the state at the end of the tweeningoptions:
Object
βNumber
β the options or the durationReturns:
Tween
Example:Tween fillColor:
Example:Tween rotation:
tween(to, options)
Tween item to a state.
Parameters:
to:
Object
β the state at the end of the tweeningoptions:
Object
βNumber
β the options or the durationReturns:
Tween
See also:
item.tween(from, to, options)
Example:Tween a nested property with relative values
tween(options)
Tween item.
Parameters:
options:
Object
βNumber
β the options or the durationReturns:
Tween
See also:
item.tween(from, to, options)
Example:Start an empty tween and just use the update callback:
tweenTo(to, options)
Tween item to a state.
Parameters:
to:
Object
β the state at the end of the tweeningoptions:
Object
βNumber
β the options or the durationReturns:
Tween
See also:
item.tween(to, options)
tweenFrom(from, options)
Tween item from a state to its state before the tweening.
Parameters:
from:
Object
β the state at the start of the tweeningoptions:
Object
βNumber
β the options or the durationReturns:
Tween
See also:
item.tween(from, to, options)
Example:Tween fillColor from red to the path's initial fillColor:
Properties inherited from PathItem
PathItem
interiorPoint
Returns a point that is guaranteed to be inside the path.
Read only.
Type:
Point
clockwise
Specifies whether the path as a whole is oriented clock-wise, by looking at the pathβs area. Note that self-intersecting paths and sub-paths of different orientation can result in areas that cancel each other out.
Type:
Boolean
See also:
path.area
compoundPath.area
pathData
The pathβs geometry, formatted as SVG style path data.
Type:
String
Methods inherited from PathItem
PathItem
Boolean Path Operations
unite(path[, options])
Unites the geometry of the specified path with this pathβs geometry and returns the result as a new path item.
Options:
options.insert: Boolean
β whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation β default:true
Parameters:
path:
PathItem
β the path to unite withoptions:
Object
β the boolean operation options β optionalReturns:
PathItem
β the resulting path item
intersect(path[, options])
Intersects the geometry of the specified path with this pathβs geometry and returns the result as a new path item.
Options:
options.insert: Boolean
β whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation β default:true
options.trace: Boolean
β whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections, keeping the parts of the curves that intersect with the area of the second path. β default:true
Parameters:
path:
PathItem
β the path to intersect withoptions:
Object
β the boolean operation options β optionalReturns:
PathItem
β the resulting path item
subtract(path[, options])
Subtracts the geometry of the specified path from this pathβs geometry and returns the result as a new path item.
Options:
options.insert: Boolean
β whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation β default:true
options.trace: Boolean
β whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections, removing the parts of the curves that intersect with the area of the second path. β default:true
Parameters:
path:
PathItem
β the path to subtractoptions:
Object
β the boolean operation options β optionalReturns:
PathItem
β the resulting path item
exclude(path[, options])
Excludes the intersection of the geometry of the specified path with this pathβs geometry and returns the result as a new path item.
Options:
options.insert: Boolean
β whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation β default:true
Parameters:
path:
PathItem
β the path to exclude the intersection ofoptions:
Object
β the boolean operation options β optionalReturns:
PathItem
β the resulting path item
divide(path[, options])
Splits the geometry of this path along the geometry of the specified path returns the result as a new group item. This is equivalent to calling
subtract(path)
andintersect(path)
and putting the results into a new group.Options:
options.insert: Boolean
β whether the resulting item should be inserted back into the scene graph, above both paths involved in the operation β default:true
options.trace: Boolean
β whether the tracing method is used, treating both paths as areas when determining which parts of the paths are to be kept in the result, or whether the first path is only to be split at intersections. β default:true
Parameters:
path:
PathItem
β the path to divide byoptions:
Object
β the boolean operation options β optionalReturns:
PathItem
β the resulting path item
reorient([nonZero[, clockwise]])
Fixes the orientation of the sub-paths of a compound-path, assuming that non of its sub-paths intersect, by reorienting them so that they are of different winding direction than their containing paths, except for disjoint sub-paths, i.e. islands, which are oriented so that they have the same winding direction as the the biggest path.
Parameters:
nonZero:
Boolean
β controls if the non-zero fill-rule is to be applied, by counting the winding of each nested path and discarding sub-paths that do not contribute to the final result β optional, default:false
clockwise:
Boolean
β if provided, the orientation of the root paths will be set to the orientation specified byclockwise
, otherwise the orientation of the largest root child is used. β optionalReturns:
PathItem
β a reference to the item itself, reoriented
Path Intersections and Locations
getIntersections(path[, include])
Returns all intersections between two
PathItem
items as an array ofCurveLocation
objects.CompoundPath
items are also supported.Parameters:
path:
PathItem
β the other item to find the intersections withinclude:
Function
β a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall returntrue
to include a location,false
otherwise. β optionalReturns:
Array of CurveLocation
objects β the locations of all intersection between the pathsSee also:
getCrossings(path)
Example:Finding the intersections between two paths
getCrossings(path)
Returns all crossings between two
PathItem
items as an array ofCurveLocation
objects.CompoundPath
items are also supported. Crossings are intersections where the paths actually are crossing each other, as opposed to simply touching.Parameters:
path:
PathItem
β the other item to find the crossings withReturns:
Array of CurveLocation
objects β the locations of all crossings between the pathsSee also:
getIntersections(path)
getNearestLocation(point)
Returns the nearest location on the path item to the specified point.
Parameters:
point:
Point
β the point for which we search the nearest locationReturns:
CurveLocation
β the location on the path thatβs the closest to the specified point
getNearestPoint(point)
Returns the nearest point on the path item to the specified point.
Parameters:
point:
Point
β the point for which we search the nearest pointReturns:
Point
β the point on the path thatβs the closest to the specified point
Example: