Creates a new path item and places it at the top of the active layer.
Example — Create an empty path and add segments to it:
var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 30)); path.add(new Point(100, 100));
Example — Create a path with two segments:
var segments = [new Point(30, 30), new Point(100, 100)]; var path = new Path(segments); path.strokeColor = 'black';
Creates a new path item from an object description and places it at the top of the active layer.
Example
Example
Creates a new path item from SVG path-data and places it at the top of the active layer.
Example
Creates a linear path item from the properties described by an object literal.
Example
Creates a circular path item from the properties described by an object literal.
Example
Creates a rectangular path item, with optionally rounded corners.
Example
Example — The same, with rounder corners
Creates a rectangular path item from the passed points. These do not necessarily need to be the top left and bottom right corners, the constructor figures out how to fit a rectangle between them.
Example
Creates a rectangular path item from the properties described by an object literal.
Example
Example
Example
Example
Creates an elliptical path item from the properties described by an object literal.
Example
Example — Placing by center and radius
Creates an circular arc path item from the properties described by an object literal.
Example
Creates a regular polygon shaped path item from the properties described by an object literal.
Example
Creates a star shaped path item.
The largest of radius1 and radius2 will be the outer radius of the star. The smallest of radius1 and radius2 will be the inner radius.
Example
Creates a star shaped path item from the properties described by an object literal.
Example
Specifies whether the path is closed. If it is closed, Paper.js connects the first and last segments.
Example
The approximate length of the path.
Read only.
The area that the path's geometry is covering. Self-intersecting paths can contain sub-areas that cancel each other out.
Read only.
Specifies whether the path is oriented clock-wise.
Specifies whether the path and all its segments are selected. Cannot be true on an empty path.
Example — A path is fully selected, if all of its segments are selected:
Adds one or more segments to the end of the segments array of this path.
Example — Adding segments to a path using point objects:
Example — Adding segments to a path using arrays containing number pairs:
Example — Adding segments to a path using objects:
Example — Adding a segment with handles to a path:
Inserts one or more segments at a given index in the list of this path's segments.
Example — Inserting a segment:
Example — Inserting multiple segments:
Adds an array of segments (or types that can be converted to segments) to the end of the segments array.
Example — Adding an array of Point objects:
Example — Adding an array of [x, y] arrays:
Example — Adding segments from one path to another:
Inserts an array of segments at a given index in the path's segments array.
Removes the segments from the specified from index to the to index from the path's segments array.
Example — Removing segments from a path:
Checks if any of the curves in the path have curve handles set.
See also: segment.hasHandles(), curve.hasHandles()
Clears the path's handles by setting their coordinates to zero, turning the path into a polygon (or a polyline if it isn't closed).
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 maxDistance parameter.
Example — Flattening a circle shaped path:
Reduces the path by removing curves that have a length of 0, and unnecessary segments between two collinear curves.
Smooths a path by simplifying it. The path.segments array is analyzed and replaced by a more optimal set of segments, reducing memory usage and speeding up drawing.
Example — Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify():
Splits the path at the given offset. After splitting, the path will be open. If the path was open already, splitting will result in two paths.
Example — Splitting an open path
Example — Splitting a closed path
Splits the path at the given curve location. After splitting, the path will be open. If the path was open already, splitting will result in two paths.
Example
Splits the path at the given curve index and parameter. After splitting, the path will be open. If the path was open already, splitting will result in two paths.
Example — Splitting an open path Draw a V shaped path:
Example — Splitting a closed path
Reverses the orientation of the path, by reversing all its segments.
Joins the path with the specified path, which will be removed in the process.
Example — Joining two paths:
Example — Joining two paths that share a point at the start or end of their segments array:
Example — Joining two paths that connect at two points:
Attempts to create a new shape item with same geometry as this path item, and inherits all settings from it, similar to item.clone().
See also: shape.toPath(insert)
Returns the curve location of the specified point if it lies on the path, null otherwise.
Returns the length of the path from its beginning up to up to the specified point if it lies on the path, null otherwise.
Returns the curve location of the specified offset on the path.
Calculates the point on the path at the given offset.
Example — Finding the point on a path at a given offset:
Example — Iterating over the length of a path:
Calculates the normalized tangent vector of the path at the given offset.
Example — Working with the tangent vector at a given offset:
Example — Iterating over the length of a path:
Calculates the normal vector of the path at the given offset.
Example — Working with the normal vector at a given offset:
Example — Iterating over the length of a path:
Calculates the weighted tangent vector of the path at the given offset.
Calculates the weighted normal vector of the path at the given offset.
Calculates the curvature of the path at the given offset. Curvatures indicate how sharply a path changes direction. A straight line has zero curvature, where as a circle has a constant curvature. The path's radius at the given offset is the reciprocal value of its curvature.
Returns the nearest location on the path to the specified point.
The unique id of the item.
Read only.
The class name of the item as a string.
The name of the item. If the item has a name, it can be accessed by name through its parent's children list.
Example
The path style of the item.
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:
Specifies whether the item is visible. When set to false, the item won't be drawn.
Example — Hiding an item:
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.
Example — Setting an item's blend mode:
The opacity of the item as a value between 0 and 1.
Example — Making an item 50% transparent:
Specifies whether the item is selected. This will also return true for Group 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.
See also: project.selectedItems, segment.selected, curve.selected, point.selected
Example — Selecting an item:
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.
A plain javascript object which can be used to store arbitrary data on the item.
Example
var path = new Path(); path.data.remember = 'milk';
Example
var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20
Example
var path = new Path();
path.data = {
home: 'Omicron Theta',
found: 2338,
pets: ['Spot']
};
console.log(path.data.pets.length); // 1
Example
var path = new Path({
data: {
home: 'Omicron Theta',
found: 2338,
pets: ['Spot']
}
});
console.log(path.data.pets.length); // 1
The item's position within the parent item's coordinate system. By default, this is the rectangle.center of the item's bounds rectangle.
Example — Changing the position of a path:
Example — Changing the x coordinate of an item's position:
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 to null, meaning the rectangle.center of the item's bounds rectangle is used as pivot.
The bounding rectangle of the item including stroke width.
The bounding rectangle of the item including handles.
The item's transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.
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.
Controls whether the transformations applied to the item (e.g. through transform(matrix), rotate(angle), scale(scale), etc.) are stored in its matrix property, or whether they are directly applied to its contents or children (passed on to the segments in Path items, the children of Group items, etc.).
The item that this item is contained within.
Example
var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); group.addChild(path); // Now the parent of the path has become the group: console.log(path.parent == group); // true
Example — Setting the parent of the item to another item
var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); group.parent = path; // Now the parent of the path has become the group: console.log(path.parent == group); // true // The path is now contained in the children list of group: console.log(group.children[0] == path); // true
Example — Setting the parent of an item in the constructor
var group = new Group();
var path = new Path({
parent: group
});
// The parent of the path is the group:
console.log(path.parent == group); // true
// The path is contained in the children list of group:
console.log(group.children[0] == path); // true
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, use item.removeChildren(). To add items to the children list, use item.addChild(item) or item.insertChild(index, item).
Example — Accessing items in the children array:
Example — Accessing children by name:
Example — Passing an array of items to item.children:
The first item contained within this item. This is a shortcut for accessing item.children[0].
Read only.
The last item contained within this item.This is a shortcut for accessing item.children[item.children.length - 1].
Read only.
The index of this item within the list of its parent's children.
Read only.
The width of the stroke.
Example — Setting an item's stroke width:
The shape to be used at the beginning and end of open Path items, when they have a stroke.
Example — A look at the different stroke caps:
The shape to be used at the segments and corners of Path items when they have a stroke.
Example — A look at the different stroke joins:
The dash offset of the stroke.
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.
Specifies an array containing the dash and gap lengths of the stroke.
Example
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 the item.strokeWidth of the path. The miterLimit imposes a limit on the ratio of the miter length to the item.strokeWidth.
The winding-rule with which the shape gets filled. Please note that only modern browsers support winding-rules other than 'nonzero'.
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.
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:
See also: view.onFrame
Example — Creating an animation:
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.
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:
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.
Example — Release the mouse button over the circle shaped path, to make it red:
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.
Example — Click on the circle shaped path, to make it red:
Example — Click on the circle shaped paths to remove them:
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.
Example — Double click on the circle shaped path, to make it red:
Example — Double click on the circle shaped paths to remove them:
The function to be called repeatedly when the mouse moves on top of the item. The function receives a MouseEvent object which contains information about the mouse event.
Example — Move over the circle shaped path, to change its opacity:
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.
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.
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.
Example — Move the mouse over the circle shaped path and then move it out of it again to set its fill color to red:
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).
Example — Setting properties through an object literal
Clones the item within the same project and places the copy above the item.
Example — Cloning items:
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.
Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization.
Example — Rasterizing an item:
Checks whether the item's geometry contains the given point.
Example — Click within and outside the star below Create a star shaped path:
Perform a hit-test on the item (and its children, if it is a Group or Layer) at the location of the specified point.
The options object allows you to control the specifics of the hit-test and may contain a combination of the following values:
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(match) for a selection of illustrated examples.
See also: getItems(match)
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(match) for a selection of illustrated examples.
See also: getItems(match)
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 match.inside or match.overlapping to a rectangle describing the area in which the items either have to be fully or partly contained.
See project.getItems(match) for a selection of illustrated examples.
See also: matches(match)
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.
See project.getItems(match) for a selection of illustrated examples.
See also: getItems(match)
Exports (serializes) the item with its content and child items to a JSON data string.
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.
Exports the item with its content and child items as an SVG DOM.
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.
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.
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.
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.
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.
Sends this item to the back of all other items within the same parent.
Brings this item to the front of all other items within the same parent.
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.
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.
Moves this item above the specified item.
Moves the item below the specified item.
Removes the item and all its children from the project. The item is not destroyed and can be inserted again after removal.
Replaces this item with the provided new item which will takes its place in the project hierarchy instead.
Removes the children from the specified from index to the to index from the parent's children array.
Reverses the order of the item's children
Checks whether the item has a fill.
Checks whether the item has a stroke.
Checks whether the item has a shadow.
Checks if the item contains any children items.
Checks whether the item and all its parents are inserted into the DOM or not.
Checks if this item is above the specified item in the stacking order of the project.
Checks if the item is below the specified item in the stacking order of the project.
Checks whether the specified item is the parent of the item.
Checks whether the specified item is a child of the item.
Checks if the item is contained within the specified item.
Checks if the item is an ancestor of the specified item.
Checks if the item is an a sibling of the specified item.
Checks whether the item is grouped with the specified item.
Translates (moves) the item by the given offset point.
Rotates the item by a given angle around the given point.
Angles are oriented clockwise and measured in degrees.
See also: matrix.rotate
Example — Rotating an item:
Example — Rotating an item around a specific point:
Scales the item by the given value from its center point, or optionally from a supplied point.
Example — Scaling an item from its center point:
Example — Scaling an item from a specific point:
Scales the item by the given values from its center point, or optionally from a supplied point.
Example — Scaling an item horizontally by 300%:
Shears the item by the given value from its center point, or optionally by a supplied point.
See also: matrix.shear
Shears the item by the given values from its center point, or optionally by a supplied point.
See also: matrix.shear
Skews the item by the given angles from its center point, or optionally by a supplied point.
See also: matrix.shear
Skews the item by the given angles from its center point, or optionally by a supplied point.
See also: matrix.shear
Transform the item.
Transform the item so that its bounds fit within the specified rectangle, without changing its aspect ratio.
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
Attaches an event handler to the item.
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.
Attaches one or more event handlers to the item.
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.
Detach an event handler from the item.
Detach one or more event handlers to the item.
Emit an event on the item.
Check if the item has one or more event handlers of the specified type.
Removes the item when the events specified in the passed object literal occur.
The object literal can contain the following values:
Remove the item when the next tool.onMouseMove event is fired: object.move = true
Remove the item when the next tool.onMouseDrag event is fired: object.drag = true
Remove the item when the next tool.onMouseDown event is fired: object.down = true
Remove the item when the next tool.onMouseUp event is fired: object.up = true
Example — Click and drag below:
Removes the item when the next tool.onMouseMove event is fired.
Example — Move your mouse below:
Removes the item when the next tool.onMouseDown event is fired.
Example — Click a few times below:
Removes the item when the next tool.onMouseUp event is fired.
Example — Click a few times below:
The path's geometry, formatted as SVG style path data.
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) and subtract(path) and putting the results into a new group.
Returns all intersections between two PathItem items as an array of CurveLocation objects. CompoundPath items are also supported.
See also: getCrossings(path)
Example — Finding the intersections between two paths
Returns all crossings between two PathItem items as an array of CurveLocation objects. CompoundPath items are also supported.
Crossings are intersections where the paths actually are crossing each other, as opposed to simply touching.
See also: getIntersections(path)
Smooth bezier curves without changing the amount of segments or their points, by only smoothing and adjusting their handle points, for both open ended and closed paths.
Example — Smoothing a closed shape:
Example
On a normal empty Path, the point is simply added as the path's first segment. If called on a CompoundPath, a new Path is created as a child and the point is added as its first segment.
Draws a curve from the position of the last segment point in the path that goes through the specified through point, to the specified to point by adding one segment to the path.
Example — Interactive example. Move your mouse around the view below:
Draws an arc from the position of the last segment point in the path that goes through the specified through point, to the specified to point by adding one or more segments to the path.
Example
Example — Interactive example. Click and drag in the view below:
Draws an arc from the position of the last segment point in the path to the specified point by adding one or more segments to the path.
Example
Example — Interactive example. Click and drag in the view below:
Closes the path. When closed, Paper.js connects the first and last segment of the path with an additional curve.
See also: path.closed
If called on a CompoundPath, a new Path 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.
Adds a segment relative to the last segment point of the path.
Example
Example — Drawing a spiral using lineBy:
Copyright © 2011 Jürg Lehni & Jonathan Puckey. All Rights Reserved.