<p>A compound path is a complex path that is made up of one or more simple sub-paths. It can have the <code>nonzero</code> fill rule, or the <code>evenodd</code> rule applied. Both rules use mathematical equations to determine if any region is outside or inside the final shape. The <code>evenodd</code> rule is more predictable: Every other region within a such a compound path is a hole, regardless of path direction.</p>
<p>All the paths in a compound path take on the style of the compound path and can be accessed through its <ahref="../classes/Item.html#children"><tt>item.children</tt></a> list.</p>
<p>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.</p>
<p>Specifies whether the item is selected. This will also return <code>true</code> for <ahref="../classes/Group.html"><tt>Group</tt></a> items if they are partially selected, e.g. groups containing selected or partially selected paths.</p>
<p>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.</p>
<p>Specifies whether the item defines a clip mask. This can only be set on paths, compound paths, and text frame objects, and only if the item is already contained within a clipping group.</p>
<p>The item’s position within the parent item’s coordinate system. By default, this is the <ahref="../classes/Rectangle.html#center"><tt>rectangle.center</tt></a> of the item’s <ahref="../classes/Item.html#bounds"><tt>bounds</tt></a> rectangle.</p>
<ulclass="member-list">
<h4>Type:</h4>
<li>
<ahref="../classes/Point.html"><tt>Point</tt></a>
</li>
</ul>
<h4>Example:<spanclass="description">Changing the position of a path:</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-10">
// Create a circle at position { x: 10, y: 10 }
var circle = new Path.Circle({
center: new Point(10, 10),
radius: 10,
fillColor: 'red'
});
// Move the circle to { x: 20, y: 20 }
circle.position = new Point(20, 20);
// Move the circle 100 points to the right and 50 points down
<p>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 <ahref="../classes/Item.html#position"><tt>position</tt></a>. By default, it is set to <code>null</code>, meaning the <ahref="../classes/Rectangle.html#center"><tt>rectangle.center</tt></a> of the item’s <ahref="../classes/Item.html#bounds"><tt>bounds</tt></a> rectangle is used as pivot.</p>
<p>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.</p>
<p>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.</p>
<p>Controls whether the transformations applied to the item (e.g. through <ahref="../classes/Item.html#transform-matrix"><tt>transform(matrix)</tt></a>, <ahref="../classes/Item.html#rotate-angle"><tt>rotate(angle)</tt></a>, <ahref="../classes/Item.html#scale-scale"><tt>scale(scale)</tt></a>, etc.) are stored in its <ahref="../classes/Item.html#matrix"><tt>matrix</tt></a> property, or whether they are directly applied to its contents or children (passed on to the segments in <ahref="../classes/Path.html"><tt>Path</tt></a> items, the children of <ahref="../classes/Group.html"><tt>Group</tt></a> items, etc.).</p>
<p>The children items contained within this item. Items that define a <ahref="../classes/Item.html#name"><tt>name</tt></a> can also be accessed by name.</p>
<p><b>Please note:</b> The children array should not be modified directly using array functions. To remove single items from the children list, use <ahref="../classes/Item.html#remove"><tt>item.remove</tt></a>(), to remove all items from the children list, use <ahref="../classes/Item.html#removechildren"><tt>item.removeChildren</tt></a>(). To add items to the children list, use <ahref="../classes/Item.html#addchild-item"><tt>item.addChild(item)</tt></a> or <ahref="../classes/Item.html#insertchild-index-item"><tt>item.insertChild(index, item)</tt></a>.</p>
<ulclass="member-list">
<h4>Type:</h4>
<li>
Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects
</li>
</ul>
<h4>Example:<spanclass="description">Accessing items in the children array:</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-12">
var path = new Path.Circle({
center: [80, 50],
radius: 35
});
// Create a group and move the path into it:
var group = new Group();
group.addChild(path);
// Access the path through the group's children array:
<p>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.</p>
<p>The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for <ahref="../classes/Item.html#strokejoin"><tt>item.strokeJoin</tt></a>, it is possible for the miter to extend far beyond the <ahref="../classes/Item.html#strokewidth"><tt>item.strokeWidth</tt></a> of the path. The miterLimit imposes a limit on the ratio of the miter length to the <ahref="../classes/Item.html#strokewidth"><tt>item.strokeWidth</tt></a>.</p>
<p>The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than <code>'nonzero'</code>.</p>
<p>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.</p>
<p>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:</p>
<ulclass="member-list">
<h4>Type:</h4>
<li>
<tt>Function</tt>
</li>
</ul>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>event.count: <tt>Number</tt></tt>— the number of times the frame event was fired</li>
<li><tt>event.time: <tt>Number</tt></tt>— the total amount of time passed since the first frame event in seconds</li>
<li><tt>event.delta: <tt>Number</tt></tt>— the time passed in seconds since the last frame event</li>
<p>The function to be called when the mouse button is pushed down on the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>The function to be called when the mouse position changes while the mouse is being dragged over the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>The function to be called when the mouse button is released over the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>The function to be called when the mouse clicks on the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>The function to be called when the mouse double clicks on the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>The function to be called repeatedly while the mouse moves over the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<p>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 <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<h4>Example:<spanclass="description">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.</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-32">
// Create a circle shaped path at the center of the view:
var path = new Path.Circle({
center: view.center,
radius: 25,
fillColor: 'black'
});
// When the mouse enters the item, set its fill color to red:
path.onMouseEnter = function(event) {
this.fillColor = 'red';
}
// When the mouse leaves the item, set its fill color to black:
<h4>Example:<spanclass="description">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.</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-33">
function enter(event) {
this.fillColor = 'red';
}
function leave(event) {
this.fillColor = 'black';
}
// When the mouse is pressed:
function onMouseDown(event) {
// Create a circle shaped path at the position of the mouse:
var path = new Path.Circle(event.point, 25);
path.fillColor = 'black';
// When the mouse enters the item, set its fill color to red:
path.onMouseEnter = enter;
// When the mouse leaves the item, set its fill color to black:
<p>The function to be called when the mouse moves out of the item. The function receives a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> 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 with <ahref="../classes/Event.html#stoppropagation"><tt>event.stopPropagation</tt></a>() or by returning <code>false</code> from the handler.</p>
<h4>Example:<spanclass="description">Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-34">
// Create a circle shaped path at the center of the view:
var path = new Path.Circle({
center: view.center,
radius: 25,
fillColor: 'black'
});
// When the mouse leaves the item, set its fill color to red:
<p>Sets those 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).</p>
<p>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.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>source:</tt>
<ahref="../classes/Item.html"><tt>Item</tt></a>
— the item to copy the attributes from
</li>
<li>
<tt>excludeMatrix:</tt>
<tt>Boolean</tt>
— whether to exclude the transformation matrix when copying all attributes
<p>Perform a hit-test on the item (and its children, if it is a <ahref="../classes/Group.html"><tt>Group</tt></a> or <ahref="../classes/Layer.html"><tt>Layer</tt></a>) at the location of the specified point.</p>
<p>The options object allows you to control the specifics of the hit-test and may contain a combination of the following values:</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.tolerance: <tt>Number</tt></tt>— the tolerance of the hit-test — default: <tt><ahref="../classes/PaperScope.html#settings"><tt>paperScope.settings</tt></a>.hitTolerance</tt></li>
<li><tt>options.class: <tt>Function</tt></tt>— only hit-test again a certain item class and its sub-classes: <tt>Group</tt>, <tt>Layer</tt>, <tt>Path</tt>, <tt>CompoundPath</tt>, <tt>Shape</tt>, <tt>Raster</tt>, <tt>SymbolItem</tt>, <tt>PointText</tt>, …</li>
<li><tt>options.fill: <tt>Boolean</tt></tt>— hit-test the fill of items</li>
<li><tt>options.stroke: <tt>Boolean</tt></tt>— hit-test the stroke of path and shape items, taking into account the setting of stroke color and width</li>
<li><tt>options.segments: <tt>Boolean</tt></tt>— hit-test for <ahref="../classes/Segment.html#point"><tt>segment.point</tt></a> of <ahref="../classes/Path.html"><tt>Path</tt></a> items</li>
<li><tt>options.curves: <tt>Boolean</tt></tt>— hit-test the curves of path items, without taking the stroke color or width into account</li>
<li><tt>options.handles: <tt>Boolean</tt></tt>— hit-test for the handles (<ahref="../classes/Segment.html#handlein"><tt>segment.handleIn</tt></a> / <ahref="../classes/Segment.html#handleout"><tt>segment.handleOut</tt></a>) of path segments</li>
<li><tt>options.ends: <tt>Boolean</tt></tt>— only hit-test for the first or last segment points of open path items</li>
<li><tt>options.bounds: <tt>Boolean</tt></tt>— hit-test the corners and side-centers of the bounding rectangle of items (<ahref="../classes/Item.html#bounds"><tt>item.bounds</tt></a>)</li>
<li><tt>options.center: <tt>Boolean</tt></tt>— hit-test the <ahref="../classes/Rectangle.html#center"><tt>rectangle.center</tt></a> of the bounding rectangle of items (<ahref="../classes/Item.html#bounds"><tt>item.bounds</tt></a>)</li>
<li><tt>options.guides: <tt>Boolean</tt></tt>— hit-test items that have <tt>Item#guide</tt> set to <code>true</code></li>
<li><tt>options.selected: <tt>Boolean</tt></tt>— only hit selected items</li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>point:</tt>
<ahref="../classes/Point.html"><tt>Point</tt></a>
— the point where the hit-test should be performed
<tt><ahref="../classes/HitResult.html"><tt>HitResult</tt></a></tt> — a hit result object that contains more information about what exactly was hit or <code>null</code> if nothing was hit
<p>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 <ahref="../classes/Item.html#matches-name-compare"><tt>matches(name, compare)</tt></a>.</p>
<p>See <ahref="../classes/Project.html#getitems-match"><tt>project.getItems(match)</tt></a> for a selection of illustrated examples.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>match:</tt>
<tt>Object</tt>⟋<tt>Function</tt>
— the criteria to match against
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><tt>Boolean</tt></tt> — <tt>true</tt> if the item matches all the criteria, <tt>false</tt> otherwise
<p>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 <ahref="../classes/Item.html#data"><tt>item.data</tt></a>.</p>
<p>See <ahref="../classes/Project.html#getitems-match"><tt>project.getItems(match)</tt></a> for a selection of illustrated examples.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>name:</tt>
<tt>String</tt>
— the name of the state to match against
</li>
<li>
<tt>compare:</tt>
<tt>Object</tt>
— the value, function or regular expression to compare against
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><tt>Boolean</tt></tt> — <tt>true</tt> if the item matches the state, <tt>false</tt> otherwise
<p>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 <ahref="../classes/Item.html#data"><tt>item.data</tt></a>.</p>
<p>Matching items against a rectangular area is also possible, by setting either <code>match.inside</code> or <code>match.overlapping</code> to a rectangle describing the area in which the items either have to be fully or partly contained.</p>
<p>See <ahref="../classes/Project.html#getitems-match"><tt>project.getItems(match)</tt></a> for a selection of illustrated examples.</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>match.recursive: <tt>Boolean</tt></tt>— whether to loop recursively through all children, or stop at the current level — default: <tt>true</tt></li>
<li><tt>match.match: <tt>Function</tt></tt>— 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 the <code>match</code> object</li>
<li><tt>match.class: <tt>Function</tt></tt>— the constructor function of the item type to match against</li>
<li><tt>match.inside: <ahref="../classes/Rectangle.html"><tt>Rectangle</tt></a></tt>— the rectangle in which the items need to be fully contained</li>
<li><tt>match.overlapping: <ahref="../classes/Rectangle.html"><tt>Rectangle</tt></a></tt>— the rectangle with which the items need to at least partly overlap</li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>match:</tt>
<tt>Object</tt>⟋<tt>Function</tt>
— the criteria to match against
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt>Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects</tt> — the list of matching descendant items
<p>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 <ahref="../classes/Item.html#data"><tt>item.data</tt></a>. See <ahref="../classes/Project.html#getitems-match"><tt>project.getItems(match)</tt></a> for a selection of illustrated examples.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>match:</tt>
<tt>Object</tt>⟋<tt>Function</tt>
— the criteria to match against
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — the first descendant item matching the given criteria
<p>Exports (serializes) the item with its content and child items to a JSON data string.</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.asString: <tt>Boolean</tt></tt>— whether the JSON is returned as a <code>Object</code> or a <code>String</code>— default: <tt>true</tt></li>
<li><tt>options.precision: <tt>Number</tt></tt>— the amount of fractional digits in numbers used in JSON data — default: <tt>5</tt></li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>options:</tt>
<tt>Object</tt>
— the serialization options
— optional
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><tt>String</tt></tt> — the exported JSON data
<p>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 <ahref="../classes/Item.html#children"><tt>item.children</tt></a> list. Note that not all type of items can have children.</p>
<p>Exports the item with its content and child items as an SVG DOM.</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.asString: <tt>Boolean</tt></tt>— whether a SVG node or a <code>String</code> is to be returned — default: <tt>false</tt></li>
<li><tt>options.precision: <tt>Number</tt></tt>— the amount of fractional digits in numbers used in SVG data — default: <tt>5</tt></li>
<li><tt>options.matchShapes: <tt>Boolean</tt></tt>— whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: <tt>false</tt></li>
<li><tt>options.embedImages: <tt>Boolean</tt></tt>— whether raster images should be embedded as base64 data inlined in the xlink:href attribute, or kept as a link to their external URL. — default: <tt>true</tt></li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>options:</tt>
<tt>Object</tt>
— the export options
— optional
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><tt>SVGElement</tt></tt> — the item converted to an SVG node
<p>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 <ahref="../classes/Item.html#removechildren"><tt>item.removeChildren</tt></a>() to do so.</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.expandShapes: <tt>Boolean</tt></tt>— whether imported shape items should be expanded to path items — default: <tt>false</tt></li>
<li><tt>options.onLoad: <tt>Function</tt></tt>— the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted <code>item</code> and the original <code>svg</code> data as a string. Only required when loading from external files.</li>
<li><tt>options.applyMatrix: <tt>Boolean</tt></tt>— whether imported items should have their transformation matrices applied to their contents or not — default: <tt><ahref="../classes/PaperScope.html#settings"><tt>paperScope.settings</tt></a>.applyMatrix</tt></li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>svg:</tt>
<tt>SVGElement</tt>⟋<tt>String</tt>
— 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.
</li>
<li>
<tt>options:</tt>
<tt>Object</tt>
— the import options
— optional
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — the newly created Paper.js item containing the converted SVG content
<p>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 <ahref="../classes/Item.html#removechildren"><tt>item.removeChildren</tt></a>() to do so.</p>
— the callback function to call once the SVG content is loaded from the given URL receiving two arguments: the converted <code>item</code> and the original <code>svg</code> data as a string. Only required when loading from external files.
<p>Adds the specified item as a child of this item at the end of the its <ahref="../classes/Item.html#children"><tt>children</tt></a> list. You can use this function for groups, compound paths and layers.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>item:</tt>
<ahref="../classes/Item.html"><tt>Item</tt></a>
— the item to be added as a child
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — the added item, or <code>null</code> if adding was not possible
<p>Inserts the specified item as a child of this item at the specified index in its <ahref="../classes/Item.html#children"><tt>children</tt></a> list. You can use this function for groups, compound paths and layers.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>index:</tt>
<tt>Number</tt>
— the index at which to insert the item
</li>
<li>
<tt>item:</tt>
<ahref="../classes/Item.html"><tt>Item</tt></a>
— the item to be inserted as a child
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — the inserted item, or <code>null</code> if inserting was not possible
<p>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.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>items:</tt>
Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects
— the items to be added as children
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt>Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects</tt> — the added items, or <code>null</code> if adding was not possible
<p>Inserts the specified items as children of this item at the specified index in its <ahref="../classes/Item.html#children"><tt>children</tt></a> list. You can use this function for groups, compound paths and layers.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>index:</tt>
<tt>Number</tt>
</li>
<li>
<tt>items:</tt>
Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects
— the items to be appended as children
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt>Array of <ahref="../classes/Item.html"><tt>Item</tt></a> objects</tt> — the inserted items, or <code>null</code> if inserted was not possible
<p>Inserts the specified item as a child of this item by appending it to the list of children and moving it above all other children. You can use this function for groups, compound paths and layers.</p>
<p>Inserts the specified item as a child of this item by appending it to the list of children and moving it below all other children. You can use this function for groups, compound paths and layers.</p>
<p>When passed a project, copies the item to the project, or duplicates it within the same project. When passed an item, copies the item into the specified item.</p>
<p>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.</p>
<p>Removes the children from the specified <code>start</code> index to and excluding the <code>end</code> index from the parent’s <ahref="../classes/Item.html#children"><tt>children</tt></a> array.</p>
<p>Specifies whether the item has any content or not. The meaning of what content is differs from type to type. For example, a <ahref="../classes/Group.html"><tt>Group</tt></a> with no children, a <ahref="../classes/TextItem.html"><tt>TextItem</tt></a> with no text content and a <ahref="../classes/Path.html"><tt>Path</tt></a> with no segments all are considered empty.</p>
<p>Transform the item so that its <ahref="../classes/Item.html#bounds"><tt>bounds</tt></a> fit within the specified rectangle, without changing its aspect ratio.</p>
<h4>Example:<spanclass="description">Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true:</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-45">
// Create a rectangle shaped path with its top left corner
// at {x: 80, y: 25} and a size of {width: 75, height: 50}:
var path = new Path.Rectangle({
point: [80, 25],
size: [75, 50],
fillColor: 'black'
});
// Create a circle shaped path with its center at {x: 80, y: 50}
// and a radius of 30.
var circlePath = new Path.Circle({
center: [80, 50],
radius: 30,
fillColor: 'red'
});
// Fit the circlePath to the bounding rectangle of
— the type of event: <tt>‘frame’</tt>, <tt>mousedown’</tt>, <tt>‘mouseup’</tt>, <tt>‘mousedrag’</tt>, <tt>‘click’</tt>, <tt>‘doubleclick’</tt>, <tt>‘mousemove’</tt>, <tt>‘mouseenter’</tt>, <tt>‘mouseleave’</tt>
</li>
<li>
<tt>function:</tt>
<tt>Function</tt>
— the function to be called when the event occurs, receiving a <ahref="../classes/MouseEvent.html"><tt>MouseEvent</tt></a> or <ahref="../classes/Event.html"><tt>Event</tt></a> object as its sole argument
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — this item itself, so calls can be chained
</li>
</ul>
<h4>Example:<spanclass="description">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.</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-47">
// Create a circle shaped path at the center of the view:
var path = new Path.Circle({
center: view.center,
radius: 25,
fillColor: 'black'
});
// When the mouse enters the item, set its fill color to red:
path.on('mouseenter', function() {
this.fillColor = 'red';
});
// When the mouse leaves the item, set its fill color to black:
<p>Attaches one or more event handlers to the item.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>object:</tt>
<tt>Object</tt>
— an object literal containing one or more of the following properties: <tt>frame</tt>, <tt>mousedown</tt>, <tt>mouseup</tt>, <tt>mousedrag</tt>, <tt>click</tt>, <tt>doubleclick</tt>, <tt>mousemove</tt>, <tt>mouseenter</tt>, <tt>mouseleave</tt>
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — this item itself, so calls can be chained
</li>
</ul>
<h4>Example:<spanclass="description">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.</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-48">
// Create a circle shaped path at the center of the view:
var path = new Path.Circle({
center: view.center,
radius: 25
});
path.fillColor = 'black';
// When the mouse enters the item, set its fill color to red:
<h4>Example:<spanclass="description">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.</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-49">
var pathHandlers = {
mouseenter: function(event) {
this.fillColor = 'red';
},
mouseleave: function(event) {
this.fillColor = 'black';
}
}
// When the mouse is pressed:
function onMouseDown(event) {
// Create a circle shaped path at the position of the mouse:
var path = new Path.Circle({
center: event.point,
radius: 25,
fillColor: 'black'
});
// Attach the handers inside the object literal to the path:
<p>Detach one or more event handlers to the item.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>object:</tt>
<tt>Object</tt>
— an object literal containing one or more of the following properties: <tt>frame</tt>, <tt>mousedown</tt>, <tt>mouseup</tt>, <tt>mousedrag</tt>, <tt>click</tt>, <tt>doubleclick</tt>, <tt>mousemove</tt>, <tt>mouseenter</tt>, <tt>mouseleave</tt>
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/Item.html"><tt>Item</tt></a></tt> — this item itself, so calls can be chained
<p>Removes the item when the events specified in the passed options object occur.</p>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.move: undefined</tt>— {Boolean) remove the item when the next <ahref="../classes/Tool.html#onmousemove"><tt>tool.onMouseMove</tt></a> event is fired.</li>
<li><tt>options.drag: undefined</tt>— {Boolena) remove the item when the next <ahref="../classes/Tool.html#onmousedrag"><tt>tool.onMouseDrag</tt></a> event is fired.</li>
<li><tt>options.down: undefined</tt>— {Boolean) remove the item when the next <ahref="../classes/Tool.html#onmousedown"><tt>tool.onMouseDown</tt></a> event is fired.</li>
<li><tt>options.up: undefined</tt>— {Boolean) remove the item when the next <ahref="../classes/Tool.html#onmouseup"><tt>tool.onMouseUp</tt></a> event is fired.</li>
</ul>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>options:</tt>
<tt>Object</tt>
</li>
</ul>
<h4>Example:<spanclass="description">Click and drag below:</span></h4>
<divclass="paperscript split">
<divclass="buttons">
<divclass="button run">Run</div>
</div>
<scripttype="text/paperscript"canvas="canvas-50">
function onMouseDrag(event) {
// Create a circle shaped path at the mouse position,
// with a radius of 10:
var path = new Path.Circle({
center: event.point,
radius: 10,
fillColor: 'black'
});
// Remove the path on the next onMouseDrag or onMouseDown event:
<p>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 <ahref="../classes/PathItem.html#subtract-path"><tt>subtract(path)</tt></a> and <ahref="../classes/PathItem.html#subtract-path"><tt>subtract(path)</tt></a> and putting the results into a new group.</p>
<p>Returns all intersections between two <ahref="../classes/PathItem.html"><tt>PathItem</tt></a> items as an array of <ahref="../classes/CurveLocation.html"><tt>CurveLocation</tt></a> objects. <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a> items are also supported.</p>
— the other item to find the intersections with
</li>
<li>
<tt>include:</tt>
<tt>Function</tt>
— a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall return <tt>true</tt> to include a location, <tt>false</tt> otherwise.
— optional
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt>Array of <ahref="../classes/CurveLocation.html"><tt>CurveLocation</tt></a> objects</tt> — the locations of all intersection between the paths
<p>Returns all crossings between two <ahref="../classes/PathItem.html"><tt>PathItem</tt></a> items as an array of <ahref="../classes/CurveLocation.html"><tt>CurveLocation</tt></a> objects. <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a> items are also supported. Crossings are intersections where the paths actually are crossing each other, as opposed to simply touching.</p>
<p>Returns the nearest location on the path item to the specified point.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>point:</tt>
<ahref="../classes/Point.html"><tt>Point</tt></a>
— the point for which we search the nearest location
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><ahref="../classes/CurveLocation.html"><tt>CurveLocation</tt></a></tt> — the location on the path that’s the closest to the specified point
<p>Reverses the orientation of the path item. When called on <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a> items, each of the nested paths is reversed. On <ahref="../classes/Path.html"><tt>Path</tt></a> items, the sequence of <ahref="../classes/Path.html#segments"><tt>path.segments</tt></a> is reversed.</p>
<p>Converts the curves in a path to straight lines with an even distribution of points. The distance between the produced segments is as close as possible to the value specified by the <code>maxDistance</code> parameter.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>maxDistance:</tt>
<tt>Number</tt>
— the maximum distance between the points
</li>
</ul>
<h4>Example:<spanclass="description">Flattening a circle shaped path:</span></h4>
<p>Smooths the path item without changing the amount of segments in the path or moving the segments’ locations, by smoothing and adjusting the angle and length of the segments’ handles based on the position and distance of neighboring segments.</p>
<p>Smoothing works both for open paths and closed paths, and can be applied to the full path, as well as a sub-range of it. If a range is defined using the <code>options.from</code> and <code>options.to</code> properties, only the curve handles inside that range are touched. If one or both limits of the range are specified in negative indices, the indices are wrapped around the end of the curve. That way, a smoothing range in a close path can even wrap around the connection between the last and the first segment.</p>
<p>Four different smoothing methods are available:</p>
<ul>
<li>
<p><code>'continuous'</code> smooths the path item by adjusting its curve handles so that the first and second derivatives of all involved curves are continuous across their boundaries.</p>
<p>This method tends to result in the smoothest results, but does not allow for further parametrization of the handles.</p>
</li>
<li>
<p><code>'asymmetric'</code> is based on the same principle as <code>'continuous'</code> but uses different factors so that the result is asymmetric. This used to the only method available until v0.10.0, and is currently still the default when no method is specified, for reasons of backward compatibility. It will eventually be removed.</p></li>
<li>
<p><code>'catmull-rom'</code> uses the Catmull-Rom spline to smooth the segment.</p>
<p>The optionally passed factor controls the knot parametrization of the algorithm:</p>
<ul>
<li><code>0.0</code>: the standard, uniform Catmull-Rom spline</li>
<li><code>0.5</code>: the centripetal Catmull-Rom spline, guaranteeing no self-intersections</li>
<li><code>1.0</code>: the chordal Catmull-Rom spline</li>
</ul>
</li>
<li>
<p><code>'geometric'</code> use a simple heuristic and empiric geometric method to smooth the segment’s handles. The handles were weighted, meaning that big differences in distances between the segments will lead to probably undesired results.</p>
<p>The optionally passed factor defines the tension parameter (<code>0…1</code>), controlling the amount of smoothing as a factor by which to scale each handle.</p>
</li>
</ul>
<ulclass="member-list">
<h4>Options:</h4>
<li><tt>options.type: <tt>String</tt></tt>— the type of smoothing method: <tt>‘continuous’</tt>, <tt>‘asymmetric’</tt>, <tt>‘catmull-rom’</tt>, <tt>‘geometric’</tt>— default: <tt>‘asymmetric’</tt></li>
<li><tt>options.factor: <tt>Number</tt></tt>— the factor parameterizing the smoothing method — default: <code>0.5</code> for <code>'catmull-rom'</code>, <code>0.4</code> for <code>'geometric'</code></li>
<li><tt>options.from: <tt>Number</tt>⟋<ahref="../classes/Segment.html"><tt>Segment</tt></a>⟋<ahref="../classes/Curve.html"><tt>Curve</tt></a></tt>— the segment or curve at which to start smoothing, if not the full path shall be smoothed (inclusive). This can either be a segment index, or a segment or curve object that is part of the path. If the passed number is negative, the index is wrapped around the end of the path.</li>
<li><tt>options.to: <tt>Number</tt>⟋<ahref="../classes/Segment.html"><tt>Segment</tt></a>⟋<ahref="../classes/Curve.html"><tt>Curve</tt></a></tt>— the segment or curve to which the handles of the path shall be processed (inclusive). This can either be a segment index, or a segment or curve object that is part of the path. If the passed number is negative, the index is wrapped around the end of the path.</li>
<p>Fits a sequence of as few curves as possible through the path’s anchor points, ignoring the path items’s curve-handles, with an allowed maximum error. When called on <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a> items, each of the nested paths is simplified. On <ahref="../classes/Path.html"><tt>Path</tt></a> items, the <ahref="../classes/Path.html#segments"><tt>path.segments</tt></a> array is processed and replaced by the resulting sequence of fitted curves.</p>
<p>This method can be used to process and simplify the point data received from a mouse or touch device.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>tolerance:</tt>
<tt>Number</tt>
— the allowed maximum error when fitting the curves through the segment points
— optional, default: <tt>2.5</tt>
</li>
</ul>
<ulclass="member-list">
<h4>Returns:</h4>
<li>
<tt><tt>Boolean</tt></tt> — <tt>true</tt> if the method was capable of fitting curves through the path’s segment points, <tt>false</tt> otherwise
</li>
</ul>
<h4>Example:<spanclass="description">Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify():</span></h4>
<aname="interpolate-from-to-factor"href="#interpolate-from-to-factor"><tt><b>interpolate</b>(from, to, factor)</tt></a>
</div>
<divclass="member-description hidden">
<divclass="member-text">
<p>Interpolates between the two specified path items and uses the result as the geometry for this path item. The number of children and segments in the two paths involved in the operation should be the same.</p>
<p>On a normal empty <ahref="../classes/Path.html"><tt>Path</tt></a>, the point is simply added as the path’s first segment. If called on a <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a>, a new <ahref="../classes/Path.html"><tt>Path</tt></a> is created as a child and the point is added as its first segment.</p>
<p>Draws a curve from the position of the last segment point in the path that goes through the specified <code>through</code> point, to the specified <code>to</code> point by adding one segment to the path.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>through:</tt>
<ahref="../classes/Point.html"><tt>Point</tt></a>
— the point through which the curve should go
</li>
<li>
<tt>to:</tt>
<ahref="../classes/Point.html"><tt>Point</tt></a>
— the point where the curve should end
</li>
<li>
<tt>parameter:</tt>
<tt>Number</tt>
— optional, default: <tt>0.5</tt>
</li>
</ul>
<h4>Example:<spanclass="description">Interactive example. Move your mouse around the view below:</span></h4>
<p>Draws an arc from the position of the last segment point in the path that goes through the specified <code>through</code> point, to the specified <code>to</code> point by adding one or more segments to the path.</p>
<ulclass="member-list">
<h4>Parameters:</h4>
<li>
<tt>through:</tt>
<ahref="../classes/Point.html"><tt>Point</tt></a>
— the point where the arc should pass through
<p>If called on a <ahref="../classes/CompoundPath.html"><tt>CompoundPath</tt></a>, a new <ahref="../classes/Path.html"><tt>Path</tt></a> is created as a child and a point is added as its first segment relative to the position of the last segment of the current path.</p>
Copyright © 2011—2016 <ahref="http://www.lehni.org"target="_blank">Jürg Lehni</a>&<ahref="http://www.jonathanpuckey.com"target="_blank">Jonathan Puckey</a>. All Rights Reserved.</p>
