# Paper.js API Reference [Paper.js](http://paperjs.org/reference/global/) Index — version 0.12.11 {% content-ref url="/pages/estyqR68lWiZNCsJMddn" %} [Global Scope](/global-scope) {% endcontent-ref %} ### Basic Types {% content-ref url="/pages/iltSRnVZu7V7qj83MsWq" %} [Point](/basic-types/point) {% endcontent-ref %} {% content-ref url="/pages/zbFUS6ZUAVgcJ88KvHbE" %} [Size](/basic-types/size) {% endcontent-ref %} {% content-ref url="/pages/gQCwTFn4uqwjy5jqwsp3" %} [Line](/basic-types/line) {% endcontent-ref %} {% content-ref url="/pages/JkssgpiM6gW80X6k3doI" %} [Rectangle](/basic-types/rectangle) {% endcontent-ref %} {% content-ref url="/pages/jjwTUsss6cMXYQsvBjER" %} [Matrix](/basic-types/matrix) {% endcontent-ref %} ### Project & Items {% content-ref url="/pages/pWQyRoZZzFxmaQFptqH7" %} [Project](/project-and-items/project) {% endcontent-ref %} {% content-ref url="/pages/Rtp5OG2BlrHqggZrEV9O" %} [Item](/project-and-items/item) {% endcontent-ref %} {% content-ref url="/pages/tGtsmOOi1UN7zukAMgyj" %} [Layer](/project-and-items/layer) {% endcontent-ref %} {% content-ref url="/pages/ob05KDxfPWQWunk9NEFB" %} [Group](/project-and-items/group) {% endcontent-ref %} {% content-ref url="/pages/oZPiuwu4HaoKLSAFmTI9" %} [Shape](/project-and-items/shape) {% endcontent-ref %} {% content-ref url="/pages/OHQiBkhKbQSm9IakQLc8" %} [Raster](/project-and-items/raster) {% endcontent-ref %} *** {% content-ref url="/pages/hmYqEegHidW8dEiDVbwV" %} [HitResult](/project-and-items/hitresult) {% endcontent-ref %} ### Paths {% content-ref url="/pages/NgVHhcxoIoGWtehKZGeQ" %} [PathItem](/paths/pathitem) {% endcontent-ref %} {% content-ref url="/pages/if9uMldlavs6q4G412Dg" %} [Path](/paths/path) {% endcontent-ref %} {% content-ref url="/pages/NNPFWTDwHTcmK6jubIqb" %} [CompoundPath](/paths/compoundpath) {% endcontent-ref %} {% content-ref url="/pages/F2iou7y04nq0M4BFTwJE" %} [Segment](/paths/segment) {% endcontent-ref %} {% content-ref url="/pages/4RU9iCNVkNCwMuV2ghIM" %} [Curve](/paths/curve) {% endcontent-ref %} *** {% content-ref url="/pages/nm9AzROhxR6Gt8llqBQ8" %} [CurveLocation](/paths/curvelocation) {% endcontent-ref %} ### Symbols {% content-ref url="/pages/8HnUyzj44K500xteWqam" %} [SymbolDefinition](/symbols/symboldefinition) {% endcontent-ref %} {% content-ref url="/pages/eNxwk6YgoSHfdslfvmmi" %} [SymbolItem](/symbols/symbolitem) {% endcontent-ref %} ### Styling {% content-ref url="/pages/FCNPbfMQPT5x9rnXkc55" %} [Style](/styling/style) {% endcontent-ref %} {% content-ref url="/pages/eeJLVuE7kbiCwCC2RBqS" %} [Color](/styling/color) {% endcontent-ref %} {% content-ref url="/pages/5NgTbKrU85qTiKLcqqZI" %} [Gradient](/styling/gradient) {% endcontent-ref %} {% content-ref url="/pages/jJTyrr2Kc4BSAEMtD4Bb" %} [GradientStop](/styling/gradientstop) {% endcontent-ref %} ### Animation {% content-ref url="/pages/fiNzjRNjjXOYbUBDUaJ9" %} [Tween](/animation/tween) {% endcontent-ref %} ### Typography {% content-ref url="/pages/PTsFJhvB7eOjcuVUJGCo" %} [TextItem](/typography/textitem) {% endcontent-ref %} {% content-ref url="/pages/G2EYM8ZVTyR5cRx4gJyI" %} [PointText](/typography/pointtext) {% endcontent-ref %} ### User Interaction & Events {% content-ref url="/pages/x0p0pLH9qgKLZ4S1Oo1x" %} [View](/user-interaction-and-events/view) {% endcontent-ref %} {% content-ref url="/pages/GYOyFOQJmvP3WXBL6Yj8" %} [Event](/user-interaction-and-events/event) {% endcontent-ref %} {% content-ref url="/pages/f5tEFntMr7myvIqAAbmy" %} [MouseEvent](/user-interaction-and-events/mouseevent) {% endcontent-ref %} {% content-ref url="/pages/B2gpTjlYDHZMcrmKBiVz" %} [Tool](/user-interaction-and-events/tool) {% endcontent-ref %} {% content-ref url="/pages/cSb5qyMMOYVrNQcLvCCK" %} [ToolEvent](/user-interaction-and-events/toolevent) {% endcontent-ref %} {% content-ref url="/pages/GROryUGVf9nJBEhr8zPs" %} [Key](/user-interaction-and-events/key) {% endcontent-ref %} {% content-ref url="/pages/D2Unq8wpUcJBYKHiT2pM" %} [KeyEvent](/user-interaction-and-events/keyevent) {% endcontent-ref %} ### JavaScript {% content-ref url="/pages/IPBphVGC9NX6vGbcAWGl" %} [PaperScope](/javascript/paperscope) {% endcontent-ref %} {% content-ref url="/pages/w3K9NEeoQDVTAdAyNGdp" %} [PaperScript](/javascript/paperscript) {% endcontent-ref %} # Global Scope When code is executed as PaperScript, the script’s scope is populated with all fields of the currently active `PaperScope` object, which within the script appear to be global. In a JavaScript context, only the `paper` variable is added to the global scope, referencing the currently active `PaperScope` object, through which all properties and Paper.js classes can be accessed. ## Properties * `paper` A reference to the currently active `PaperScope` object. * Type: * `PaperScope` ### Global PaperScript Properties * `project` The project for which the PaperScript is executed. Note that when working with multiple projects, this does not necessarily reflect the currently active project. For this, use `paperScope.project` instead. * Type: * `Project` * `projects` The list of all open projects within the current Paper.js context. * Type: * Array of `Project` objects * `view` The reference to the project’s view. Note that when working with multiple projects, this does not necessarily reflect the view of the currently active project. For this, use `paperScope.view` instead. Read only. * Type: * `View` * `tool` The reference to the tool object which is automatically created when global tool event handlers are defined. Note that when working with multiple tools, this does not necessarily reflect the currently active tool. For this, use `paperScope.tool` instead. * Type: * `Tool` * `tools` The list of available tools. * Type: * Array of `Tool` objects ### PaperScript View Event Handlers * `onFrame` A global reference to the `view.onFrame` handler function. * Type: * `Function` * `onResize` A reference to the `view.onResize` handler function. * Type: * `Function` ### PaperScript Tool Event Handlers * `onMouseDown` A reference to the `tool.onMouseDown` handler function. * Type: * `Function` * `onMouseDrag` A reference to the `tool.onMouseDrag` handler function. * Type: * `Function` * `onMouseMove` A reference to the `tool.onMouseMove` handler function. * Type: * `Function` * `onMouseUp` A reference to the `tool.onMouseUp` handler function. * Type: * `Function` ### Keyboard Event Handlers (for PaperScript) * `onKeyDown` A reference to the `tool.onKeyDown` handler function. * Type: * `Function` * `onKeyUp` A reference to the `tool.onKeyUp` handler function. * Type: * `Function` # paperjs-round-corners A library that provides methods to round the corners of paths in Paper.js. [![npm](https://img.shields.io/npm/v/paperjs-round-corners.svg)](https://www.npmjs.com/package/paperjs-round-corners) `paperjs-round-corners` is a library that provides methods to round the corners of paths in Paper.js. It offers three different rounding methods: "simple-cubic", "cubic", and "arc", allowing you to achieve smooth and visually appealing rounded corners in your Paper.js projects. For more information and usage examples, please visit the [npm package page](https://www.npmjs.com/package/paperjs-round-corners). ### Installation To install `paperjs-round-corners`, use the following command: ```bash npm install paperjs-round-corners ``` Make sure you have Paper.js installed as well. ### Getting Started To use `paperjs-round-corners` in your Paper.js project, follow these steps: 1. Import the library and Paper.js: ```javascript import paper from 'paper'; import { PaperRoundCorners } from 'paperjs-round-corners'; ``` 2. Set up your Paper.js project and create a path: ```javascript paper.setup(canvas); const path = new paper.Path(); // Add segments to the path ``` 3. Round the corners of the path using one of the available methods: ```javascript const roundness = 10; // Adjust the roundness value as needed const options = { method: 'cubic' }; // Choose the desired rounding method // Round a single segment PaperRoundCorners.round(path.segments[0], roundness, options); // Round multiple segments PaperRoundCorners.roundMany(path.segments, roundness, options); ``` 4. Update the Paper.js view to see the rounded path: ```javascript paper.view.update(); ``` ### API Reference ### `.round(segment, roundness, options)` Rounds the corners of a single segment. * `segment` (paper.Segment): The segment to be rounded. * `roundness` (number): The roundness value. Must be positive. * `options` (object): The rounding options. * `method` (string): The rounding method. Can be "simple-cubic", "cubic", or "arc". Returns `true` if the rounding was successful, `false` otherwise. ### `.roundMany(segments, roundness, options)` Rounds the corners of multiple segments. * `segments` (paper.Segment\[]): An array of segments to be rounded. * `roundness` (number): The roundness value. Must be positive. * `options` (object): The rounding options. * `method` (string): The rounding method. Can be "simple-cubic", "cubic", or "arc". Returns an array of boolean values indicating the success of rounding for each segment. ### `.roundMap(segments, options)` Rounds the corners of multiple segments using a Map. * `segments` (Map\): A Map where the keys are the segments to be rounded and the values are the corresponding roundness values. * `options` (object): The rounding options. * `method` (string): The rounding method. Can be "simple-cubic", "cubic", or "arc". Returns a Map\ indicating the success of rounding for each segment. Example usage: ```javascript const segments = new Map([ [segment1, 10], [segment2, 20], [segment3, 15], ]); const roundedSegments = YourClass.roundMap(segments, { method: "cubic" }); ``` ### Rounding Methods #### `simple-cubic` The "simple-cubic" method rounds the corner by dividing the path at a specified distance (roundness) before and after the segment. It creates a smooth curve using a simple cubic Bézier curve. #### `cubic` The "cubic" method rounds the corner by dividing the path at a specified distance (roundness) before and after the segment. It calculates the tangent lines at the division points and finds their intersection point to create a more precise and smoother curve using a cubic Bézier curve. #### `arc` The "arc" method rounds the corner using an arc with a specified radius. It creates offset paths (inward and outward) for the curves before and after the segment, finds the intersection point between the offset paths, and creates an arc using that intersection point as the center. # Point The Point object represents a point in the two dimensional space of the Paper.js project. It is also used to represent two dimensional vector objects. Example:Create a point at x: 10, y: 5 ```jsx var point = new Point(10, 5); console.log(point.x); // 10 console.log(point.y); // 5 ``` ## Constructors * `Point(x, y)` Creates a Point object with the given x and y coordinates. * Parameters: * `x:` `Number` — the x coordinate * `y:` `Number` — the y coordinate * Returns: * `Point` Example:Create a point at x: 10, y: 5 ```jsx var point = new Point(10, 5); console.log(point.x); // 10 console.log(point.y); // 5 ``` * `Point(array)` Creates a Point object using the numbers in the given array as coordinates. * Parameters: * `array:` `Array` * Returns: * `Point` Example:Creating a point at x: 10, y: 5 using an array of numbers: ```jsx var array = [10, 5]; var point = new Point(array); console.log(point.x); // 10 console.log(point.y); // 5 ``` Example:Passing an array to a functionality that expects a point: ```jsx // Create a circle shaped path at x: 50, y: 50 // with a radius of 30: var path = new Path.Circle([50, 50], 30); path.fillColor = 'red'; // Which is the same as doing: var path = new Path.Circle(new Point(50, 50), 30); path.fillColor = 'red'; ``` * `Point(object)` Creates a Point object using the properties in the given object. * Parameters: * `object:` `Object` — the object describing the point’s properties * Returns: * `Point` Example:Creating a point using an object literal with length and angle properties: ```jsx var point = new Point({ length: 10, angle: 90 }); console.log(point.length); // 10 console.log(point.angle); // 90 ``` Example:Creating a point at x: 10, y: 20 using an object literal: ```jsx var point = new Point({ x: 10, y: 20 }); console.log(point.x); // 10 console.log(point.y); // 20 ``` Example:Passing an object to a functionality that expects a point: ```jsx var center = { x: 50, y: 50 }; // Creates a circle shaped path at x: 50, y: 50 // with a radius of 30: var path = new Path.Circle(center, 30); path.fillColor = 'red'; ``` * `Point(size)` Creates a Point object using the width and height values of the given Size object. * Parameters: * `size:` `Size` * Returns: * `Point` Example:Creating a point using a size object. ```jsx // Create a Size with a width of 100pt and a height of 50pt var size = new Size(100, 50); console.log(size); // { width: 100, height: 50 } var point = new Point(size); console.log(point); // { x: 100, y: 50 } ``` * `Point(point)` Creates a Point object using the coordinates of the given Point object. * Parameters: * `point:` `Point` * Returns: * `Point` ## Operators * `+number`, `+point` Returns the addition of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Point` — the addition of the point and the value as a new point Example: ```jsx var point = new Point(5, 10); var result = point + 20; console.log(result); // {x: 25, y: 30} ``` Returns the addition of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to add * Returns: * `Point` — the addition of the two points as a new point Example: ```jsx var point1 = new Point(5, 10); var point2 = new Point(10, 20); var result = point1 + point2; console.log(result); // {x: 15, y: 30} ``` * `-number`, `-point` Returns the subtraction of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Point` — the subtraction of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point - 5; console.log(result); // {x: 5, y: 15} ``` Returns the subtraction of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to subtract * Returns: * `Point` — the subtraction of the two points as a new point Example: ```jsx var firstPoint = new Point(10, 20); var secondPoint = new Point(5, 5); var result = firstPoint - secondPoint; console.log(result); // {x: 5, y: 15} ``` * `*number`, `*point` Returns the multiplication of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply by * Returns: * `Point` — the multiplication of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point * 2; console.log(result); // {x: 20, y: 40} ``` Returns the multiplication of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to multiply by * Returns: * `Point` — the multiplication of the two points as a new point Example: ```jsx var firstPoint = new Point(5, 10); var secondPoint = new Point(4, 2); var result = firstPoint * secondPoint; console.log(result); // {x: 20, y: 20} ``` * `/number`, `/point` Returns the division of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide by * Returns: * `Point` — the division of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point / 2; console.log(result); // {x: 5, y: 10} ``` Returns the division of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to divide by * Returns: * `Point` — the division of the two points as a new point Example: ```jsx var firstPoint = new Point(8, 10); var secondPoint = new Point(2, 5); var result = firstPoint / secondPoint; console.log(result); // {x: 4, y: 2} ``` * `%number`, `%point` The modulo operator returns the integer remainders of dividing the point by the supplied value as a new point. * Parameters: * `value:` `Number` * Returns: * `Point` — the integer remainders of dividing the point by the value as a new point Example: ```jsx var point = new Point(12, 6); console.log(point % 5); // {x: 2, y: 1} ``` The modulo operator returns the integer remainders of dividing the point by the supplied value as a new point. * Parameters: * `point:` `Point` * Returns: * `Point` — the integer remainders of dividing the points by each other as a new point Example: ```jsx var point = new Point(12, 6); console.log(point % new Point(5, 2)); // {x: 2, y: 0} ``` ## Properties * `x` The x coordinate of the point * Type: * `Number` * `y` The y coordinate of the point * Type: * `Number` * `length` The length of the vector that is represented by this point’s coordinates. Each point can be interpreted as a vector that points from the origin (`x = 0`, `y = 0`) to the point’s location. Setting the length changes the location but keeps the vector’s angle. * Type: * `Number` * `angle` The vector’s angle in degrees, measured from the x-axis to the vector. * Type: * `Number` * `angleInRadians` The vector’s angle in radians, measured from the x-axis to the vector. * Type: * `Number` * `quadrant` The quadrant of the `angle` of the point. Angles between 0 and 90 degrees are in quadrant `1`. Angles between 90 and 180 degrees are in quadrant `2`, angles between 180 and 270 degrees are in quadrant `3` and angles between 270 and 360 degrees are in quadrant `4`. Read only. * Type: * `Number` Example: ```jsx var point = new Point({ angle: 10, length: 20 }); console.log(point.quadrant); // 1 point.angle = 100; console.log(point.quadrant); // 2 point.angle = 190; console.log(point.quadrant); // 3 point.angle = 280; console.log(point.quadrant); // 4 ``` * `selected` This property is only valid if the point is an anchor or handle point of a `Segment` or a `Curve`, or the position of an `Item`, as returned by `item.position`, `segment.point`, `segment.handleIn`, `segment.handleOut`, `curve.point1`, `curve.point2`, `curve.handle1`, `curve.handle2`. In those cases, it returns `true` if it the point is selected, `false` otherwise. Paper.js renders selected points on top of your project. This is very useful when debugging. * Default: * `false` * Type: * `Boolean` Example: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40 }); // Select the third segment point: path.segments[2].point.selected = true; // Select the item's position, which is the pivot point // around which it is transformed: path.position.selected = true; ``` ## Methods * `set(...values)` Sets the point to the passed values. Note that any sequence of parameters that is supported by the various `Point`() constructors also work for calls of `set()`. * Parameters: * `values:` `any value` * Returns: * `Point` * `equals(point)` Checks whether the coordinates of the point are equal to that of the supplied point. * Parameters: * `point:` `Point` * Returns: * `Boolean` — `true` if the points are equal, `false` otherwise Example: ```jsx var point = new Point(5, 10); console.log(point == new Point(5, 10)); // true console.log(point == new Point(1, 1)); // false console.log(point != new Point(1, 1)); // true ``` * `clone()` Returns a copy of the point. * Returns: * `Point` — the cloned point Example: ```jsx var point1 = new Point(); var point2 = point1; point2.x = 1; // also changes point1.x var point2 = point1.clone(); point2.x = 1; // doesn't change point1.x ``` * `toString()` * Returns: * `String` — a string representation of the point * `getAngle(point)` Returns the smaller angle between two vectors. The angle is unsigned, no information about rotational direction is given. * Parameters: * `point:` `Point` * Returns: * `Number` — the angle in degrees * `getAngleInRadians(point)` Returns the smaller angle between two vectors in radians. The angle is unsigned, no information about rotational direction is given. * Parameters: * `point:` `Point` * Returns: * `Number` — the angle in radians * `getDirectedAngle(point)` Returns the angle between two vectors. The angle is directional and signed, giving information about the rotational direction. Read more about angle units and orientation in the description of the `angle` property. * Parameters: * `point:` `Point` * Returns: * `Number` — the angle between the two vectors * `getDistance(point[, squared])` Returns the distance between the point and another point. * Parameters: * `point:` `Point` * `squared:` `Boolean` — Controls whether the distance should remain squared, or its square root should be calculated — optional, default: `false` * Returns: * `Number` * `normalize([length])` Normalize modifies the `length` of the vector to `1` without changing its angle and returns it as a new point. The optional `length` parameter defines the length to normalize to. The object itself is not modified! * Parameters: * `length:` `Number` — The length of the normalized vector — optional, default: `1` * Returns: * `Point` — the normalized vector of the vector that is represented by this point’s coordinates * `rotate(angle, center)` Rotates the point by the given angle around an optional center point. The object itself is not modified. Read more about angle units and orientation in the description of the `angle` property. * Parameters: * `angle:` `Number` — the rotation angle * `center:` `Point` — the center point of the rotation * Returns: * `Point` — the rotated point * `transform(matrix)` Transforms the point by the matrix as a new point. The object itself is not modified! * Parameters: * `matrix:` `Matrix` * Returns: * `Point` — the transformed point ### Tests * `isInside(rect)` Checks whether the point is inside the boundaries of the rectangle. * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` — `true` if the point is inside the rectangle, `false` otherwise * `isClose(point, tolerance)` Checks if the point is within a given distance of another point. * Parameters: * `point:` `Point` — the point to check against * `tolerance:` `Number` — the maximum distance allowed * Returns: * `Boolean` — `true` if it is within the given distance, `false` otherwise * `isCollinear(point)` Checks if the vector represented by this point is collinear (parallel) to another vector. * Parameters: * `point:` `Point` — the vector to check against * Returns: * `Boolean` — `true` it is collinear, `false` otherwise * `isOrthogonal(point)` Checks if the vector represented by this point is orthogonal (perpendicular) to another vector. * Parameters: * `point:` `Point` — the vector to check against * Returns: * `Boolean` — `true` it is orthogonal, `false` otherwise * `isZero()` Checks if this point has both the x and y coordinate set to 0. * Returns: * `Boolean` — `true` if both x and y are 0, `false` otherwise * `isNaN()` Checks if this point has an undefined value for at least one of its coordinates. * Returns: * `Boolean` — `true` if either x or y are not a number, `false` otherwise * `isInQuadrant(quadrant)` Checks if the vector is within the specified quadrant. Note that if the vector lies on the boundary between two quadrants, `true` will be returned for both quadrants. * Parameters: * `quadrant:` `Number` — the quadrant to check against * Returns: * `Boolean` — `true` if either x or y are not a number, `false` otherwise * See also: * `quadrant` ### Vector Math Functions * `dot(point)` Returns the dot product of the point and another point. * Parameters: * `point:` `Point` * Returns: * `Number` — the dot product of the two points * `cross(point)` Returns the cross product of the point and another point. * Parameters: * `point:` `Point` * Returns: * `Number` — the cross product of the two points * `project(point)` Returns the projection of the point onto another point. Both points are interpreted as vectors. * Parameters: * `point:` `Point` * Returns: * `Point` — the projection of the point onto another point ### Math Functions * `round()` Returns a new point with rounded `x` and `y` values. The object itself is not modified! * Returns: * `Point` Example: ```jsx var point = new Point(10.2, 10.9); var roundPoint = point.round(); console.log(roundPoint); // {x: 10, y: 11} ``` * `ceil()` Returns a new point with the nearest greater non-fractional values to the specified `x` and `y` values. The object itself is not modified! * Returns: * `Point` Example: ```jsx var point = new Point(10.2, 10.9); var ceilPoint = point.ceil(); console.log(ceilPoint); // {x: 11, y: 11} ``` * `floor()` Returns a new point with the nearest smaller non-fractional values to the specified `x` and `y` values. The object itself is not modified! * Returns: * `Point` Example: ```jsx var point = new Point(10.2, 10.9); var floorPoint = point.floor(); console.log(floorPoint); // {x: 10, y: 10} ``` * `abs()` Returns a new point with the absolute values of the specified `x` and `y` values. The object itself is not modified! * Returns: * `Point` Example: ```jsx var point = new Point(-5, 10); var absPoint = point.abs(); console.log(absPoint); // {x: 5, y: 10} ``` ### Math Operator Functions * `add(number)` Returns the addition of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Point` — the addition of the point and the value as a new point Example: ```jsx var point = new Point(5, 10); var result = point + 20; console.log(result); // {x: 25, y: 30} ``` * `add(point)` Returns the addition of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to add * Returns: * `Point` — the addition of the two points as a new point Example: ```jsx var point1 = new Point(5, 10); var point2 = new Point(10, 20); var result = point1 + point2; console.log(result); // {x: 15, y: 30} ``` * `subtract(number)` Returns the subtraction of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Point` — the subtraction of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point - 5; console.log(result); // {x: 5, y: 15} ``` * `subtract(point)` Returns the subtraction of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to subtract * Returns: * `Point` — the subtraction of the two points as a new point Example: ```jsx var firstPoint = new Point(10, 20); var secondPoint = new Point(5, 5); var result = firstPoint - secondPoint; console.log(result); // {x: 5, y: 15} ``` * `multiply(number)` Returns the multiplication of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply by * Returns: * `Point` — the multiplication of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point * 2; console.log(result); // {x: 20, y: 40} ``` * `multiply(point)` Returns the multiplication of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to multiply by * Returns: * `Point` — the multiplication of the two points as a new point Example: ```jsx var firstPoint = new Point(5, 10); var secondPoint = new Point(4, 2); var result = firstPoint * secondPoint; console.log(result); // {x: 20, y: 20} ``` * `divide(number)` Returns the division of the supplied value to both coordinates of the point as a new point. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide by * Returns: * `Point` — the division of the point and the value as a new point Example: ```jsx var point = new Point(10, 20); var result = point / 2; console.log(result); // {x: 5, y: 10} ``` * `divide(point)` Returns the division of the supplied point to the point as a new point. The object itself is not modified! * Parameters: * `point:` `Point` — the point to divide by * Returns: * `Point` — the division of the two points as a new point Example: ```jsx var firstPoint = new Point(8, 10); var secondPoint = new Point(2, 5); var result = firstPoint / secondPoint; console.log(result); // {x: 4, y: 2} ``` * `modulo(value)` The modulo operator returns the integer remainders of dividing the point by the supplied value as a new point. * Parameters: * `value:` `Number` * Returns: * `Point` — the integer remainders of dividing the point by the value as a new point Example: ```jsx var point = new Point(12, 6); console.log(point % 5); // {x: 2, y: 1} ``` * `modulo(point)` The modulo operator returns the integer remainders of dividing the point by the supplied value as a new point. * Parameters: * `point:` `Point` * Returns: * `Point` — the integer remainders of dividing the points by each other as a new point Example: ```jsx var point = new Point(12, 6); console.log(point % new Point(5, 2)); // {x: 2, y: 0} ``` ## Static Methods * `Point.min(point1, point2)` Returns a new point object with the smallest `x` and `y` of the supplied points. * Parameters: * `point1:` `Point` * `point2:` `Point` * Returns: * `Point` — the newly created point object Example: ```jsx var point1 = new Point(10, 100); var point2 = new Point(200, 5); var minPoint = Point.min(point1, point2); console.log(minPoint); // {x: 10, y: 5} ``` Example:Find the minimum of multiple points: ```jsx var point1 = new Point(60, 100); var point2 = new Point(200, 5); var point3 = new Point(250, 35); [point1, point2, point3].reduce(Point.min) // {x: 60, y: 5} ``` * `Point.max(point1, point2)` Returns a new point object with the largest `x` and `y` of the supplied points. * Parameters: * `point1:` `Point` * `point2:` `Point` * Returns: * `Point` — the newly created point object Example: ```jsx var point1 = new Point(10, 100); var point2 = new Point(200, 5); var maxPoint = Point.max(point1, point2); console.log(maxPoint); // {x: 200, y: 100} ``` Example:Find the maximum of multiple points: ```jsx var point1 = new Point(60, 100); var point2 = new Point(200, 5); var point3 = new Point(250, 35); [point1, point2, point3].reduce(Point.max) // {x: 250, y: 100} ``` * `Point.random()` Returns a point object with random `x` and `y` values between `0` and `1`. * Returns: * `Point` — the newly created point object Example: ```jsx var maxPoint = new Point(100, 100); var randomPoint = Point.random(); // A point between {x:0, y:0} and {x:100, y:100}: var point = maxPoint * randomPoint; ``` # Size The Size object is used to describe the size or dimensions of something, through its `width` and `height` properties. Example: Create a size that is 10pt wide and 5pt high, and use it to define a rectangle: ```jsx var size = new Size(10, 5); console.log(size.width); // 10 console.log(size.height); // 5 var rect = new Rectangle(new Point(20, 15), size); console.log(rect); // { x: 20, y: 15, width: 10, height: 5 } ``` ## Constructors * `Size(width, height)` Creates a Size object with the given width and height values. * Parameters: * `width:` `Number` — the width * `height:` `Number` — the height * Returns: * `Size` Example:Create a size that is 10pt wide and 5pt high ```jsx var size = new Size(10, 5); console.log(size.width); // 10 console.log(size.height); // 5 ``` * `Size(array)` Creates a Size object using the numbers in the given array as dimensions. * Parameters: * `array:` `Array` * Returns: * `Size` Example:Creating a size of width: 320, height: 240 using an array of numbers: ```jsx var array = [320, 240]; var size = new Size(array); console.log(size.width); // 320 console.log(size.height); // 240 ``` * `Size(object)` Creates a Size object using the properties in the given object. * Parameters: * `object:` `Object` * Returns: * `Size` Example:Creating a size of width: 10, height: 20 using an object literal: ```jsx var size = new Size({ width: 10, height: 20 }); console.log(size.width); // 10 console.log(size.height); // 20 ``` * `Size(size)` Creates a Size object using the coordinates of the given Size object. * Parameters: * `size:` `Size` * Returns: * `Size` * `Size(point)` Creates a Size object using the `point.x` and `point.y` values of the given Point object. * Parameters: * `point:` `Point` * Returns: * `Size` Example: ```jsx var point = new Point(50, 50); var size = new Size(point); console.log(size.width); // 50 console.log(size.height); // 50 ``` ## Operators * `+number`, `+size` Returns the addition of the supplied value to the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Size` — the addition of the size and the value as a new size Example: ```jsx var size = new Size(5, 10); var result = size + 20; console.log(result); // {width: 25, height: 30} ``` Returns the addition of the width and height of the supplied size to the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to add * Returns: * `Size` — the addition of the two sizes as a new size Example: ```jsx var size1 = new Size(5, 10); var size2 = new Size(10, 20); var result = size1 + size2; console.log(result); // {width: 15, height: 30} ``` * `-number`, `-size` Returns the subtraction of the supplied value from the width and height of the size as a new size. The object itself is not modified! The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Size` — the subtraction of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size - 5; console.log(result); // {width: 5, height: 15} ``` Returns the subtraction of the width and height of the supplied size from the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to subtract * Returns: * `Size` — the subtraction of the two sizes as a new size Example: ```jsx var firstSize = new Size(10, 20); var secondSize = new Size(5, 5); var result = firstSize - secondSize; console.log(result); // {width: 5, height: 15} ``` * `*number`, `*size` Returns the multiplication of the supplied value with the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply by * Returns: * `Size` — the multiplication of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size * 2; console.log(result); // {width: 20, height: 40} ``` Returns the multiplication of the width and height of the supplied size with the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to multiply by * Returns: * `Size` — the multiplication of the two sizes as a new size Example: ```jsx var firstSize = new Size(5, 10); var secondSize = new Size(4, 2); var result = firstSize * secondSize; console.log(result); // {width: 20, height: 20} ``` * `/number`, `/size` Returns the division of the supplied value by the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide by * Returns: * `Size` — the division of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size / 2; console.log(result); // {width: 5, height: 10} ``` Returns the division of the width and height of the supplied size by the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to divide by * Returns: * `Size` — the division of the two sizes as a new size Example: ```jsx var firstSize = new Size(8, 10); var secondSize = new Size(2, 5); var result = firstSize / secondSize; console.log(result); // {width: 4, height: 2} ``` * `%number`, `%size` The modulo operator returns the integer remainders of dividing the size by the supplied value as a new size. * Parameters: * `value:` `Number` * Returns: * `Size` — the integer remainders of dividing the size by the value as a new size Example: ```jsx var size = new Size(12, 6); console.log(size % 5); // {width: 2, height: 1} ``` The modulo operator returns the integer remainders of dividing the size by the supplied size as a new size. * Parameters: * `size:` `Size` * Returns: * `Size` — the integer remainders of dividing the sizes by each other as a new size Example: ```jsx var size = new Size(12, 6); console.log(size % new Size(5, 2)); // {width: 2, height: 0} ``` ## Properties * `width` The width of the size * Type: * `Number` * `height` The height of the size * Type: * `Number` ## Methods * `set(...values)` Sets the size to the passed values. Note that any sequence of parameters that is supported by the various `Size`() constructors also work for calls of `set()`. * Parameters: * `values:` `any value` * Returns: * `Size` * `equals(size)` Checks whether the width and height of the size are equal to those of the supplied size. * Parameters: * `size:` `Size` — the size to compare to * Returns: * `Boolean` Example: ```jsx var size = new Size(5, 10); console.log(size == new Size(5, 10)); // true console.log(size == new Size(1, 1)); // false console.log(size != new Size(1, 1)); // true ``` * `clone()` Returns a copy of the size. * Returns: * `Size` * `toString()` * Returns: * `String` — a string representation of the size ### Tests * `isZero()` Checks if this size has both the width and height set to 0. * Returns: * `Boolean` — `true` if both width and height are 0, `false` otherwise * `isNaN()` Checks if the width or the height of the size are NaN. * Returns: * `Boolean` — `true` if the width or height of the size are NaN, `false` otherwise ### Math Functions * `round()` Returns a new size with rounded `width` and `height` values. The object itself is not modified! * Returns: * `Size` Example: ```jsx var size = new Size(10.2, 10.9); var roundSize = size.round(); console.log(roundSize); // {x: 10, y: 11} ``` * `ceil()` Returns a new size with the nearest greater non-fractional values to the specified `width` and `height` values. The object itself is not modified! * Returns: * `Size` Example: ```jsx var size = new Size(10.2, 10.9); var ceilSize = size.ceil(); console.log(ceilSize); // {x: 11, y: 11} ``` * `floor()` Returns a new size with the nearest smaller non-fractional values to the specified `width` and `height` values. The object itself is not modified! * Returns: * `Size` Example: ```jsx var size = new Size(10.2, 10.9); var floorSize = size.floor(); console.log(floorSize); // {x: 10, y: 10} ``` * `abs()` Returns a new size with the absolute values of the specified `width` and `height` values. The object itself is not modified! * Returns: * `Size` Example: ```jsx var size = new Size(-5, 10); var absSize = size.abs(); console.log(absSize); // {x: 5, y: 10} ``` ### Math Operator Functions * `add(number)` Returns the addition of the supplied value to the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Size` — the addition of the size and the value as a new size Example: ```jsx var size = new Size(5, 10); var result = size + 20; console.log(result); // {width: 25, height: 30} ``` * `add(size)` Returns the addition of the width and height of the supplied size to the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to add * Returns: * `Size` — the addition of the two sizes as a new size Example: ```jsx var size1 = new Size(5, 10); var size2 = new Size(10, 20); var result = size1 + size2; console.log(result); // {width: 15, height: 30} ``` * `subtract(number)` Returns the subtraction of the supplied value from the width and height of the size as a new size. The object itself is not modified! The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Size` — the subtraction of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size - 5; console.log(result); // {width: 5, height: 15} ``` * `subtract(size)` Returns the subtraction of the width and height of the supplied size from the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to subtract * Returns: * `Size` — the subtraction of the two sizes as a new size Example: ```jsx var firstSize = new Size(10, 20); var secondSize = new Size(5, 5); var result = firstSize - secondSize; console.log(result); // {width: 5, height: 15} ``` * `multiply(number)` Returns the multiplication of the supplied value with the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply by * Returns: * `Size` — the multiplication of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size * 2; console.log(result); // {width: 20, height: 40} ``` * `multiply(size)` Returns the multiplication of the width and height of the supplied size with the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to multiply by * Returns: * `Size` — the multiplication of the two sizes as a new size Example: ```jsx var firstSize = new Size(5, 10); var secondSize = new Size(4, 2); var result = firstSize * secondSize; console.log(result); // {width: 20, height: 20} ``` * `divide(number)` Returns the division of the supplied value by the width and height of the size as a new size. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide by * Returns: * `Size` — the division of the size and the value as a new size Example: ```jsx var size = new Size(10, 20); var result = size / 2; console.log(result); // {width: 5, height: 10} ``` * `divide(size)` Returns the division of the width and height of the supplied size by the size as a new size. The object itself is not modified! * Parameters: * `size:` `Size` — the size to divide by * Returns: * `Size` — the division of the two sizes as a new size Example: ```jsx var firstSize = new Size(8, 10); var secondSize = new Size(2, 5); var result = firstSize / secondSize; console.log(result); // {width: 4, height: 2} ``` * `modulo(value)` The modulo operator returns the integer remainders of dividing the size by the supplied value as a new size. * Parameters: * `value:` `Number` * Returns: * `Size` — the integer remainders of dividing the size by the value as a new size Example: ```jsx var size = new Size(12, 6); console.log(size % 5); // {width: 2, height: 1} ``` * `modulo(size)` The modulo operator returns the integer remainders of dividing the size by the supplied size as a new size. * Parameters: * `size:` `Size` * Returns: * `Size` — the integer remainders of dividing the sizes by each other as a new size Example: ```jsx var size = new Size(12, 6); console.log(size % new Size(5, 2)); // {width: 2, height: 0} ``` ## Static Methods * `Size.min(size1, size2)` Returns a new size object with the smallest `width` and `height` of the supplied sizes. * Parameters: * `size1:` `Size` * `size2:` `Size` * Returns: * `Size` — the newly created size object Example: ```jsx var size1 = new Size(10, 100); var size2 = new Size(200, 5); var minSize = Size.min(size1, size2); console.log(minSize); // {width: 10, height: 5} ``` Example:Find the minimum of multiple sizes: ```jsx var size1 = new Size(60, 100); var size2 = new Size(200, 5); var size3 = new Size(250, 35); [size1, size2, size3].reduce(Size.min) // {width: 60, height: 5} ``` * `Size.max(size1, size2)` Returns a new size object with the largest `width` and `height` of the supplied sizes. * Parameters: * `size1:` `Size` * `size2:` `Size` * Returns: * `Size` — the newly created size object Example: ```jsx var size1 = new Size(10, 100); var size2 = new Size(200, 5); var maxSize = Size.max(size1, size2); console.log(maxSize); // {width: 200, height: 100} ``` Example:Find the maximum of multiple sizes: ```jsx var size1 = new Size(60, 100); var size2 = new Size(200, 5); var size3 = new Size(250, 35); [size1, size2, size3].reduce(Size.max) // {width: 250, height: 100} ``` * `Size.random()` Returns a size object with random `width` and `height` values between `0` and `1`. * Returns: * `Size` — the newly created size object Example: ```jsx var maxSize = new Size(100, 100); var randomSize = Size.random(); var size = maxSize * randomSize; ``` # Line The Line object represents.. ## Constructors * `Line(point1, point2[, asVector, arg3, arg4])` Creates a Line object. * Parameters: * `point1:` `Point` * `point2:` `Point` * `asVector:` `Boolean` — optional, default: `false` * `arg3:` * `arg4:` * Returns: * `Line` ## Properties * `point` The starting point of the line. Read only. * Type: * `Point` * `vector` The direction of the line as a vector. Read only. * Type: * `Point` * `length` The length of the line. Read only. * Type: * `Number` ## Methods * `intersect(line[, isInfinite])` * Parameters: * `line:` `Line` * `isInfinite:` `Boolean` — optional, default: `false` * Returns: * `Point` — the intersection point of the lines, `undefined` if the two lines are collinear, or `null` if they don’t intersect. * `getSide(point[, isInfinite])` * Parameters: * `point:` `Point` * `isInfinite:` `Boolean` — optional, default: `false` * Returns: * `Number` * `getDistance(point)` * Parameters: * `point:` `Point` * Returns: * `Number` * `getSignedDistance(point)` * Parameters: * `point:` `Point` * Returns: * `Number` # Rectangle A Rectangle specifies an area that is enclosed by it’s top-left point (x, y), its width, and its height. It should not be confused with a rectangular path, it is not an item. ## Constructors * `Rectangle(point, size)` Creates a Rectangle object. * Parameters: * `point:` `Point` — the top-left point of the rectangle * `size:` `Size` — the size of the rectangle * Returns: * `Rectangle` * `Rectangle(object)` Creates a Rectangle object. * Parameters: * `object:` `Object` — an object containing properties to be set on the rectangle * Returns: * `Rectangle` Example:Create a rectangle between {x: 20, y: 20} and {x: 80, y:80} ```jsx var rectangle = new Rectangle({ point: [20, 20], size: [60, 60] }); ``` Example:Create a rectangle between {x: 20, y: 20} and {x: 80, y:80} ```jsx var rectangle = new Rectangle({ from: [20, 20], to: [80, 80] }); ``` * `Rectangle(x, y, width, height)` Creates a rectangle object. * Parameters: * `x:` `Number` — the left coordinate * `y:` `Number` — the top coordinate * `width:` `Number` * `height:` `Number` * Returns: * `Rectangle` * `Rectangle(from, to)` Creates a rectangle object 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. * Parameters: * `from:` `Point` — the first point defining the rectangle * `to:` `Point` — the second point defining the rectangle * Returns: * `Rectangle` * `Rectangle(rectangle)` Creates a new rectangle object from the passed rectangle object. * Parameters: * `rectangle:` `Rectangle` * Returns: * `Rectangle` ## Properties * `x` The x position of the rectangle. * Type: * `Number` * `y` The y position of the rectangle. * Type: * `Number` * `width` The width of the rectangle. * Type: * `Number` * `height` The height of the rectangle. * Type: * `Number` * `point` The top-left point of the rectangle * Type: * `Point` * `size` The size of the rectangle * Type: * `Size` ### Side Positions * `left` The position of the left hand side of the rectangle. Note that this doesn’t move the whole rectangle; the right hand side stays where it was. * Type: * `Number` * `top` The top coordinate of the rectangle. Note that this doesn’t move the whole rectangle: the bottom won’t move. * Type: * `Number` * `right` The position of the right hand side of the rectangle. Note that this doesn’t move the whole rectangle; the left hand side stays where it was. * Type: * `Number` * `bottom` The bottom coordinate of the rectangle. Note that this doesn’t move the whole rectangle: the top won’t move. * Type: * `Number` ### Corner and Center Point Positions * `center` The center point of the rectangle. * Type: * `Point` * `topLeft` The top-left point of the rectangle. * Type: * `Point` * `topRight` The top-right point of the rectangle. * Type: * `Point` * `bottomLeft` The bottom-left point of the rectangle. * Type: * `Point` * `bottomRight` The bottom-right point of the rectangle. * Type: * `Point` * `leftCenter` The left-center point of the rectangle. * Type: * `Point` * `topCenter` The top-center point of the rectangle. * Type: * `Point` * `rightCenter` The right-center point of the rectangle. * Type: * `Point` * `bottomCenter` The bottom-center point of the rectangle. * Type: * `Point` * `area` The area of the rectangle. Read only. * Type: * `Number` ### Item Bounds * `selected` Specifies whether an item’s bounds are to appear as selected. Paper.js draws the bounds of items with selected bounds on top of your project. This is very useful when debugging. * Default: * `false` * Type: * `Boolean` Example: Run ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, selected: true }); path.bounds.selected = true; ``` ## Methods * `set(...values)` Sets the rectangle to the passed values. Note that any sequence of parameters that is supported by the various `Rectangle`() constructors also work for calls of `set()`. * Parameters: * `values:` `any value` * Returns: * `Rectangle` * `clone()` Returns a copy of the rectangle. * Returns: * `Rectangle` * `equals(rect)` Checks whether the coordinates and size of the rectangle are equal to that of the supplied rectangle. * Parameters: * `rect:` `Rectangle` * Returns: * `Boolean` — `true` if the rectangles are equal, `false` otherwise * `toString()` * Returns: * `String` — a string representation of this rectangle * `isEmpty()` * Returns: * `Boolean` — `true` if the rectangle is empty, `false` otherwise ### Geometric Tests * `contains(point)` Tests if the specified point is inside the boundary of the rectangle. * Parameters: * `point:` `Point` — the specified point * Returns: * `Boolean` — `true` if the point is inside the rectangle’s boundary, `false` otherwise Example:Checking whether the mouse position falls within the bounding rectangle of an item: Run ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30. var circle = new Path.Circle(new Point(80, 50), 30); circle.fillColor = 'red'; function onMouseMove(event) { // Check whether the mouse position intersects with the // bounding box of the item: if (circle.bounds.contains(event.point)) { // If it intersects, fill it with green: circle.fillColor = 'green'; } else { // If it doesn't intersect, fill it with red: circle.fillColor = 'red'; } } ``` * `contains(rect)` Tests if the interior of the rectangle entirely contains the specified rectangle. * Parameters: * `rect:` `Rectangle` — the specified rectangle * Returns: * `Boolean` — `true` if the rectangle entirely contains the specified rectangle, `false` otherwise Example:Checking whether the bounding box of one item is contained within that of another item: Run ```jsx // All newly created paths will inherit these styles: project.currentStyle = { fillColor: 'green', strokeColor: 'black' }; // Create a circle shaped path at {x: 80, y: 50} // with a radius of 45. var largeCircle = new Path.Circle(new Point(80, 50), 45); // Create a smaller circle shaped path in the same position // with a radius of 30. var circle = new Path.Circle(new Point(80, 50), 30); function onMouseMove(event) { // Move the circle to the position of the mouse: circle.position = event.point; // Check whether the bounding box of the smaller circle // is contained within the bounding box of the larger item: if (largeCircle.bounds.contains(circle.bounds)) { // If it does, fill it with green: circle.fillColor = 'green'; largeCircle.fillColor = 'green'; } else { // If doesn't, fill it with red: circle.fillColor = 'red'; largeCircle.fillColor = 'red'; } } ``` * `intersects(rect[, epsilon])` Tests if the interior of this rectangle intersects the interior of another rectangle. Rectangles just touching each other are considered as non-intersecting, except if a `epsilon` value is specified by which this rectangle’s dimensions are increased before comparing. * Parameters: * `rect:` `Rectangle` — the specified rectangle * `epsilon:` `Number` — the epsilon against which to compare the rectangle’s dimensions — optional, default: `0` * Returns: * `Boolean` — `true` if the rectangle and the specified rectangle intersect each other, `false` otherwise Example:Checking whether the bounding box of one item intersects with that of another item: Run ```jsx // All newly created paths will inherit these styles: project.currentStyle = { fillColor: 'green', strokeColor: 'black' }; // Create a circle shaped path at {x: 80, y: 50} // with a radius of 45. var largeCircle = new Path.Circle(new Point(80, 50), 45); // Create a smaller circle shaped path in the same position // with a radius of 30. var circle = new Path.Circle(new Point(80, 50), 30); function onMouseMove(event) { // Move the circle to the position of the mouse: circle.position = event.point; // Check whether the bounding box of the two circle // shaped paths intersect: if (largeCircle.bounds.intersects(circle.bounds)) { // If it does, fill it with green: circle.fillColor = 'green'; largeCircle.fillColor = 'green'; } else { // If doesn't, fill it with red: circle.fillColor = 'red'; largeCircle.fillColor = 'red'; } } ``` ### Boolean Operations * `intersect(rect)` Returns a new rectangle representing the intersection of this rectangle with the specified rectangle. * Parameters: * `rect:` `Rectangle` — the rectangle to be intersected with this rectangle * Returns: * `Rectangle` — the largest rectangle contained in both the specified rectangle and in this rectangle Example:Intersecting two rectangles and visualizing the result using rectangle shaped paths: Run ```jsx // Create two rectangles that overlap each other var size = new Size(50, 50); var rectangle1 = new Rectangle(new Point(25, 15), size); var rectangle2 = new Rectangle(new Point(50, 40), size); // The rectangle that represents the intersection of the // two rectangles: var intersected = rectangle1.intersect(rectangle2); // To visualize the intersecting of the rectangles, we will // create rectangle shaped paths using the Path.Rectangle // constructor. // Have all newly created paths inherit a black stroke: project.currentStyle.strokeColor = 'black'; // Create two rectangle shaped paths using the abstract rectangles // we created before: new Path.Rectangle(rectangle1); new Path.Rectangle(rectangle2); // Create a path that represents the intersected rectangle, // and fill it with red: var intersectionPath = new Path.Rectangle(intersected); intersectionPath.fillColor = 'red'; ``` * `unite(rect)` Returns a new rectangle representing the union of this rectangle with the specified rectangle. * Parameters: * `rect:` `Rectangle` — the rectangle to be combined with this rectangle * Returns: * `Rectangle` — the smallest rectangle containing both the specified rectangle and this rectangle * `include(point)` Adds a point to this rectangle. The resulting rectangle is the smallest rectangle that contains both the original rectangle and the specified point. After adding a point, a call to `contains(point)` with the added point as an argument does not necessarily return `true`. The `rectangle.contains(point)` method does not return `true` for points on the right or bottom edges of a rectangle. Therefore, if the added point falls on the left or bottom edge of the enlarged rectangle, `rectangle.contains(point)` returns `false` for that point. * Parameters: * `point:` `Point` * Returns: * `Rectangle` — the smallest rectangle that contains both the original rectangle and the specified point * `expand(amount)` Returns a new rectangle expanded by the specified amount in horizontal and vertical directions. * Parameters: * `amount:` `Number`⟋`Size`⟋`Point` — the amount to expand the rectangle in both directions * Returns: * `Rectangle` — the expanded rectangle * `expand(hor, ver)` Returns a new rectangle expanded by the specified amounts in horizontal and vertical directions. * Parameters: * `hor:` `Number` — the amount to expand the rectangle in horizontal direction * `ver:` `Number` — the amount to expand the rectangle in vertical direction * Returns: * `Rectangle` — the expanded rectangle * `scale(amount)` Returns a new rectangle scaled by the specified amount from its center. * Parameters: * `amount:` `Number` * Returns: * `Rectangle` — the scaled rectangle * `scale(hor, ver)` Returns a new rectangle scaled in horizontal direction by the specified `hor` amount and in vertical direction by the specified `ver` amount from its center. * Parameters: * `hor:` `Number` * `ver:` `Number` * Returns: * `Rectangle` — the scaled rectangle # Matrix An affine transformation matrix performs a linear mapping from 2D coordinates to other 2D coordinates that preserves the “straightness” and “parallelness” of lines. Such a coordinate transformation can be represented by a 3 row by 3 column matrix with an implied last row of `[ 0 0 1 ]`. This matrix transforms source coordinates `(x, y)` into destination coordinates `(x',y')` by considering them to be a column vector and multiplying the coordinate vector by the matrix according to the following process: ``` [ x ] [ a c tx ] [ x ] [ a * x + c * y + tx ] [ y ] = [ b d ty ] [ y ] = [ b * x + d * y + ty ] [ 1 ] [ 0 0 1 ] [ 1 ] [ 1 ] ``` Note the locations of b and c. This class is optimized for speed and minimizes calculations based on its knowledge of the underlying matrix (as opposed to say simply performing matrix multiplication). ## Constructors * `Matrix()` Creates a 2D affine transformation matrix that describes the identity transformation. * Returns: * `Matrix` * `Matrix(a, b, c, d, tx, ty)` Creates a 2D affine transformation matrix. * Parameters: * `a:` `Number` — the a property of the transform * `b:` `Number` — the b property of the transform * `c:` `Number` — the c property of the transform * `d:` `Number` — the d property of the transform * `tx:` `Number` — the tx property of the transform * `ty:` `Number` — the ty property of the transform * Returns: * `Matrix` * `Matrix(values)` Creates a 2D affine transformation matrix. * Parameters: * `values:` Array of `Numbers` — the matrix values to initialize this matrix with * Returns: * `Matrix` * `Matrix(matrix)` Creates a 2D affine transformation matrix. * Parameters: * `matrix:` `Matrix` — the matrix to copy the values from * Returns: * `Matrix` ## Properties * `a` The value that affects the transformation along the x axis when scaling or rotating, positioned at (0, 0) in the transformation matrix. * Type: * `Number` * `b` The value that affects the transformation along the y axis when rotating or skewing, positioned at (1, 0) in the transformation matrix. * Type: * `Number` * `c` The value that affects the transformation along the x axis when rotating or skewing, positioned at (0, 1) in the transformation matrix. * Type: * `Number` * `d` The value that affects the transformation along the y axis when scaling or rotating, positioned at (1, 1) in the transformation matrix. * Type: * `Number` * `tx` The distance by which to translate along the x axis, positioned at (2, 0) in the transformation matrix. * Type: * `Number` * `ty` The distance by which to translate along the y axis, positioned at (2, 1) in the transformation matrix. * Type: * `Number` * `values` The matrix values as an array, in the same sequence as they are passed to `initialize(a, b, c, d, tx, ty)`. Read only. * Type: * Array of `Numbers` * `translation` The translation of the matrix as a vector. Read only. * Type: * `Point` * `scaling` The scaling values of the matrix, if it can be decomposed. Read only. * Type: * `Point` * See also: * `decompose`() * `rotation` The rotation angle of the matrix, if it can be decomposed. Read only. * Type: * `Number` * See also: * `decompose`() ## Methods * `set(...values)` Sets the matrix to the passed values. Note that any sequence of parameters that is supported by the various `Matrix`() constructors also work for calls of `set()`. * Parameters: * `values:` `any value` * Returns: * `Point` * `clone()` * Returns: * `Matrix` — a copy of this transform * `equals(matrix)` Checks whether the two matrices describe the same transformation. * Parameters: * `matrix:` `Matrix` — the matrix to compare this matrix to * Returns: * `Boolean` — `true` if the matrices are equal, `false` otherwise * `toString()` * Returns: * `String` — a string representation of this transform * `reset()` Resets the matrix by setting its values to the ones of the identity matrix that results in no transformation. * `apply([recursively])` Attempts to apply the matrix to the content of item that it belongs to, meaning its transformation is baked into the item’s content or children. * Parameters: * `recursively:` `Boolean` — controls whether to apply transformations recursively on children — optional, default: `true` * Returns: * `Boolean` — `true` if the matrix was applied, `false` otherwise * `translate(point)` Concatenates this matrix with a translate transformation. * Parameters: * `point:` `Point` — the vector to translate by * Returns: * `Matrix` — this affine transform * `translate(dx, dy)` Concatenates this matrix with a translate transformation. * Parameters: * `dx:` `Number` — the distance to translate in the x direction * `dy:` `Number` — the distance to translate in the y direction * Returns: * `Matrix` — this affine transform * `scale(scale[, center])` Concatenates this matrix with a scaling transformation. * Parameters: * `scale:` `Number` — the scaling factor * `center:` `Point` — the center for the scaling transformation — optional * Returns: * `Matrix` — this affine transform * `scale(hor, ver[, center])` Concatenates this matrix with a scaling transformation. * Parameters: * `hor:` `Number` — the horizontal scaling factor * `ver:` `Number` — the vertical scaling factor * `center:` `Point` — the center for the scaling transformation — optional * Returns: * `Matrix` — this affine transform * `rotate(angle, center)` Concatenates this matrix with a rotation transformation around an anchor point. * Parameters: * `angle:` `Number` — the angle of rotation measured in degrees * `center:` `Point` — the anchor point to rotate around * Returns: * `Matrix` — this affine transform * `rotate(angle, x, y)` Concatenates this matrix with a rotation transformation around an anchor point. * Parameters: * `angle:` `Number` — the angle of rotation measured in degrees * `x:` `Number` — the x coordinate of the anchor point * `y:` `Number` — the y coordinate of the anchor point * Returns: * `Matrix` — this affine transform * `shear(shear[, center])` Concatenates this matrix with a shear transformation. * Parameters: * `shear:` `Point` — the shear factor in x and y direction * `center:` `Point` — the center for the shear transformation — optional * Returns: * `Matrix` — this affine transform * `shear(hor, ver[, center])` Concatenates this matrix with a shear transformation. * Parameters: * `hor:` `Number` — the horizontal shear factor * `ver:` `Number` — the vertical shear factor * `center:` `Point` — the center for the shear transformation — optional * Returns: * `Matrix` — this affine transform * `skew(skew[, center])` Concatenates this matrix with a skew transformation. * Parameters: * `skew:` `Point` — the skew angles in x and y direction in degrees * `center:` `Point` — the center for the skew transformation — optional * Returns: * `Matrix` — this affine transform * `skew(hor, ver[, center])` Concatenates this matrix with a skew transformation. * Parameters: * `hor:` `Number` — the horizontal skew angle in degrees * `ver:` `Number` — the vertical skew angle in degrees * `center:` `Point` — the center for the skew transformation — optional * Returns: * `Matrix` — this affine transform * `append(matrix)` Appends the specified matrix to this matrix. This is the equivalent of multiplying `(this matrix) * (specified matrix)`. * Parameters: * `matrix:` `Matrix` — the matrix to append * Returns: * `Matrix` — this matrix, modified * `prepend(matrix)` Prepends the specified matrix to this matrix. This is the equivalent of multiplying `(specified matrix) * (this matrix)`. * Parameters: * `matrix:` `Matrix` — the matrix to prepend * Returns: * `Matrix` — this matrix, modified * `appended(matrix)` Returns a new matrix as the result of appending the specified matrix to this matrix. This is the equivalent of multiplying `(this matrix) * (specified matrix)`. * Parameters: * `matrix:` `Matrix` — the matrix to append * Returns: * `Matrix` — the newly created matrix * `prepended(matrix)` Returns a new matrix as the result of prepending the specified matrix to this matrix. This is the equivalent of multiplying `(specified matrix) * (this matrix)`. * Parameters: * `matrix:` `Matrix` — the matrix to prepend * Returns: * `Matrix` — the newly created matrix * `invert()` Inverts the matrix, causing it to perform the opposite transformation. If the matrix is not invertible (in which case `isSingular`() returns true), `null` is returned. * Returns: * `Matrix` — this matrix, or `null`, if the matrix is singular. * `inverted()` Creates a new matrix that is the inversion of this matrix, causing it to perform the opposite transformation. If the matrix is not invertible (in which case `isSingular`() returns true), `null` is returned. * Returns: * `Matrix` — this matrix, or `null`, if the matrix is singular. * `isIdentity()` * Returns: * `Boolean` — whether this matrix is the identity matrix * `isInvertible()` Checks whether the matrix is invertible. A matrix is not invertible if the determinant is 0 or any value is infinite or NaN. * Returns: * `Boolean` — whether the matrix is invertible * `isSingular()` Checks whether the matrix is singular or not. Singular matrices cannot be inverted. * Returns: * `Boolean` — whether the matrix is singular * `transform(point)` Transforms a point and returns the result. * Parameters: * `point:` `Point` — the point to be transformed * Returns: * `Point` — the transformed point * `transform(src, dst, count)` Transforms an array of coordinates by this matrix and stores the results into the destination array, which is also returned. * Parameters: * `src:` Array of `Numbers` — the array containing the source points as x, y value pairs * `dst:` Array of `Numbers` — the array into which to store the transformed point pairs * `count:` `Number` — the number of points to transform * Returns: * `Array of Numbers` — the dst array, containing the transformed coordinates * `inverseTransform(point)` Inverse transforms a point and returns the result. * Parameters: * `point:` `Point` — the point to be transformed * Returns: * `Point` * `decompose()` Decomposes the affine transformation described by this matrix into `scaling`, `rotation` and `skewing`, and returns an object with these properties. * Returns: * `Object` — the decomposed matrix * `applyToContext(ctx)` Applies this matrix to the specified Canvas Context. * Parameters: * `ctx:` `CanvasRenderingContext2D` # Project A Project object in Paper.js is what usually is referred to as the document: The top level object that holds all the items contained in the scene graph. As the term document is already taken in the browser context, it is called Project. Projects allow the manipulation of the styles that are applied to all newly created items, give access to the selected items, and will in future versions offer ways to query for items in the scene graph defining specific requirements, and means to persist and load from different formats, such as SVG and PDF. The currently active project can be accessed through the `paperScope.project` variable. An array of all open projects is accessible through the `paperScope.projects` variable. ## Constructors * `Project(element)` Creates a Paper.js project containing one empty `Layer`, referenced by `project.activeLayer`. Note that when working with PaperScript, a project is automatically created for us and the `paperScope.project` variable points to it. * Parameters: * `element:` `HTMLCanvasElement`⟋`String`⟋`Size` — the HTML canvas element that should be used as the element for the view, or an ID string by which to find the element, or the size of the canvas to be created for usage in a web worker. * Returns: * `Project` ## Properties * `view` The reference to the project’s view. Read only. * Type: * `View` * `currentStyle` The currently active path style. All selected items and newly created items will be styled with this style. * Type: * `Style` Example: ```jsx project.currentStyle = { fillColor: 'red', strokeColor: 'black', strokeWidth: 5 } // The following paths will take over all style properties of // the current style: var path = new Path.Circle(new Point(75, 50), 30); var path2 = new Path.Circle(new Point(175, 50), 20); ``` Example: ```jsx project.currentStyle.fillColor = 'red'; // The following path will take over the fill color we just set: var path = new Path.Circle(new Point(75, 50), 30); var path2 = new Path.Circle(new Point(175, 50), 20); ``` * `index` The index of the project in the `paperScope.projects` list. Read only. * Type: * `Number` ### Project Content * `layers` The layers contained within the project. Read only. * Type: * Array of `Layer` objects * `activeLayer` The layer which is currently active. New items will be created on this layer by default. Read only. * Type: * `Layer` * `symbolDefinitions` The symbol definitions shared by all symbol items contained place ind project. Read only. * Type: * Array of `SymbolDefinition` objects * `selectedItems` The selected items contained within the project. Read only. * Type: * Array of `Item` objects ## Methods * `activate()` Activates this project, so all newly created items will be placed in it. * `clear()` Clears the project by removing all `project.layers`. * `isEmpty()` Checks whether the project has any content or not. * Returns: * `Boolean` * `remove()` Removes this project from the `paperScope.projects` list, and also removes its view, if one was defined. * `selectAll()` Selects all items in the project. * `deselectAll()` Deselects all selected items in the project. ### Hierarchy Operations * `addLayer(layer)` Adds the specified layer at the end of the this project’s `layers` list. * Parameters: * `layer:` `Layer` — the layer to be added to the project * Returns: * `Layer` — the added layer, or `null` if adding was not possible * `insertLayer(index, layer)` Inserts the specified layer at the specified index in this project’s `layers` list. * Parameters: * `index:` `Number` — the index at which to insert the layer * `layer:` `Layer` — the layer to be inserted in the project * Returns: * `Layer` — the added layer, or `null` if adding was not possible ### Hit-testing, Fetching and Matching Items * `hitTest(point[, options])` Performs a hit-test on the items contained within the project 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: * Options: * `options.tolerance: Number` — the tolerance of the hit-test — default: `paperScope.settings`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * Parameters: * `point:` `Point` — the point where the hit-test should be performed * `options:` `Object` — optional, default: `{ fill: true, stroke: true, segments: true, tolerance: settings.hitTolerance }` * Returns: * `HitResult` — a hit result object that contains more information about what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 * `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 or `null` if nothing was hit * See also: * `hitTest(point[, options])`; * `getItems(options)` Fetch items contained within the project whose properties match the criteria in the specified object. Extended matching of properties is possible by providing a comparator 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` or `options.overlapping` to a rectangle describing the area in which the items either have to be fully or partly contained. * 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 the `match` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching items contained in the project * See also: * `item.matches(options)` * `item.getItems(options)` Example:Fetch all selected path items: ```jsx var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black' }); var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'black' }); // Select path2: path2.selected = true; // Fetch all selected path items: var items = project.getItems({ selected: true, class: Path }); // Change the fill color of the selected path to red: items[0].fillColor = 'red'; ``` Example:Fetch all items with a specific fill color: ```jsx var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black' }); var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'purple' }); // Fetch all items with a purple fill color: var items = project.getItems({ fillColor: 'purple' }); // Select the fetched item: items[0].selected = true; ``` Example:Fetch items at a specific position: ```jsx var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black' }); var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'black' }); // Fetch all path items positioned at {x: 150, y: 150}: var items = project.getItems({ position: [150, 50] }); // Select the fetched path: items[0].selected = true; ``` Example:Fetch items using a comparator function: ```jsx // Create a circle shaped path: var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black' }); // Create a circle shaped path with 50% opacity: var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'black', opacity: 0.5 }); // Fetch all items whose opacity is smaller than 1 var items = paper.project.getItems({ opacity: function(value) { return value < 1; } }); // Select the fetched item: items[0].selected = true; ``` Example:Fetch items using a comparator function (2): ```jsx // Create a rectangle shaped path (4 segments): var path1 = new Path.Rectangle({ from: [25, 25], to: [75, 75], strokeColor: 'black', strokeWidth: 10 }); // Create a line shaped path (2 segments): var path2 = new Path.Line({ from: [125, 50], to: [175, 50], strokeColor: 'black', strokeWidth: 10 }); // Fetch all paths with 2 segments: var items = project.getItems({ class: Path, segments: function(segments) { return segments.length == 2; } }); // Select the fetched path: items[0].selected = true; ``` Example:Match (nested) properties of the data property: ```jsx // Create a black circle shaped path: var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black', data: { person: { name: 'john', length: 200, hair: true } } }); // Create a red circle shaped path: var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'red', data: { person: { name: 'john', length: 180, hair: false } } }); // Fetch all items whose data object contains a person // object whose name is john and length is 180: var items = paper.project.getItems({ data: { person: { name: 'john', length: 180 } } }); // Select the fetched item: items[0].selected = true; ``` Example:Match strings using regular expressions: ```jsx // Create a path named 'aardvark': var path1 = new Path.Circle({ center: [50, 50], radius: 25, fillColor: 'black', name: 'aardvark' }); // Create a path named 'apple': var path2 = new Path.Circle({ center: [150, 50], radius: 25, fillColor: 'black', name: 'apple' }); // Create a path named 'banana': var path2 = new Path.Circle({ center: [250, 50], radius: 25, fillColor: 'black', name: 'banana' }); // Fetch all items that have a name starting with 'a': var items = project.getItems({ name: /^a/ }); // Change the fill color of the matched items: for (var i = 0; i < items.length; i++) { items[i].fillColor = 'red'; } ``` * `getItem(options)` Fetch the first item contained within the project whose properties match the criteria 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 `getItems(options)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first item in the project matching the given criteria ### Importing / Exporting JSON and SVG * `exportJSON([options])` Exports (serializes) the project with all its layers and child items to a JSON data object or string. * Options: * `options.asString: Boolean` — whether the JSON is returned as a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `String` — the exported JSON data * `importJSON(json)` Imports (deserializes) the stored JSON data into the project. Note that the project is not cleared first. You can call `project.clear`() to do so. * Parameters: * `json:` `String` — the JSON data to import from * Returns: * `Item` — the imported item * `exportSVG([options])` Exports the project with all its layers and child items as an SVG DOM, all contained in one top level SVG group node. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the project converted to an SVG node or a `String` depending on `option.asString` value * `importSVG(svg[, options])` Converts the provided SVG content into Paper.js items and adds them to the active layer of this project. Note that the project is not cleared first. You can call `project.clear`() 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 converted `item` and the original `svg` 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 project that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 active layer of this project. Note that the project is not cleared first. You can call `project.clear`() 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 converted `item` and the original `svg` data as a string. Only required when loading from external files. * Returns: * `Item` — the newly created Paper.js item containing the converted SVG content # Item The Item type allows you to access and modify the items in Paper.js projects. Its functionality is inherited by different project item types such as [`Path`](/paths/path), [`CompoundPath`](/paths/compoundpath), [`Group`](/project-and-items/group), [`Layer`](/project-and-items/layer) and [`Raster`](/project-and-items/raster). They each add a layer of functionality that is unique to their type, but share the underlying properties and functions that they inherit from Item. ## Properties * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods * `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `Item` * `exportSVG([options])` Exports the item with its content and child items as an SVG DOM. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the item converted to an SVG node or a `String` depending on `option.asString` value * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # Layer Extends [**`Item`**](/project-and-items/item), [**`Group`**](/project-and-items/group) The Layer item represents a layer in a Paper.js project. The layer which is currently active can be accessed through `project.activeLayer`. An array of all layers in a project can be accessed through `project.layers`. ## Constructors * `Layer([children])` Creates a new Layer item and places it at the end of the `project.layers` array. The newly created layer will be activated, so all newly created items will be placed within it. * Parameters: * `children:` Array of `Item` objects — An array of items that will be added to the newly created layer — optional * Returns: * `Layer` Example: ``` var layer = new Layer(); ``` * `Layer(object)` Creates a new Layer item and places it at the end of the `project.layers` array. The newly created layer will be activated, so all newly created items will be placed within it. * Parameters: * `object:` `Object` — an object containing the properties to be set on the layer * Returns: * `Layer` Example: ``` var path = new Path([100, 100], [100, 200]); var path2 = new Path([50, 150], [150, 150]); // Create a layer. The properties in the object literal // are set on the newly created layer. var layer = new Layer({ children: [path, path2], strokeColor: 'black', position: view.center }); ``` ## Methods * `activate()` Activates the layer. Example: ``` var firstLayer = project.activeLayer; var secondLayer = new Layer(); console.log(project.activeLayer == secondLayer); // true firstLayer.activate(); console.log(project.activeLayer == firstLayer); // true ``` ## Properties inherited from `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` ## Properties inherited from `Group` * `clipped` Specifies whether the group item is to be clipped. When setting to `true`, the first child in the group is automatically defined as the clipping mask. * Type: * `Boolean` Example: ``` var star = new Path.Star({ center: view.center, points: 6, radius1: 20, radius2: 40, fillColor: 'red' }); var circle = new Path.Circle({ center: view.center, radius: 25, strokeColor: 'black' }); // Create a group of the two items and clip it: var group = new Group(circle, star); group.clipped = true; // Lets animate the circle: function onFrame(event) { var offset = Math.sin(event.count / 30) * 30; circle.position.x = view.center.x + offset; } ``` # Group Extends [**`Item`**](/project-and-items/item) A Group is a collection of items. When you transform a Group, its children are treated as a single unit without changing their relative positions. ## Constructors * `Group([children])` Creates a new Group item and places it at the top of the active layer. * Parameters: * `children:` Array of `Item` objects — An array of children that will be added to the newly created group — optional * Returns: * `Group` Example:Create a group containing two paths: ``` var path = new Path([100, 100], [100, 200]); var path2 = new Path([50, 150], [150, 150]); // Create a group from the two paths: var group = new Group([path, path2]); // Set the stroke color of all items in the group: group.strokeColor = 'black'; // Move the group to the center of the view: group.position = view.center; ``` Example:Click in the view to add a path to the group, which in turn is rotated every frame: ``` var group = new Group(); function onMouseDown(event) { // Create a new circle shaped path at the position // of the mouse: var path = new Path.Circle(event.point, 5); path.fillColor = 'black'; // Add the path to the group's children list: group.addChild(path); } function onFrame(event) { // Rotate the group by 1 degree from // the centerpoint of the view: group.rotate(1, view.center); } ``` * `Group(object)` Creates a new Group item and places it at the top of the active layer. * Parameters: * `object:` `Object` — an object containing the properties to be set on the group * Returns: * `Group` Example: ``` var path = new Path([100, 100], [100, 200]); var path2 = new Path([50, 150], [150, 150]); // Create a group from the two paths: var group = new Group({ children: [path, path2], // Set the stroke color of all items in the group: strokeColor: 'black', // Move the group to the center of the view: position: view.center }); ``` ## Properties * `clipped` Specifies whether the group item is to be clipped. When setting to `true`, the first child in the group is automatically defined as the clipping mask. * Type: * `Boolean` Example: ``` var star = new Path.Star({ center: view.center, points: 6, radius1: 20, radius2: 40, fillColor: 'red' }); var circle = new Path.Circle({ center: view.center, radius: 25, strokeColor: 'black' }); // Create a group of the two items and clip it: var group = new Group(circle, star); group.clipped = true; // Lets animate the circle: function onFrame(event) { var offset = Math.sin(event.count / 30) * 30; circle.position.x = view.center.x + offset; } ``` ## Properties inherited from `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # Shape Extends [**`Item`**](/project-and-items/item) ## Constructors * `Shape.Circle(center, radius)` Creates a circular shape item. * Parameters: * `center:` `Point` — the center point of the circle * `radius:` `Number` — the radius of the circle * Returns: * `Shape` — the newly created shape Example: ``` var shape = new Shape.Circle(new Point(80, 50), 30); shape.strokeColor = 'black'; ``` * `Shape.Circle(object)` Creates a circular shape item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the shape’s attributes * Returns: * `Shape` — the newly created shape Example: ``` var shape = new Shape.Circle({ center: [80, 50], radius: 30, strokeColor: 'black' }); ``` * `Shape.Rectangle(rectangle[, radius])` Creates a rectangular shape item, with optionally rounded corners. * Parameters: * `rectangle:` `Rectangle` — the rectangle object describing the geometry of the rectangular shape to be created * `radius:` `Size` — the size of the rounded corners — optional, default: `null` * Returns: * `Shape` — the newly created shape Example: ``` var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60)); var shape = new Shape.Rectangle(rectangle); shape.strokeColor = 'black'; ``` Example:The same, with rounder corners ``` var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60)); var cornerSize = new Size(10, 10); var shape = new Shape.Rectangle(rectangle, cornerSize); shape.strokeColor = 'black'; ``` * `Shape.Rectangle(point, size)` Creates a rectangular shape item from a point and a size object. * Parameters: * `point:` `Point` — the rectangle’s top-left corner. * `size:` `Size` — the rectangle’s size. * Returns: * `Shape` — the newly created shape Example: ``` var point = new Point(20, 20); var size = new Size(60, 60); var shape = new Shape.Rectangle(point, size); shape.strokeColor = 'black'; ``` * `Shape.Rectangle(from, to)` Creates a rectangular shape 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. * Parameters: * `from:` `Point` — the first point defining the rectangle * `to:` `Point` — the second point defining the rectangle * Returns: * `Shape` — the newly created shape Example: ```jsx var from = new Point(20, 20); var to = new Point(80, 80); var shape = new Shape.Rectangle(from, to); shape.strokeColor = 'black'; ``` * `Shape.Rectangle(object)` Creates a rectangular shape item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the shape’s attributes * Returns: * `Shape` — the newly created shape Example: ``` var shape = new Shape.Rectangle({ point: [20, 20], size: [60, 60], strokeColor: 'black' }); ``` Example: ``` var shape = new Shape.Rectangle({ from: [20, 20], to: [80, 80], strokeColor: 'black' }); ``` Example: ``` var shape = new Shape.Rectangle({ rectangle: { topLeft: [20, 20], bottomRight: [80, 80] }, strokeColor: 'black' }); ``` Example: ``` var shape = new Shape.Rectangle({ topLeft: [20, 20], bottomRight: [80, 80], radius: 10, strokeColor: 'black' }); ``` * `Shape.Ellipse(rectangle)` Creates an elliptical shape item. * Parameters: * `rectangle:` `Rectangle` — the rectangle circumscribing the ellipse * Returns: * `Shape` — the newly created shape Example: ``` var rectangle = new Rectangle(new Point(20, 20), new Size(180, 60)); var shape = new Shape.Ellipse(rectangle); shape.fillColor = 'black'; ``` * `Shape.Ellipse(object)` Creates an elliptical shape item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the shape’s attributes * Returns: * `Shape` — the newly created shape Example: ``` var shape = new Shape.Ellipse({ point: [20, 20], size: [180, 60], fillColor: 'black' }); ``` Example:Placing by center and radius ``` var shape = new Shape.Ellipse({ center: [110, 50], radius: [90, 30], fillColor: 'black' }); ``` ## Properties * `type` The type of shape of the item as a string. * Type: * `String` * `size` The size of the shape. * Type: * `Size` * `radius` The radius of the shape, as a number if it is a circle, or a size object for ellipses and rounded rectangles. * Type: * `Number`⟋`Size` ## Methods * `toPath([insert])` Creates a new path item with same geometry as this shape item, and inherits all settings from it, similar to `item.clone`(). * Parameters: * `insert:` `Boolean` — specifies whether the new path should be inserted into the scene graph. When set to `true`, it is inserted above the shape item — optional, default: `true` * Returns: * `Path` — the newly created path item with the same geometry as this shape item * See also: * `path.toShape(insert)` ## Properties inherited from `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ``` var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ``` var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ``` var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ``` var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ``` // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ``` 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 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ``` // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ``` // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ``` 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(); path.parent = group; // 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ``` 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ``` var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ``` var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ``` // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ``` // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ``` // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ``` // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ``` // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ``` // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ``` // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ``` 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ``` var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ``` var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ``` var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ``` var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `Item` * `exportSVG([options])` Exports the item with its content and child items as an SVG DOM. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the item converted to an SVG node or a `String` depending on `option.asString` value * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ``` // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ``` // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ``` // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ``` var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ``` // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ``` // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ``` 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ``` 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ``` function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ``` function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ``` 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ``` function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # Raster Extends **`[Item](Item%20eab4980134ff44238bc91e6d4a28d6f9.md)`** The Raster item represents an image in a Paper.js project. ## Constructors * `Raster([source[, position]])` Creates a new raster item from the passed argument, and places it in the active layer. `source` can either be a DOM Image, a Canvas, or a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas). * Parameters: * `source:` `HTMLImageElement`⟋`HTMLCanvasElement`⟋`String` — the source of the raster — optional * `position:` `Point` — the center position at which the raster item is placed — optional * Returns: * `Raster` Example:Creating a raster using a url ``` var url = 'http://assets.paperjs.org/images/marilyn.jpg'; var raster = new Raster(url); // If you create a Raster using a url, you can use the onLoad // handler to do something once it is loaded: raster.onLoad = function() { console.log('The image has loaded.'); }; ``` Example:Creating a raster using the id of a DOM Image: ``` // Create a raster using the id of the image: var raster = new Raster('art'); ``` Example:Creating a raster using a DOM Image: ``` // Find the element using its id: var imageElement = document.getElementById('art'); // Create the raster: var raster = new Raster(imageElement); ``` * `Raster(size[, position])` Creates a new empty raster of the given size, and places it in the active layer. * Parameters: * `size:` `Size` — the size of the raster * `position:` `Point` — the center position at which the raster item is placed — optional * Returns: * `Raster` Example:Creating an empty raster and fill it with random pixels: ``` var width = 100; var height = 100; // Create an empty raster placed at view center. var raster = new Raster(new Size(width, height), view.center); // For all of its pixels... for (var i = 0; i < width; i++) { for (var j = 0; j < height; j++) { // ...set a random color. raster.setPixel(i, j, Color.random()); } } ``` * `Raster(object)` Creates a new raster from an object description, and places it in the active layer. * Parameters: * `object:` `Object` — an object containing properties to be set on the raster * Returns: * `Raster` Example: ``` var raster = new Raster({ source: 'http://assets.paperjs.org/images/marilyn.jpg', position: view.center }); raster.scale(0.5); raster.rotate(10); ``` ## Properties * `size`3245\` The size of the raster in pixels. * Type: * `Size` * `width` The width of the raster in pixels. * Type: * `Number` * `height` The height of the raster in pixels. * Type: * `Number` * `loaded` The loading state of the raster image. Read only. * Type: * `Boolean` * `resolution` The resolution of the raster at its current size, in PPI (pixels per inch). Read only. * Type: * `Size` * `image` The HTMLImageElement or Canvas element of the raster, if one is associated. Note that for consistency, a `onLoad` event will be triggered on the raster even if the image has already finished loading before, or if we are setting the raster to a canvas. * Type: * `HTMLImageElement`⟋`HTMLCanvasElement` * `canvas` The Canvas object of the raster. If the raster was created from an image, accessing its canvas causes the raster to try and create one and draw the image into it. Depending on security policies, this might fail, in which case `null` is returned instead. * Type: * `HTMLCanvasElement` * `context` The Canvas 2D drawing context of the raster. * Type: * `CanvasRenderingContext2D` * `source` The source of the raster, which can be set using a DOM Image, a Canvas, a data url, a string describing the URL to load the image from, or the ID of a DOM element to get the image from (either a DOM Image or a Canvas). Reading this property will return the url of the source image or a data-url. Note that for consistency, a `onLoad` event will be triggered on the raster even if the image has already finished loading before. * Type: * `HTMLImageElement`⟋`HTMLCanvasElement`⟋`String` Example: ``` var raster = new Raster(); raster.source = 'http://paperjs.org/about/paper-js.gif'; raster.position = view.center; ``` Example: ``` var raster = new Raster({ source: 'http://paperjs.org/about/paper-js.gif', position: view.center }); ``` * `crossOrigin` The crossOrigin value to be used when loading the image resource, in order to support CORS. Note that this needs to be set before setting the `source` property in order to always work (e.g. when the image is cached in the browser). * Type: * `String` Example: ``` var raster = new Raster({ crossOrigin: 'anonymous', source: 'http://assets.paperjs.org/images/marilyn.jpg', position: view.center }); console.log(view.element.toDataURL('image/png').substring(0, 32)); ``` * `smoothing` Specifies if the raster should be smoothed when scaled up or if the pixels should be scaled up by repeating the nearest neighboring pixels. * Default: * `true` * Type: * `Boolean` Example: ``` var raster = new Raster({ source: 'http://assets.paperjs.org/images/marilyn.jpg', smoothing: false }); raster.scale(5); ``` ### Event Handlers * `onLoad` The event handler function to be called when the underlying image has finished loading and is ready to be used. This is also triggered when the image is already loaded, or when a canvas is used instead of an image. * Type: * `Function`⟋`null` Example: ``` var url = 'http://assets.paperjs.org/images/marilyn.jpg'; var raster = new Raster(url); // If you create a Raster using a url, you can use the onLoad // handler to do something once it is loaded: raster.onLoad = function() { console.log('The image has finished loading.'); }; // As with all events in paper.js, you can also use this notation instead // to install multiple handlers: raster.on('load', function() { console.log('Now the image is definitely ready.'); }); ``` * `onError` The event handler function to be called when there is an error loading the underlying image. * Type: * `Function`⟋`null` ## Methods * `getSubCanvas(rect)` Extracts a part of the Raster’s content as a sub image, and returns it as a Canvas object. * Parameters: * `rect:` `Rectangle` — the boundaries of the sub image in pixel coordinates * Returns: * `HTMLCanvasElement` — the sub image as a Canvas object * `getSubRaster(rect)` Extracts a part of the raster item’s content as a new raster item, placed in exactly the same place as the original content. * Parameters: * `rect:` `Rectangle` — the boundaries of the sub raster in pixel coordinates * Returns: * `Raster` — the sub raster as a newly created raster item * `toDataURL()` Returns a Base 64 encoded `data:` URL representation of the raster. * Returns: * `String` * `drawImage(image, point)` Draws an image on the raster. * Parameters: * `image:` `CanvasImageSource` * `point:` `Point` — the offset of the image as a point in pixel coordinates * `getAverageColor(object)` Calculates the average color of the image within the given path, rectangle or point. This can be used for creating raster image effects. * Parameters: * `object:` `Path`⟋`Rectangle`⟋`Point` * Returns: * `Color` — the average color contained in the area covered by the specified path, rectangle or point ### Pixels * `getPixel(x, y)` Gets the color of a pixel in the raster. * Parameters: * `x:` `Number` — the x offset of the pixel in pixel coordinates * `y:` `Number` — the y offset of the pixel in pixel coordinates * Returns: * `Color` — the color of the pixel * `getPixel(point)` Gets the color of a pixel in the raster. * Parameters: * `point:` `Point` — the offset of the pixel as a point in pixel coordinates * Returns: * `Color` — the color of the pixel * `setPixel(x, y, color)` Sets the color of the specified pixel to the specified color. * Parameters: * `x:` `Number` — the x offset of the pixel in pixel coordinates * `y:` `Number` — the y offset of the pixel in pixel coordinates * `color:` `Color` — the color that the pixel will be set to * `setPixel(point, color)` Sets the color of the specified pixel to the specified color. * Parameters: * `point:` `Point` — the offset of the pixel as a point in pixel coordinates * `color:` `Color` — the color that the pixel will be set to * `clear()` Clears the image, if it is backed by a canvas. ### Image Data * `createImageData(size)` * Parameters: * `size:` `Size` * Returns: * `ImageData` * `getImageData(rect)` * Parameters: * `rect:` `Rectangle` * Returns: * `ImageData` * `setImageData(data, point)` * Parameters: * `data:` `ImageData` * `point:` `Point` ## Properties inherited from `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # HitResult A HitResult object contains information about the results of a hit test. It is returned by `item.hitTest(point)` and `project.hitTest(point)`. ## Properties * `type` Describes the type of the hit result. For example, if you hit a segment point, the type would be `'segment'`. * Values: * `'segment'`, `'handle-in'`, `'handle-out'`, `'curve'`, `'stroke'`, `'fill'`, `'bounds'`, `'center'`, `'pixel'` * Type: * `String` * `name` If the HitResult has a `hitResult.type` of `'bounds'`, this property describes which corner of the bounding rectangle was hit. * Values: * `'top-left'`, `'top-right'`, `'bottom-left'`, `'bottom-right'`, `'left-center'`, `'top-center'`, `'right-center'`, `'bottom- center'` * Type: * `String` * `item` The item that was hit. * Type: * `Item` * `location` If the HitResult has a type of ‘curve’ or ‘stroke’, this property gives more information about the exact position that was hit on the path. * Type: * `CurveLocation` * `color` If the HitResult has a type of ‘pixel’, this property refers to the color of the pixel on the `Raster` that was hit. * Type: * `Color`⟋`null` * `segment` If the HitResult has a type of ‘stroke’, ‘segment’, ‘handle-in’ or ‘handle-out’, this property refers to the segment that was hit or that is closest to the hitResult.location on the curve. * Type: * `Segment` * `point` Describes the actual coordinates of the segment, handle or bounding box corner that was hit. * Type: * `Point` # PathItem Extends [**`Item`**](/project-and-items/item) The PathItem class is the base for any items that describe paths and offer standardised methods for drawing and path manipulation, such as `[Path](Path%20f91b7d17f1f747e1950d655ad8aaf2c5.md)` and `[CompoundPath](CompoundPath%200e46476761cb45a0ab9ed15d5e6dfffb.md)`. ## Properties * `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 ### 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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 subtract * `options:` `Object` — the boolean operation options — optional * Returns: * `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 of * `options:` `Object` — the boolean operation options — optional * Returns: * `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)` and `intersect(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 by * `options:` `Object` — the boolean operation options — optional * Returns: * `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 by `clockwise`, otherwise the orientation of the largest root child is used. — optional * Returns: * `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 of `CurveLocation` objects. `CompoundPath` items are also supported. * Parameters: * `path:` `PathItem` — the other item to find the intersections with * `include:` `Function` — a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall return `true` to include a location, `false` otherwise. — optional * Returns: * `Array of CurveLocation` objects — the locations of all intersection between the paths * See also: * `getCrossings(path)` Example:Finding the intersections between two paths ```jsx var path = new Path.Rectangle(new Point(30, 25), new Size(50, 50)); path.strokeColor = 'black'; var secondPath = path.clone(); var intersectionGroup = new Group(); function onFrame(event) { secondPath.rotate(1); var intersections = path.getIntersections(secondPath); intersectionGroup.removeChildren(); for (var i = 0; i < intersections.length; i++) { var intersectionPath = new Path.Circle({ center: intersections[i].point, radius: 4, fillColor: 'red', parent: intersectionGroup }); } } ``` * `getCrossings(path)` 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. * Parameters: * `path:` `PathItem` — the other item to find the crossings with * Returns: * `Array of CurveLocation` objects — the locations of all crossings between the paths * See 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 location * Returns: * `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 point * Returns: * `Point` — the point on the path that’s the closest to the specified point Example: ```jsx var star = new Path.Star({ center: view.center, points: 10, radius1: 30, radius2: 60, strokeColor: 'black' }); var circle = new Path.Circle({ center: view.center, radius: 3, fillColor: 'red' }); function onMouseMove(event) { // Get the nearest point from the mouse position // to the star shaped path: var nearestPoint = star.getNearestPoint(event.point); // Move the red circle to the nearest point: circle.position = nearestPoint; } ``` ### Path Manipulation * `reverse()` Reverses the orientation of the path item. When called on `CompoundPath` items, each of the nested paths is reversed. On `Path` items, the sequence of `path.segments` is reversed. * `flatten([flatness])` Flattens the curves in path items to a sequence of straight lines, by subdividing them enough times until the specified maximum error is met. * Parameters: * `flatness:` `Number` — the maximum error between the flattened lines and the original curves — optional, default: `0.25` Example:Flattening a circle shaped path: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Select the path, so we can inspect its segments: path.selected = true; // Create a copy of the path and move it by 150 points: var copy = path.clone(); copy.position.x += 150; // Flatten the copied path, with a maximum error of 4 points: copy.flatten(4); ``` * `smooth([options])` 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. 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 `options.from` and `options.to` 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. Four different smoothing methods are available: * `'continuous'` 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. This method tends to result in the smoothest results, but does not allow for further parametrization of the handles. * `'asymmetric'` is based on the same principle as `'continuous'` 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. * `'catmull-rom'` uses the Catmull-Rom spline to smooth the segment. The optionally passed factor controls the knot parametrization of the algorithm: * `0.0`: the standard, uniform Catmull-Rom spline * `0.5`: the centripetal Catmull-Rom spline, guaranteeing no self-intersections * `1.0`: the chordal Catmull-Rom spline * `'geometric'` 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. The optionally passed factor defines the tension parameter (`0…1`), controlling the amount of smoothing as a factor by which to scale each handle. * Options: * `options.type: String` — the type of smoothing method: `‘continuous’`, `‘asymmetric’`, `‘catmull-rom’`, `‘geometric’` — default: `‘asymmetric’` * `options.factor: Number` — the factor parameterizing the smoothing method — default: `0.5` for `'catmull-rom'`, `0.4` for `'geometric'` * `options.from: Number`⟋`Segment`⟋`Curve` — 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. * `options.to: Number`⟋`Segment`⟋`Curve` — 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. * Parameters: * `options:` `Object` — the smoothing options — optional * See also: * `segment.smooth([options])` Example:Smoothing a closed shape: ```jsx // Create a rectangular path with its top-left point at // {x: 30, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle({ point: [30, 25], size: [50, 50], strokeColor: 'black', }); // Select the path, so we can see its handles: path.fullySelected = true; // Create a copy of the path and move it 100 to the right: var copy = path.clone(); copy.position.x += 100; // Smooth the segments of the copy: copy.smooth({ type: 'continuous' }); ``` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 50)); var y = 5; var x = 3; for (var i = 0; i < 28; i++) { y *= -1.1; x *= 1.1; path.lineBy(x, y); } // Create a copy of the path and move it 100 down: var copy = path.clone(); copy.position.y += 120; // Select the path, so we can see its handles: copy.fullySelected = true; // Smooth the path using centripetal Catmull-Rom splines: copy.smooth({ type: 'catmull-rom', factor: 0.5 }); ``` Example:Smoothing ranges of paths, using segments, curves or indices: ```jsx // Create 5 rectangles, next to each other: var paths = []; for (var i = 0; i < 5; i++) { paths.push(new Path.Rectangle({ point: [30 + i * 100, 30], size: [50, 50], fullySelected: true })); } // Smooth a range, using segments: paths[1].smooth({ type: 'continuous', from: paths[1].segments[0], to: paths[1].segments[2] }); // Smooth a range, using curves: paths[2].smooth({ type: 'continuous', from: paths[2].curves[0], to: paths[2].curves[1] }); // Smooth a range, using indices: paths[3].smooth({ type: 'continuous', from: 0, to: 2 }); // Smooth a range, using negative indices: paths[4].smooth({ type: 'continuous', from: -1, to: 1 }); ``` * `simplify([tolerance])` 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 `CompoundPath` items, each of the nested paths is simplified. On `Path` items, the `path.segments` array is processed and replaced by the resulting sequence of fitted curves. This method can be used to process and simplify the point data received from a mouse or touch device. * Parameters: * `tolerance:` `Number` — the allowed maximum error when fitting the curves through the segment points — optional, default: `2.5` * Returns: * `Boolean` — `true` if the method was capable of fitting curves through the path’s segment points, `false` otherwise Example:Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify(): ```jsx var path; function onMouseDown(event) { // If we already made a path before, deselect it: if (path) { path.selected = false; } // Create a new path and add the position of the mouse // as its first segment. Select it, so we can see the // segment points: path = new Path({ segments: [event.point], strokeColor: 'black', selected: true }); } function onMouseDrag(event) { // On every drag event, add a segment to the path // at the position of the mouse: path.add(event.point); } function onMouseUp(event) { // When the mouse is released, simplify the path: path.simplify(); path.selected = true; } ``` * `interpolate(from, to, factor)` 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. * Parameters: * `from:` `PathItem` — the path item defining the geometry when `factor` is `0` * `to:` `PathItem` — the path item defining the geometry when `factor` is `1` * `factor:` `Number` — the interpolation coefficient, typically between `0` and `1`, but extrapolation is possible too * `compare(path)` Compares the geometry of two paths to see if they describe the same shape, detecting cases where paths start in different segments or even use different amounts of curves to describe the same shape, as long as their orientation is the same, and their segments and handles really result in the same visual appearance of curves. * Parameters: * `path:` `PathItem` — the path to compare this path’s geometry with * Returns: * `Boolean` — `true` if two paths describe the same shape, `false` otherwise ### Postscript Style Drawing Commands * `moveTo(point)` 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. * Parameters: * `point:` `Point` — the point in which to start the path * `lineTo(point)` Adds a straight curve to the path, from the the last segment in the path to the specified point. * Parameters: * `point:` `Point` — the destination point of the newly added straight curve * `arcTo(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` point, to the specified `to` point, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the point where the arc should pass through * `to:` `Point` — the point where the arc should end Example: ```jsx var path = new Path(); path.strokeColor = 'black'; var firstPoint = new Point(30, 75); path.add(firstPoint); // The point through which we will create the arc: var throughPoint = new Point(40, 40); // The point at which the arc will end: var toPoint = new Point(130, 75); // Draw an arc through 'throughPoint' to 'toPoint' path.arcTo(throughPoint, toPoint); // Add a red circle shaped path at the position of 'throughPoint': var circle = new Path.Circle(throughPoint, 3); circle.fillColor = 'red'; ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; function onMouseDrag(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw an arc through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.arcTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } // When the mouse is released, deselect the path // and fill it with black. function onMouseUp(event) { myPath.selected = false; myPath.fillColor = 'black'; } ``` * `arcTo(to[, clockwise])` Adds an arc from the position of the last segment in the path to the specified point, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the point where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 75)); path.arcTo(new Point(130, 75)); var path2 = new Path(); path2.strokeColor = 'red'; path2.add(new Point(180, 25)); // To draw an arc in anticlockwise direction, // we pass `false` as the second argument to arcTo: path2.arcTo(new Point(280, 25), false); ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; // The mouse has to move at least 20 points before // the next mouse drag event is fired: tool.minDistance = 20; // When the user clicks, create a new path and add // the current mouse position to it as its first segment: function onMouseDown(event) { myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(event.point); } // On each mouse drag event, draw an arc to the current // position of the mouse: function onMouseDrag(event) { myPath.arcTo(event.point); } ``` * `curveTo(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` point, to the specified destination point by adding one segment to the path. * Parameters: * `through:` `Point` — the point through which the curve should pass * `to:` `Point` — the destination point of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` Example:Interactive example. Move your mouse around the view below: ```jsx var myPath; function onMouseMove(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw a curve through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.curveTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } ``` * `cubicCurveTo(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleOut` of its first segment are calculated * `handle2:` `Point` — the location of the second handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveTo(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the location of the handle of the newly added quadratic curve in absolute coordinates, out of which the relative values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `closePath()` Closes the path. When closed, Paper.js connects the first and last segment of the path with an additional curve. The difference to setting `path.closed` to `true` is that this will also merge the first segment with the last if they lie in the same location. * See also: * `path.closed` ### Relative Drawing Commands * `moveBy(to)` 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. * Parameters: * `to:` `Point` * `lineBy(point)` Adds a straight curve to the path, from the the last segment in the path to the `to` vector specified relatively to it. * Parameters: * `point:` `Point` — the vector describing the destination of the newly added straight curve Example: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add a segment at {x: 50, y: 50} path.add(25, 25); // Add a segment relative to the last segment of the path. // 50 in x direction and 0 in y direction, becomes {x: 75, y: 25} path.lineBy(50, 0); // 0 in x direction and 50 in y direction, becomes {x: 75, y: 75} path.lineBy(0, 50); ``` Example:Drawing a spiral using lineBy: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add the first segment at {x: 50, y: 50} path.add(view.center); // Loop 500 times: for (var i = 0; i < 500; i++) { // Create a vector with an ever increasing length // and an angle in increments of 45 degrees var vector = new Point({ angle: i * 45, length: i / 2 }); // Add the vector relatively to the last segment point: path.lineBy(vector); } // Smooth the handles of the path: path.smooth(); // Uncomment the following line and click on 'run' to see // the construction of the path: // path.selected = true; ``` * `arcBy(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the vector where the arc should pass through * `to:` `Point` — the vector where the arc should end * `arcBy(to[, clockwise])` Adds an arc from the position of the last segment in the path to the `to` vector specified relatively to it, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the vector where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` * `curveBy(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one segment to the path. * Parameters: * `through:` `Point` — the vector through which the curve should pass * `to:` `Point` — the destination vector of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` * `cubicCurveBy(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the to the specified `to` vector, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve * `handle2:` `Point` — the location of the second handle of the newly added curve * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveBy(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the handle of the newly added quadratic curve out of which the values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve ## Static Methods * `PathItem.create(pathData)` Creates a path item from the given SVG path-data, determining if the data describes a plain path or a compound-path with multiple sub-paths. * Parameters: * `pathData:` `String` — the SVG path-data to parse * Returns: * `Path`⟋`CompoundPath` — the newly created path item * `PathItem.create(segments)` Creates a path item from the given segments array, determining if the array describes a plain path or a compound-path with multiple sub-paths. * Parameters: * `segments:` Array of `Number[]` objects\[] — the segments array to parse * Returns: * `Path`⟋`CompoundPath` — the newly created path item * `PathItem.create(object)` Creates a path item from the given object, determining if the contained information describes a plain path or a compound-path with multiple sub-paths. * Parameters: * `object:` `Object` — an object containing the properties describing the item to be created * Returns: * `Path`⟋`CompoundPath` — the newly created path item ## Properties inherited from `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # Path Extends [**`Item`**](/project-and-items/item), [**`PathItem`**](/paths/pathitem) The path item represents a path in a Paper.js project. ## Constructors * `Path([segments])` Creates a new path item and places it at the top of the active layer. * Parameters: * `segments:` Array of `Segment` objects — An array of segments (or points to be converted to segments) that will be added to the path — optional * Returns: * `Path` — the newly created path 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'; ``` * `Path(object)` Creates a new 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: * `Path` — the newly created path Example: ``` var path = new Path({ segments: [[20, 20], [80, 80], [140, 20]], fillColor: 'black', closed: true }); ``` Example: ``` var path = new Path({ segments: [[20, 20], [80, 80], [140, 20]], strokeColor: 'red', strokeWidth: 20, strokeCap: 'round', selected: true }); ``` * `Path(pathData)` Creates a new 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: * `Path` — the newly created path Example: ``` var pathData = 'M100,50c0,27.614-22.386,50-50,50S0,77.614,0,50S22.386,0,50,0S100,22.386,100,50'; var path = new Path(pathData); path.fillColor = 'red'; ``` ### Shaped Paths * `Path.Line(from, to)` Creates a linear path item from two points describing a line. * Parameters: * `from:` `Point` — the line’s starting point * `to:` `Point` — the line’s ending point * Returns: * `Path` — the newly created path Example: ``` var from = new Point(20, 20); var to = new Point(80, 80); var path = new Path.Line(from, to); path.strokeColor = 'black'; ``` * `Path.Line(object)` Creates a linear path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Line({ from: [20, 20], to: [80, 80], strokeColor: 'black' }); ``` * `Path.Circle(center, radius)` Creates a circular path item. * Parameters: * `center:` `Point` — the center point of the circle * `radius:` `Number` — the radius of the circle * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Circle(new Point(80, 50), 30); path.strokeColor = 'black'; ``` * `Path.Circle(object)` Creates a circular path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, strokeColor: 'black' }); ``` * `Path.Rectangle(rectangle[, radius])` Creates a rectangular path item, with optionally rounded corners. * Parameters: * `rectangle:` `Rectangle` — the rectangle object describing the geometry of the rectangular path to be created * `radius:` `Size` — the size of the rounded corners — optional, default: `null` * Returns: * `Path` — the newly created path Example: ```jsx var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60)); var path = new Path.Rectangle(rectangle); path.strokeColor = 'black'; ``` Example:The same, with rounder corners ```jsx var rectangle = new Rectangle(new Point(20, 20), new Size(60, 60)); var cornerSize = new Size(10, 10); var path = new Path.Rectangle(rectangle, cornerSize); path.strokeColor = 'black'; ``` * `Path.Rectangle(point, size)` Creates a rectangular path item from a point and a size object. * Parameters: * `point:` `Point` — the rectangle’s top-left corner. * `size:` `Size` — the rectangle’s size. * Returns: * `Path` — the newly created path Example: ``` var point = new Point(20, 20); var size = new Size(60, 60); var path = new Path.Rectangle(point, size); path.strokeColor = 'black'; ``` * `Path.Rectangle(from, to)` 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. * Parameters: * `from:` `Point` — the first point defining the rectangle * `to:` `Point` — the second point defining the rectangle * Returns: * `Path` — the newly created path Example: ``` var from = new Point(20, 20); var to = new Point(80, 80); var path = new Path.Rectangle(from, to); path.strokeColor = 'black'; ``` * `Path.Rectangle(object)` Creates a rectangular path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Rectangle({ point: [20, 20], size: [60, 60], strokeColor: 'black' }); ``` Example: ``` var path = new Path.Rectangle({ from: [20, 20], to: [80, 80], strokeColor: 'black' }); ``` Example: ``` var path = new Path.Rectangle({ rectangle: { topLeft: [20, 20], bottomRight: [80, 80] }, strokeColor: 'black' }); ``` Example: ``` var path = new Path.Rectangle({ topLeft: [20, 20], bottomRight: [80, 80], radius: 10, strokeColor: 'black' }); ``` * `Path.Ellipse(rectangle)` Creates an elliptical path item. * Parameters: * `rectangle:` `Rectangle` — the rectangle circumscribing the ellipse * Returns: * `Path` — the newly created path Example: ``` var rectangle = new Rectangle(new Point(20, 20), new Size(180, 60)); var path = new Path.Ellipse(rectangle); path.fillColor = 'black'; ``` * `Path.Ellipse(object)` Creates an elliptical path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Ellipse({ point: [20, 20], size: [180, 60], fillColor: 'black' }); ``` Example:Placing by center and radius ``` var shape = new Path.Ellipse({ center: [110, 50], radius: [90, 30], fillColor: 'black' }); ``` * `Path.Arc(from, through, to)` Creates a circular arc path item. * Parameters: * `from:` `Point` — the starting point of the circular arc * `through:` `Point` — the point the arc passes through * `to:` `Point` — the end point of the arc * Returns: * `Path` — the newly created path Example: ```jsx var from = new Point(20, 20); var through = new Point(60, 20); var to = new Point(80, 80); var path = new Path.Arc(from, through, to); path.strokeColor = 'black'; ``` * `Path.Arc(object)` Creates an circular arc path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Arc({ from: [20, 20], through: [60, 20], to: [80, 80], strokeColor: 'black' }); ``` * `Path.RegularPolygon(center, sides, radius)` Creates a regular polygon shaped path item. * Parameters: * `center:` `Point` — the center point of the polygon * `sides:` `Number` — the number of sides of the polygon * `radius:` `Number` — the radius of the polygon * Returns: * `Path` — the newly created path Example: ```jsx var center = new Point(50, 50); var sides = 3; var radius = 40; var triangle = new Path.RegularPolygon(center, sides, radius); triangle.fillColor = 'black'; ``` * `Path.RegularPolygon(object)` Creates a regular polygon shaped path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var triangle = new Path.RegularPolygon({ center: [50, 50], sides: 10, radius: 40, fillColor: 'black' }); ``` * `Path.Star(center, points, radius1, radius2)` 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. * Parameters: * `center:` `Point` — the center point of the star * `points:` `Number` — the number of points of the star * `radius1:` `Number` * `radius2:` `Number` * Returns: * `Path` — the newly created path Example: ```jsx var center = new Point(50, 50); var points = 12; var radius1 = 25; var radius2 = 40; var path = new Path.Star(center, points, radius1, radius2); path.fillColor = 'black'; ``` * `Path.Star(object)` Creates a star shaped path item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `Path` — the newly created path Example: ``` var path = new Path.Star({ center: [50, 50], points: 12, radius1: 25, radius2: 40, fillColor: 'black' }); ``` ## Properties * `segments` The segments contained within the path. * Type: * Array of `Segment` objects * `firstSegment` The first Segment contained within the path. Read only. * Type: * `Segment` * `lastSegment` The last Segment contained within the path. Read only. * Type: * `Segment` * `curves` The curves contained within the path. Read only. * Type: * Array of `Curve` objects * `firstCurve` The first Curve contained within the path. Read only. * Type: * `Curve` * `lastCurve` The last Curve contained within the path. Read only. * Type: * `Curve` * `closed` Specifies whether the path is closed. If it is closed, Paper.js connects the first and last segments. * Type: * `Boolean` Example: ``` var myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(new Point(50, 75)); myPath.add(new Point(100, 25)); myPath.add(new Point(150, 75)); // Close the path: myPath.closed = true; ``` * `length` The approximate length of the path. Read only. * Type: * `Number` * `area` The area that the path’s geometry is covering. Self-intersecting paths can contain sub-areas that cancel each other out. Read only. * Type: * `Number` * `fullySelected` Specifies whether the path and all its segments are selected. Cannot be `true` on an empty path. * Type: * `Boolean` Example:A path is fully selected, if all of its segments are selected: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.fullySelected = true; var path2 = new Path.Circle({ center: [180, 50], radius: 35 }); // Deselect the second segment of the second path: path2.segments[1].selected = false; // If the path is fully selected (which it is), // set its fill color to red: if (path.fullySelected) { path.fillColor = 'red'; } // If the second path is fully selected (which it isn't, since we just // deselected its second segment), // set its fill color to red: if (path2.fullySelected) { path2.fillColor = 'red'; } ``` ## Methods * `add(...segment)` Adds one or more segments to the end of the `segments` array of this path. * Parameters: * `segment:` `Segment`⟋`Point`⟋Array of `Numbers` — the segment or point to be added. * Returns: * `Segment`⟋Array of `Segment` objects — the added segment(s). This is not necessarily the same object, e.g. if the segment to be added already belongs to another path. Example:Adding segments to a path using point objects: ``` var path = new Path({ strokeColor: 'black' }); // Add a segment at {x: 30, y: 75} path.add(new Point(30, 75)); // Add two segments in one go at {x: 100, y: 20} // and {x: 170, y: 75}: path.add(new Point(100, 20), new Point(170, 75)); ``` Example:Adding segments to a path using arrays containing number pairs: ``` var path = new Path({ strokeColor: 'black' }); // Add a segment at {x: 30, y: 75} path.add([30, 75]); // Add two segments in one go at {x: 100, y: 20} // and {x: 170, y: 75}: path.add([100, 20], [170, 75]); ``` Example:Adding segments to a path using objects: ``` var path = new Path({ strokeColor: 'black' }); // Add a segment at {x: 30, y: 75} path.add({x: 30, y: 75}); // Add two segments in one go at {x: 100, y: 20} // and {x: 170, y: 75}: path.add({x: 100, y: 20}, {x: 170, y: 75}); ``` Example:Adding a segment with handles to a path: ``` var path = new Path({ strokeColor: 'black' }); path.add(new Point(30, 75)); // Add a segment with handles: var point = new Point(100, 20); var handleIn = new Point(-50, 0); var handleOut = new Point(50, 0); var added = path.add(new Segment(point, handleIn, handleOut)); // Select the added segment, so we can see its handles: added.selected = true; path.add(new Point(170, 75)); ``` * `insert(index, segment)` Inserts one or more segments at a given index in the list of this path’s segments. * Parameters: * `index:` `Number` — the index at which to insert the segment * `segment:` `Segment`⟋`Point` — the segment or point to be inserted. * Returns: * `Segment` — the added segment. This is not necessarily the same object, e.g. if the segment to be added already belongs to another path Example:Inserting a segment: ``` var myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(new Point(50, 75)); myPath.add(new Point(150, 75)); // Insert a new segment into myPath at index 1: myPath.insert(1, new Point(100, 25)); // Select the segment which we just inserted: myPath.segments[1].selected = true; ``` Example:Inserting multiple segments: ``` var myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(new Point(50, 75)); myPath.add(new Point(150, 75)); // Insert two segments into myPath at index 1: myPath.insert(1, [80, 25], [120, 25]); // Select the segments which we just inserted: myPath.segments[1].selected = true; myPath.segments[2].selected = true; ``` * `addSegments(segments)` Adds an array of segments (or types that can be converted to segments) to the end of the `segments` array. * Parameters: * `segments:` Array of `Segment` objects * Returns: * `Array of Segment` objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path Example:Adding an array of Point objects: ``` var path = new Path({ strokeColor: 'black' }); var points = [new Point(30, 50), new Point(170, 50)]; path.addSegments(points); ``` Example:Adding an array of \[x, y] arrays: ``` var path = new Path({ strokeColor: 'black' }); var array = [[30, 75], [100, 20], [170, 75]]; path.addSegments(array); ``` Example:Adding segments from one path to another: ``` var path = new Path({ strokeColor: 'black' }); path.addSegments([[30, 75], [100, 20], [170, 75]]); var path2 = new Path(); path2.strokeColor = 'red'; // Add the second and third segments of path to path2: path2.add(path.segments[1], path.segments[2]); // Move path2 30pt to the right: path2.position.x += 30; ``` * `insertSegments(index, segments)` Inserts an array of segments at a given index in the path’s `segments` array. * Parameters: * `index:` `Number` — the index at which to insert the segments * `segments:` Array of `Segment` objects — the segments to be inserted * Returns: * `Array of Segment` objects — an array of the added segments. These segments are not necessarily the same objects, e.g. if the segment to be added already belongs to another path * `removeSegment(index)` Removes the segment at the specified index of the path’s `segments` array. * Parameters: * `index:` `Number` — the index of the segment to be removed * Returns: * `Segment` — the removed segment Example:Removing a segment from a path: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var path = new Path.Circle({ center: new Point(80, 50), radius: 35, strokeColor: 'black' }); // Remove its second segment: path.removeSegment(1); // Select the path, so we can see its segments: path.selected = true; ``` * `removeSegments()` Removes all segments from the path’s `segments` array. * Returns: * `Array of Segment` objects — an array containing the removed segments * `removeSegments(from[, to])` Removes the segments from the specified `from` index to the `to` index from the path’s `segments` array. * Parameters: * `from:` `Number` — the beginning index, inclusive * `to:` `Number` — the ending index, exclusive — optional, default: `segments.length` * Returns: * `Array of Segment` objects — an array containing the removed segments Example:Removing segments from a path: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var path = new Path.Circle({ center: new Point(80, 50), radius: 35, strokeColor: 'black' }); // Remove the segments from index 1 till index 2: path.removeSegments(1, 2); // Select the path, so we can see its segments: path.selected = true; ``` * `hasHandles()` Checks if any of the curves in the path have curve handles set. * Returns: * `Boolean` — `true` if the path has curve handles set, `false` otherwise * See also: * `segment.hasHandles()` * `curve.hasHandles()` * `clearHandles()` 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). * `divideAt(location)` Divides the path on the curve at the given offset or location into two curves, by inserting a new segment at the given location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the path at which to divide the existing curve by inserting a new segment * Returns: * `Segment` — the newly inserted segment if the location is valid, `null` otherwise * See also: * `curve.divideAt(location)` * `splitAt(location)` Splits the path at the given offset or location. After splitting, the path will be open. If the path was open already, splitting will result in two paths. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location at which to split the path * Returns: * `Path` — the newly created path after splitting, if any Example: ```jsx var path = new Path.Circle({ center: view.center, radius: 40, strokeColor: 'black' }); var pointOnCircle = view.center + { length: 40, angle: 30 }; var location = path.getNearestLocation(pointOnCircle); path.splitAt(location); path.lastSegment.selected = true; ``` Example:Splitting an open path Draw a V shaped path: ``` var path = new Path([20, 20], [50, 80], [80, 20]); path.strokeColor = 'black'; // Split the path half-way: var path2 = path.splitAt(path.length / 2); // Give the resulting path a red stroke-color // and move it 20px to the right: path2.strokeColor = 'red'; path2.position.x += 20; ``` Example:Splitting a closed path ``` var path = new Path.Rectangle({ from: [20, 20], to: [80, 80], strokeColor: 'black' }); // Split the path half-way: path.splitAt(path.length / 2); // Move the first segment, to show where the path // was split: path.firstSegment.point.x += 20; // Select the first segment: path.firstSegment.selected = true; ``` * `join(path[, tolerance])` Joins the path with the other specified path, which will be removed in the process. They can be joined if the first or last segments of either path lie in the same location. Locations are optionally compare with a provide `tolerance` value. If `null` or `this` is passed as the other path, the path will be joined with itself if the first and last segment are in the same location. * Parameters: * `path:` `Path` — the path to join this path with; `null` or `this` to join the path with itself * `tolerance:` `Number` — the tolerance with which to decide if two segments are to be considered the same location when joining — optional, default: `0` Example:Joining two paths: ``` var path = new Path({ segments: [[30, 25], [30, 75]], strokeColor: 'black' }); var path2 = new Path({ segments: [[200, 25], [200, 75]], strokeColor: 'black' }); // Join the paths: path.join(path2); ``` Example:Joining two paths that share a point at the start or end of their segments array: ``` var path = new Path({ segments: [[30, 25], [30, 75]], strokeColor: 'black' }); var path2 = new Path({ segments: [[30, 25], [80, 25]], strokeColor: 'black' }); // Join the paths: path.join(path2); // After joining, path with have 3 segments, since it // shared its first segment point with the first // segment point of path2. // Select the path to show that they have joined: path.selected = true; ``` Example:Joining two paths that connect at two points: ``` var path = new Path({ segments: [[30, 25], [80, 25], [80, 75]], strokeColor: 'black' }); var path2 = new Path({ segments: [[30, 25], [30, 75], [80, 75]], strokeColor: 'black' }); // Join the paths: path.join(path2); // Because the paths were joined at two points, the path is closed // and has 4 segments. // Select the path to show that they have joined: path.selected = true; ``` * `reduce(options)` Reduces the path by removing curves that have a length of 0, and unnecessary segments between two collinear flat curves. * Parameters: * `options:` * Returns: * `Path` — the reduced path * `toShape([insert])` Attempts to create a new shape item with same geometry as this path item, and inherits all settings from it, similar to `item.clone`(). * Parameters: * `insert:` `Boolean` — specifies whether the new shape should be inserted into the scene graph. When set to `true`, it is inserted above the path item — optional, default: `true` * Returns: * `Shape` — the newly created shape item with the same geometry as this path item if it can be matched, `null` otherwise * See also: * `shape.toPath(insert)` ### Positions on Paths and Curves * `getLocationOf(point)` Returns the curve location of the specified point if it lies on the path, `null` otherwise. * Parameters: * `point:` `Point` — the point on the path * Returns: * `CurveLocation` — the curve location of the specified point * `getOffsetOf(point)` Returns the length of the path from its beginning up to up to the specified point if it lies on the path, `null` otherwise. * Parameters: * `point:` `Point` — the point on the path * Returns: * `Number` — the length of the path up to the specified point * `getLocationAt(offset)` Returns the curve location of the specified offset on the path. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `CurveLocation` — the curve location at the specified offset * `getPointAt(offset)` Calculates the point on the path at the given offset. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Point` — the point at the given offset Example:Finding the point on a path at a given offset: ```jsx // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); // We're going to be working with a third of the length // of the path as the offset: var offset = path.length / 3; // Find the point on the path: var point = path.getPointAt(offset); // Create a small circle shaped path at the point: var circle = new Path.Circle({ center: point, radius: 3, fillColor: 'red' }); ``` Example:Iterating over the length of a path: ```jsx // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); var amount = 5; var length = path.length; for (var i = 0; i < amount + 1; i++) { var offset = i / amount * length; // Find the point on the path at the given offset: var point = path.getPointAt(offset); // Create a small circle shaped path at the point: var circle = new Path.Circle({ center: point, radius: 3, fillColor: 'red' }); } ``` * `getTangentAt(offset)` Calculates the normalized tangent vector of the path at the given offset. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Point` — the normalized tangent vector at the given offset Example:Working with the tangent vector at a given offset: ``` // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); // We're going to be working with a third of the length // of the path as the offset: var offset = path.length / 3; // Find the point on the path: var point = path.getPointAt(offset); // Find the tangent vector at the given offset // and give it a length of 60: var tangent = path.getTangentAt(offset) * 60; var line = new Path({ segments: [point, point + tangent], strokeColor: 'red' }) ``` Example:Iterating over the length of a path: ``` // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); var amount = 6; var length = path.length; for (var i = 0; i < amount + 1; i++) { var offset = i / amount * length; // Find the point on the path at the given offset: var point = path.getPointAt(offset); // Find the tangent vector on the path at the given offset // and give it a length of 60: var tangent = path.getTangentAt(offset) * 60; var line = new Path({ segments: [point, point + tangent], strokeColor: 'red' }) } ``` * `getNormalAt(offset)` Calculates the normal vector of the path at the given offset. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Point` — the normal vector at the given offset Example:Working with the normal vector at a given offset: ``` // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); // We're going to be working with a third of the length // of the path as the offset: var offset = path.length / 3; // Find the point on the path: var point = path.getPointAt(offset); // Find the normal vector on the path at the given offset // and give it a length of 30: var normal = path.getNormalAt(offset) * 30; var line = new Path({ segments: [point, point + normal], strokeColor: 'red' }); ``` Example:Iterating over the length of a path: ``` // Create an arc shaped path: var path = new Path({ strokeColor: 'black' }); path.add(new Point(40, 100)); path.arcTo(new Point(150, 100)); var amount = 10; var length = path.length; for (var i = 0; i < amount + 1; i++) { var offset = i / amount * length; // Find the point on the path at the given offset: var point = path.getPointAt(offset); // Find the normal vector on the path at the given offset // and give it a length of 30: var normal = path.getNormalAt(offset) * 30; var line = new Path({ segments: [point, point + normal], strokeColor: 'red' }); } ``` * `getWeightedTangentAt(offset)` Calculates the weighted tangent vector of the path at the given offset. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Point` — the weighted tangent vector at the given offset * `getWeightedNormalAt(offset)` Calculates the weighted normal vector of the path at the given offset. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Point` — the weighted normal vector at the given offset * `getCurvatureAt(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. * Parameters: * `offset:` `Number` — the offset on the path, where `0` is at the beginning of the path and `path.length` at the end * Returns: * `Number` — the normal vector at the given offset * `getOffsetsWithTangent(tangent)` Calculates path offsets where the path is tangential to the provided tangent. Note that tangents at the start or end are included. Tangents at segment points are returned even if only one of their handles is collinear with the provided tangent. * Parameters: * `tangent:` `Point` — the tangent to which the path must be tangential * Returns: * `Array of Numbers` — path offsets where the path is tangential to the provided tangent ## Properties inherited from `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` ## Properties inherited from `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` ### 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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 subtract * `options:` `Object` — the boolean operation options — optional * Returns: * `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 of * `options:` `Object` — the boolean operation options — optional * Returns: * `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)` and `intersect(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 by * `options:` `Object` — the boolean operation options — optional * Returns: * `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 by `clockwise`, otherwise the orientation of the largest root child is used. — optional * Returns: * `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 of `CurveLocation` objects. `CompoundPath` items are also supported. * Parameters: * `path:` `PathItem` — the other item to find the intersections with * `include:` `Function` — a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall return `true` to include a location, `false` otherwise. — optional * Returns: * `Array of CurveLocation` objects — the locations of all intersection between the paths * See also: * `getCrossings(path)` Example:Finding the intersections between two paths ```jsx var path = new Path.Rectangle(new Point(30, 25), new Size(50, 50)); path.strokeColor = 'black'; var secondPath = path.clone(); var intersectionGroup = new Group(); function onFrame(event) { secondPath.rotate(1); var intersections = path.getIntersections(secondPath); intersectionGroup.removeChildren(); for (var i = 0; i < intersections.length; i++) { var intersectionPath = new Path.Circle({ center: intersections[i].point, radius: 4, fillColor: 'red', parent: intersectionGroup }); } } ``` * `getCrossings(path)` 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. * Parameters: * `path:` `PathItem` — the other item to find the crossings with * Returns: * `Array of CurveLocation` objects — the locations of all crossings between the paths * See 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 location * Returns: * `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 point * Returns: * `Point` — the point on the path that’s the closest to the specified point Example: ```jsx var star = new Path.Star({ center: view.center, points: 10, radius1: 30, radius2: 60, strokeColor: 'black' }); var circle = new Path.Circle({ center: view.center, radius: 3, fillColor: 'red' }); function onMouseMove(event) { // Get the nearest point from the mouse position // to the star shaped path: var nearestPoint = star.getNearestPoint(event.point); // Move the red circle to the nearest point: circle.position = nearestPoint; } ``` ### Path Manipulation * `reverse()` Reverses the orientation of the path item. When called on `CompoundPath` items, each of the nested paths is reversed. On `Path` items, the sequence of `path.segments` is reversed. * `flatten([flatness])` Flattens the curves in path items to a sequence of straight lines, by subdividing them enough times until the specified maximum error is met. * Parameters: * `flatness:` `Number` — the maximum error between the flattened lines and the original curves — optional, default: `0.25` Example:Flattening a circle shaped path: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Select the path, so we can inspect its segments: path.selected = true; // Create a copy of the path and move it by 150 points: var copy = path.clone(); copy.position.x += 150; // Flatten the copied path, with a maximum error of 4 points: copy.flatten(4); ``` * `smooth([options])` 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. 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 `options.from` and `options.to` 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. Four different smoothing methods are available: * `'continuous'` 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. This method tends to result in the smoothest results, but does not allow for further parametrization of the handles. * `'asymmetric'` is based on the same principle as `'continuous'` 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. * `'catmull-rom'` uses the Catmull-Rom spline to smooth the segment. The optionally passed factor controls the knot parametrization of the algorithm: * `0.0`: the standard, uniform Catmull-Rom spline * `0.5`: the centripetal Catmull-Rom spline, guaranteeing no self-intersections * `1.0`: the chordal Catmull-Rom spline * `'geometric'` 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. The optionally passed factor defines the tension parameter (`0…1`), controlling the amount of smoothing as a factor by which to scale each handle. * Options: * `options.type: String` — the type of smoothing method: `‘continuous’`, `‘asymmetric’`, `‘catmull-rom’`, `‘geometric’` — default: `‘asymmetric’` * `options.factor: Number` — the factor parameterizing the smoothing method — default: `0.5` for `'catmull-rom'`, `0.4` for `'geometric'` * `options.from: Number`⟋`Segment`⟋`Curve` — 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. * `options.to: Number`⟋`Segment`⟋`Curve` — 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. * Parameters: * `options:` `Object` — the smoothing options — optional * See also: * `segment.smooth([options])` Example:Smoothing a closed shape: ```jsx // Create a rectangular path with its top-left point at // {x: 30, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle({ point: [30, 25], size: [50, 50], strokeColor: 'black', }); // Select the path, so we can see its handles: path.fullySelected = true; // Create a copy of the path and move it 100 to the right: var copy = path.clone(); copy.position.x += 100; // Smooth the segments of the copy: copy.smooth({ type: 'continuous' }); ``` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 50)); var y = 5; var x = 3; for (var i = 0; i < 28; i++) { y *= -1.1; x *= 1.1; path.lineBy(x, y); } // Create a copy of the path and move it 100 down: var copy = path.clone(); copy.position.y += 120; // Select the path, so we can see its handles: copy.fullySelected = true; // Smooth the path using centripetal Catmull-Rom splines: copy.smooth({ type: 'catmull-rom', factor: 0.5 }); ``` Example:Smoothing ranges of paths, using segments, curves or indices: ```jsx // Create 5 rectangles, next to each other: var paths = []; for (var i = 0; i < 5; i++) { paths.push(new Path.Rectangle({ point: [30 + i * 100, 30], size: [50, 50], fullySelected: true })); } // Smooth a range, using segments: paths[1].smooth({ type: 'continuous', from: paths[1].segments[0], to: paths[1].segments[2] }); // Smooth a range, using curves: paths[2].smooth({ type: 'continuous', from: paths[2].curves[0], to: paths[2].curves[1] }); // Smooth a range, using indices: paths[3].smooth({ type: 'continuous', from: 0, to: 2 }); // Smooth a range, using negative indices: paths[4].smooth({ type: 'continuous', from: -1, to: 1 }); ``` * `simplify([tolerance])` 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 `CompoundPath` items, each of the nested paths is simplified. On `Path` items, the `path.segments` array is processed and replaced by the resulting sequence of fitted curves. This method can be used to process and simplify the point data received from a mouse or touch device. * Parameters: * `tolerance:` `Number` — the allowed maximum error when fitting the curves through the segment points — optional, default: `2.5` * Returns: * `Boolean` — `true` if the method was capable of fitting curves through the path’s segment points, `false` otherwise Example:Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify(): ```jsx var path; function onMouseDown(event) { // If we already made a path before, deselect it: if (path) { path.selected = false; } // Create a new path and add the position of the mouse // as its first segment. Select it, so we can see the // segment points: path = new Path({ segments: [event.point], strokeColor: 'black', selected: true }); } function onMouseDrag(event) { // On every drag event, add a segment to the path // at the position of the mouse: path.add(event.point); } function onMouseUp(event) { // When the mouse is released, simplify the path: path.simplify(); path.selected = true; } ``` * `interpolate(from, to, factor)` 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. * Parameters: * `from:` `PathItem` — the path item defining the geometry when `factor` is `0` * `to:` `PathItem` — the path item defining the geometry when `factor` is `1` * `factor:` `Number` — the interpolation coefficient, typically between `0` and `1`, but extrapolation is possible too * `compare(path)` Compares the geometry of two paths to see if they describe the same shape, detecting cases where paths start in different segments or even use different amounts of curves to describe the same shape, as long as their orientation is the same, and their segments and handles really result in the same visual appearance of curves. * Parameters: * `path:` `PathItem` — the path to compare this path’s geometry with * Returns: * `Boolean` — `true` if two paths describe the same shape, `false` otherwise ### Postscript Style Drawing Commands * `moveTo(point)` 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. * Parameters: * `point:` `Point` — the point in which to start the path * `lineTo(point)` Adds a straight curve to the path, from the the last segment in the path to the specified point. * Parameters: * `point:` `Point` — the destination point of the newly added straight curve * `arcTo(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` point, to the specified `to` point, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the point where the arc should pass through * `to:` `Point` — the point where the arc should end Example: ```jsx var path = new Path(); path.strokeColor = 'black'; var firstPoint = new Point(30, 75); path.add(firstPoint); // The point through which we will create the arc: var throughPoint = new Point(40, 40); // The point at which the arc will end: var toPoint = new Point(130, 75); // Draw an arc through 'throughPoint' to 'toPoint' path.arcTo(throughPoint, toPoint); // Add a red circle shaped path at the position of 'throughPoint': var circle = new Path.Circle(throughPoint, 3); circle.fillColor = 'red'; ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; function onMouseDrag(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw an arc through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.arcTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } // When the mouse is released, deselect the path // and fill it with black. function onMouseUp(event) { myPath.selected = false; myPath.fillColor = 'black'; } ``` * `arcTo(to[, clockwise])` Adds an arc from the position of the last segment in the path to the specified point, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the point where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 75)); path.arcTo(new Point(130, 75)); var path2 = new Path(); path2.strokeColor = 'red'; path2.add(new Point(180, 25)); // To draw an arc in anticlockwise direction, // we pass `false` as the second argument to arcTo: path2.arcTo(new Point(280, 25), false); ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; // The mouse has to move at least 20 points before // the next mouse drag event is fired: tool.minDistance = 20; // When the user clicks, create a new path and add // the current mouse position to it as its first segment: function onMouseDown(event) { myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(event.point); } // On each mouse drag event, draw an arc to the current // position of the mouse: function onMouseDrag(event) { myPath.arcTo(event.point); } ``` * `curveTo(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` point, to the specified destination point by adding one segment to the path. * Parameters: * `through:` `Point` — the point through which the curve should pass * `to:` `Point` — the destination point of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` Example:Interactive example. Move your mouse around the view below: ```jsx var myPath; function onMouseMove(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw a curve through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.curveTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } ``` * `cubicCurveTo(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleOut` of its first segment are calculated * `handle2:` `Point` — the location of the second handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveTo(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the location of the handle of the newly added quadratic curve in absolute coordinates, out of which the relative values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `closePath()` Closes the path. When closed, Paper.js connects the first and last segment of the path with an additional curve. The difference to setting `path.closed` to `true` is that this will also merge the first segment with the last if they lie in the same location. * See also: * `path.closed` ### Relative Drawing Commands * `moveBy(to)` 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. * Parameters: * `to:` `Point` * `lineBy(point)` Adds a straight curve to the path, from the the last segment in the path to the `to` vector specified relatively to it. * Parameters: * `point:` `Point` — the vector describing the destination of the newly added straight curve Example: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add a segment at {x: 50, y: 50} path.add(25, 25); // Add a segment relative to the last segment of the path. // 50 in x direction and 0 in y direction, becomes {x: 75, y: 25} path.lineBy(50, 0); // 0 in x direction and 50 in y direction, becomes {x: 75, y: 75} path.lineBy(0, 50); ``` Example:Drawing a spiral using lineBy: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add the first segment at {x: 50, y: 50} path.add(view.center); // Loop 500 times: for (var i = 0; i < 500; i++) { // Create a vector with an ever increasing length // and an angle in increments of 45 degrees var vector = new Point({ angle: i * 45, length: i / 2 }); // Add the vector relatively to the last segment point: path.lineBy(vector); } // Smooth the handles of the path: path.smooth(); // Uncomment the following line and click on 'run' to see // the construction of the path: // path.selected = true; ``` * `arcBy(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the vector where the arc should pass through * `to:` `Point` — the vector where the arc should end * `arcBy(to[, clockwise])` Adds an arc from the position of the last segment in the path to the `to` vector specified relatively to it, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the vector where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` * `curveBy(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one segment to the path. * Parameters: * `through:` `Point` — the vector through which the curve should pass * `to:` `Point` — the destination vector of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` * `cubicCurveBy(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the to the specified `to` vector, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve * `handle2:` `Point` — the location of the second handle of the newly added curve * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveBy(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the handle of the newly added quadratic curve out of which the values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve # CompoundPath Extends [**`Item`**](/project-and-items/item), [**`PathItem`**](/paths/pathitem) 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: ``` var path = new CompoundPath({ children: [ new Path.Circle({ center: new Point(50, 50), radius: 30 }), new Path.Circle({ center: new Point(50, 50), radius: 10 }) ], fillColor: 'black', selected: true }); ``` * `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: ``` var pathData = 'M20,50c0,-16.56854 13.43146,-30 30,-30c16.56854,0 30,13.43146 30,30c0,16.56854 -13.43146,30 -30,30c-16.56854,0 -30,-13.43146 -30,-30z M50,60c5.52285,0 10,-4.47715 10,-10c0,-5.52285 -4.47715,-10 -10,-10c-5.52285,0 -10,4.47715 -10,10c0,5.52285 4.47715,10 10,10z'; var path = new CompoundPath(pathData); path.fillColor = 'black'; ``` ## 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` on `item.firstChild`. Read only. * Type: * `Segment` * `lastSegment` The last Segment contained within the compound-path, a short-cut to calling `path.lastSegment` on `item.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` on `item.firstChild`. Read only. * Type: * `Curve` * `lastCurve` The last Curve contained within the compound-path, a short-cut to calling `path.lastCurve` on `item.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` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ```jsx var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ```jsx var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ```jsx var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ```jsx // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ```jsx var path = new Path(); path.data.remember = 'milk'; ``` Example: ```jsx var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20 ``` Example: ```jsx var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1 ``` Example: ```jsx var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ```jsx // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ```jsx // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ```jsx 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 ```jsx var path = new Path(); // New items are placed in the active layer: console.log(path.parent == project.activeLayer); // true var group = new Group(); path.parent = group; // 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 ```jsx 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ```jsx 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ```jsx // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ```jsx // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ```jsx // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ```jsx // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ```jsx // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ```jsx // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ```jsx 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ```jsx // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ```jsx var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `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 for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ```jsx var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ```jsx // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ```jsx // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ```jsx // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ```jsx // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ```jsx var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ```jsx // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ```jsx // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ```jsx 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ```jsx 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ```jsx function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ```jsx 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ```jsx function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` ## Properties inherited from `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` ### 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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 with * `options:` `Object` — the boolean operation options — optional * Returns: * `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 subtract * `options:` `Object` — the boolean operation options — optional * Returns: * `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 of * `options:` `Object` — the boolean operation options — optional * Returns: * `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)` and `intersect(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 by * `options:` `Object` — the boolean operation options — optional * Returns: * `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 by `clockwise`, otherwise the orientation of the largest root child is used. — optional * Returns: * `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 of `CurveLocation` objects. `CompoundPath` items are also supported. * Parameters: * `path:` `PathItem` — the other item to find the intersections with * `include:` `Function` — a callback function that can be used to filter out undesired locations right while they are collected. When defined, it shall return `true` to include a location, `false` otherwise. — optional * Returns: * `Array of CurveLocation` objects — the locations of all intersection between the paths * See also: * `getCrossings(path)` Example:Finding the intersections between two paths ```jsx var path = new Path.Rectangle(new Point(30, 25), new Size(50, 50)); path.strokeColor = 'black'; var secondPath = path.clone(); var intersectionGroup = new Group(); function onFrame(event) { secondPath.rotate(1); var intersections = path.getIntersections(secondPath); intersectionGroup.removeChildren(); for (var i = 0; i < intersections.length; i++) { var intersectionPath = new Path.Circle({ center: intersections[i].point, radius: 4, fillColor: 'red', parent: intersectionGroup }); } } ``` * `getCrossings(path)` 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. * Parameters: * `path:` `PathItem` — the other item to find the crossings with * Returns: * `Array of CurveLocation` objects — the locations of all crossings between the paths * See 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 location * Returns: * `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 point * Returns: * `Point` — the point on the path that’s the closest to the specified point Example: ```jsx var star = new Path.Star({ center: view.center, points: 10, radius1: 30, radius2: 60, strokeColor: 'black' }); var circle = new Path.Circle({ center: view.center, radius: 3, fillColor: 'red' }); function onMouseMove(event) { // Get the nearest point from the mouse position // to the star shaped path: var nearestPoint = star.getNearestPoint(event.point); // Move the red circle to the nearest point: circle.position = nearestPoint; } ``` ### Path Manipulation * `reverse()` Reverses the orientation of the path item. When called on `CompoundPath` items, each of the nested paths is reversed. On `Path` items, the sequence of `path.segments` is reversed. * `flatten([flatness])` Flattens the curves in path items to a sequence of straight lines, by subdividing them enough times until the specified maximum error is met. * Parameters: * `flatness:` `Number` — the maximum error between the flattened lines and the original curves — optional, default: `0.25` Example:Flattening a circle shaped path: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Select the path, so we can inspect its segments: path.selected = true; // Create a copy of the path and move it by 150 points: var copy = path.clone(); copy.position.x += 150; // Flatten the copied path, with a maximum error of 4 points: copy.flatten(4); ``` * `smooth([options])` 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. 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 `options.from` and `options.to` 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. Four different smoothing methods are available: * `'continuous'` 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. This method tends to result in the smoothest results, but does not allow for further parametrization of the handles. * `'asymmetric'` is based on the same principle as `'continuous'` 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. * `'catmull-rom'` uses the Catmull-Rom spline to smooth the segment. The optionally passed factor controls the knot parametrization of the algorithm: * `0.0`: the standard, uniform Catmull-Rom spline * `0.5`: the centripetal Catmull-Rom spline, guaranteeing no self-intersections * `1.0`: the chordal Catmull-Rom spline * `'geometric'` 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. The optionally passed factor defines the tension parameter (`0…1`), controlling the amount of smoothing as a factor by which to scale each handle. * Options: * `options.type: String` — the type of smoothing method: `‘continuous’`, `‘asymmetric’`, `‘catmull-rom’`, `‘geometric’` — default: `‘asymmetric’` * `options.factor: Number` — the factor parameterizing the smoothing method — default: `0.5` for `'catmull-rom'`, `0.4` for `'geometric'` * `options.from: Number`⟋`Segment`⟋`Curve` — 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. * `options.to: Number`⟋`Segment`⟋`Curve` — 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. * Parameters: * `options:` `Object` — the smoothing options — optional * See also: * `segment.smooth([options])` Example:Smoothing a closed shape: ```jsx // Create a rectangular path with its top-left point at // {x: 30, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle({ point: [30, 25], size: [50, 50], strokeColor: 'black', }); // Select the path, so we can see its handles: path.fullySelected = true; // Create a copy of the path and move it 100 to the right: var copy = path.clone(); copy.position.x += 100; // Smooth the segments of the copy: copy.smooth({ type: 'continuous' }); ``` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 50)); var y = 5; var x = 3; for (var i = 0; i < 28; i++) { y *= -1.1; x *= 1.1; path.lineBy(x, y); } // Create a copy of the path and move it 100 down: var copy = path.clone(); copy.position.y += 120; // Select the path, so we can see its handles: copy.fullySelected = true; // Smooth the path using centripetal Catmull-Rom splines: copy.smooth({ type: 'catmull-rom', factor: 0.5 }); ``` Example:Smoothing ranges of paths, using segments, curves or indices: ```jsx // Create 5 rectangles, next to each other: var paths = []; for (var i = 0; i < 5; i++) { paths.push(new Path.Rectangle({ point: [30 + i * 100, 30], size: [50, 50], fullySelected: true })); } // Smooth a range, using segments: paths[1].smooth({ type: 'continuous', from: paths[1].segments[0], to: paths[1].segments[2] }); // Smooth a range, using curves: paths[2].smooth({ type: 'continuous', from: paths[2].curves[0], to: paths[2].curves[1] }); // Smooth a range, using indices: paths[3].smooth({ type: 'continuous', from: 0, to: 2 }); // Smooth a range, using negative indices: paths[4].smooth({ type: 'continuous', from: -1, to: 1 }); ``` * `simplify([tolerance])` 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 `CompoundPath` items, each of the nested paths is simplified. On `Path` items, the `path.segments` array is processed and replaced by the resulting sequence of fitted curves. This method can be used to process and simplify the point data received from a mouse or touch device. * Parameters: * `tolerance:` `Number` — the allowed maximum error when fitting the curves through the segment points — optional, default: `2.5` * Returns: * `Boolean` — `true` if the method was capable of fitting curves through the path’s segment points, `false` otherwise Example:Click and drag below to draw to draw a line, when you release the mouse, the is made smooth using path.simplify(): ```jsx var path; function onMouseDown(event) { // If we already made a path before, deselect it: if (path) { path.selected = false; } // Create a new path and add the position of the mouse // as its first segment. Select it, so we can see the // segment points: path = new Path({ segments: [event.point], strokeColor: 'black', selected: true }); } function onMouseDrag(event) { // On every drag event, add a segment to the path // at the position of the mouse: path.add(event.point); } function onMouseUp(event) { // When the mouse is released, simplify the path: path.simplify(); path.selected = true; } ``` * `interpolate(from, to, factor)` 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. * Parameters: * `from:` `PathItem` — the path item defining the geometry when `factor` is `0` * `to:` `PathItem` — the path item defining the geometry when `factor` is `1` * `factor:` `Number` — the interpolation coefficient, typically between `0` and `1`, but extrapolation is possible too * `compare(path)` Compares the geometry of two paths to see if they describe the same shape, detecting cases where paths start in different segments or even use different amounts of curves to describe the same shape, as long as their orientation is the same, and their segments and handles really result in the same visual appearance of curves. * Parameters: * `path:` `PathItem` — the path to compare this path’s geometry with * Returns: * `Boolean` — `true` if two paths describe the same shape, `false` otherwise ### Postscript Style Drawing Commands * `moveTo(point)` 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. * Parameters: * `point:` `Point` — the point in which to start the path * `lineTo(point)` Adds a straight curve to the path, from the the last segment in the path to the specified point. * Parameters: * `point:` `Point` — the destination point of the newly added straight curve * `arcTo(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` point, to the specified `to` point, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the point where the arc should pass through * `to:` `Point` — the point where the arc should end Example: ```jsx var path = new Path(); path.strokeColor = 'black'; var firstPoint = new Point(30, 75); path.add(firstPoint); // The point through which we will create the arc: var throughPoint = new Point(40, 40); // The point at which the arc will end: var toPoint = new Point(130, 75); // Draw an arc through 'throughPoint' to 'toPoint' path.arcTo(throughPoint, toPoint); // Add a red circle shaped path at the position of 'throughPoint': var circle = new Path.Circle(throughPoint, 3); circle.fillColor = 'red'; ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; function onMouseDrag(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw an arc through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.arcTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } // When the mouse is released, deselect the path // and fill it with black. function onMouseUp(event) { myPath.selected = false; myPath.fillColor = 'black'; } ``` * `arcTo(to[, clockwise])` Adds an arc from the position of the last segment in the path to the specified point, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the point where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` Example: ```jsx var path = new Path(); path.strokeColor = 'black'; path.add(new Point(30, 75)); path.arcTo(new Point(130, 75)); var path2 = new Path(); path2.strokeColor = 'red'; path2.add(new Point(180, 25)); // To draw an arc in anticlockwise direction, // we pass `false` as the second argument to arcTo: path2.arcTo(new Point(280, 25), false); ``` Example:Interactive example. Click and drag in the view below: ```jsx var myPath; // The mouse has to move at least 20 points before // the next mouse drag event is fired: tool.minDistance = 20; // When the user clicks, create a new path and add // the current mouse position to it as its first segment: function onMouseDown(event) { myPath = new Path(); myPath.strokeColor = 'black'; myPath.add(event.point); } // On each mouse drag event, draw an arc to the current // position of the mouse: function onMouseDrag(event) { myPath.arcTo(event.point); } ``` * `curveTo(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` point, to the specified destination point by adding one segment to the path. * Parameters: * `through:` `Point` — the point through which the curve should pass * `to:` `Point` — the destination point of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` Example:Interactive example. Move your mouse around the view below: ```jsx var myPath; function onMouseMove(event) { // If we created a path before, remove it: if (myPath) { myPath.remove(); } // Create a new path and add a segment point to it // at {x: 150, y: 150): myPath = new Path(); myPath.add(150, 150); // Draw a curve through the position of the mouse to 'toPoint' var toPoint = new Point(350, 150); myPath.curveTo(event.point, toPoint); // Select the path, so we can see its segments: myPath.selected = true; } ``` * `cubicCurveTo(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleOut` of its first segment are calculated * `handle2:` `Point` — the location of the second handle of the newly added curve in absolute coordinates, out of which the relative values for `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveTo(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the location of the handle of the newly added quadratic curve in absolute coordinates, out of which the relative values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve * `closePath()` Closes the path. When closed, Paper.js connects the first and last segment of the path with an additional curve. The difference to setting `path.closed` to `true` is that this will also merge the first segment with the last if they lie in the same location. * See also: * `path.closed` ### Relative Drawing Commands * `moveBy(to)` 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. * Parameters: * `to:` `Point` * `lineBy(point)` Adds a straight curve to the path, from the the last segment in the path to the `to` vector specified relatively to it. * Parameters: * `point:` `Point` — the vector describing the destination of the newly added straight curve Example: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add a segment at {x: 50, y: 50} path.add(25, 25); // Add a segment relative to the last segment of the path. // 50 in x direction and 0 in y direction, becomes {x: 75, y: 25} path.lineBy(50, 0); // 0 in x direction and 50 in y direction, becomes {x: 75, y: 75} path.lineBy(0, 50); ``` Example:Drawing a spiral using lineBy: ```jsx var path = new Path(); path.strokeColor = 'black'; // Add the first segment at {x: 50, y: 50} path.add(view.center); // Loop 500 times: for (var i = 0; i < 500; i++) { // Create a vector with an ever increasing length // and an angle in increments of 45 degrees var vector = new Point({ angle: i * 45, length: i / 2 }); // Add the vector relatively to the last segment point: path.lineBy(vector); } // Smooth the handles of the path: path.smooth(); // Uncomment the following line and click on 'run' to see // the construction of the path: // path.selected = true; ``` * `arcBy(through, to)` Adds an arc from the position of the last segment in the path, passing through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one or more segments to the path. * Parameters: * `through:` `Point` — the vector where the arc should pass through * `to:` `Point` — the vector where the arc should end * `arcBy(to[, clockwise])` Adds an arc from the position of the last segment in the path to the `to` vector specified relatively to it, by adding one or more segments to the path. * Parameters: * `to:` `Point` — the vector where the arc should end * `clockwise:` `Boolean` — specifies whether the arc should be drawn in clockwise direction — optional, default: `true` * `curveBy(through, to[, time])` Adds a curve from the last segment in the path through the specified `through` vector, to the specified `to` vector, all specified relatively to it by these given vectors, by adding one segment to the path. * Parameters: * `through:` `Point` — the vector through which the curve should pass * `to:` `Point` — the destination vector of the newly added curve * `time:` `Number` — the curve-time parameter at which the `through` point is to be located — optional, default: `0.5` * `cubicCurveBy(handle1, handle2, to)` Adds a cubic bezier curve to the path, from the last segment to the to the specified `to` vector, with the curve itself defined by two specified handles. * Parameters: * `handle1:` `Point` — the location of the first handle of the newly added curve * `handle2:` `Point` — the location of the second handle of the newly added curve * `to:` `Point` — the destination point of the newly added curve * `quadraticCurveBy(handle, to)` Adds a quadratic bezier curve to the path, from the last segment to the specified destination point, with the curve itself defined by the specified handle. Note that Paper.js only stores cubic curves, so the handle is actually converted. * Parameters: * `handle:` `Point` — the handle of the newly added quadratic curve out of which the values for `segment.handleOut` of the resulting cubic curve’s first segment and `segment.handleIn` of its second segment are calculated * `to:` `Point` — the destination point of the newly added curve # Segment The Segment object represents the points of a path through which its [`Curve`](/paths/curve) objects pass. The segments of a path can be accessed through its `path.segments` array. Each segment consists of an anchor point (`segment.point`) and optionaly an incoming and an outgoing handle (`segment.handleIn` and `segment.handleOut`), describing the tangents of the two `Curve` objects that are connected by this segment. ## Constructors * `Segment([point[, handleIn[, handleOut]]])` Creates a new Segment object. * Parameters: * `point:` `Point` — the anchor point of the segment — optional, default: `{x: 0, y: 0}` * `handleIn:` `Point` — the handle point relative to the anchor point of the segment that describes the in tangent of the segment — optional, default: `{x: 0, y: 0}` * `handleOut:` `Point` — the handle point relative to the anchor point of the segment that describes the out tangent of the segment — optional, default: `{x: 0, y: 0}` * Returns: * `Segment` Example: ```jsx var handleIn = new Point(-80, -100); var handleOut = new Point(80, 100); var firstPoint = new Point(100, 50); var firstSegment = new Segment(firstPoint, null, handleOut); var secondPoint = new Point(300, 50); var secondSegment = new Segment(secondPoint, handleIn, null); var path = new Path(firstSegment, secondSegment); path.strokeColor = 'black'; ``` * `Segment(object)` Creates a new Segment object. * Parameters: * `object:` `Object` — an object containing properties to be set on the segment * Returns: * `Segment` Example:Creating segments using object notation: ```jsx var firstSegment = new Segment({ point: [100, 50], handleOut: [80, 100] }); var secondSegment = new Segment({ point: [300, 50], handleIn: [-80, -100] }); var path = new Path({ segments: [firstSegment, secondSegment], strokeColor: 'black' }); ``` ## Properties * `point` The anchor point of the segment. * Type: * `Point` * `handleIn` The handle point relative to the anchor point of the segment that describes the in tangent of the segment. * Type: * `Point` * `handleOut` The handle point relative to the anchor point of the segment that describes the out tangent of the segment. * Type: * `Point` * `selected` Specifies whether the segment is selected. * Type: * `Boolean` Example: ```jsx var path = new Path.Circle({ center: [80, 50], radius: 40 }); // Select the third segment point: path.segments[2].selected = true; ``` ### Hierarchy * `index` The index of the segment in the `path.segments` array that the segment belongs to. Read only. * Type: * `Number` * `path` The path that the segment belongs to. Read only. * Type: * `Path` * `curve` The curve that the segment belongs to. For the last segment of an open path, the previous segment is returned. Read only. * Type: * `Curve` * `location` The curve location that describes this segment’s position on the path. Read only. * Type: * `CurveLocation` ### Sibling Segments * `next` The next segment in the `path.segments` array that the segment belongs to. If the segments belongs to a closed path, the first segment is returned for the last segment of the path. Read only. * Type: * `Segment` * `previous` The previous segment in the `path.segments` array that the segment belongs to. If the segments belongs to a closed path, the last segment is returned for the first segment of the path. Read only. * Type: * `Segment` ## Methods * `hasHandles()` Checks if the segment has any curve handles set. * Returns: * `Boolean` — `true` if the segment has handles set, `false` otherwise * See also: * `segment.handleIn` * `segment.handleOut` * `curve.hasHandles`() * `path.hasHandles`() * `isSmooth()` Checks if the segment connects two curves smoothly, meaning that its two handles are collinear and segment does not form a corner. * Returns: * `Boolean` — `true` if the segment is smooth, `false` otherwise * See also: * `point.isCollinear`() * `clearHandles()` Clears the segment’s handles by setting their coordinates to zero, turning the segment into a corner. * `smooth([options])` Smooths the bezier curves that pass through this segment by taking into account the segment’s position and distance to the neighboring segments and changing the direction and length of the segment’s handles accordingly without moving the segment itself. Two different smoothing methods are available: * `'catmull-rom'` uses the Catmull-Rom spline to smooth the segment. The optionally passed factor controls the knot parametrization of the algorithm: * `0.0`: the standard, uniform Catmull-Rom spline * `0.5`: the centripetal Catmull-Rom spline, guaranteeing no self-intersections * `1.0`: the chordal Catmull-Rom spline * `'geometric'` 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. The optionally passed factor defines the tension parameter (`0…1`), controlling the amount of smoothing as a factor by which to scale each handle. * Options: * `options.type: String` — the type of smoothing method: `‘catmull-rom’`, `‘geometric’` — default: `‘catmull-rom’` * `options.factor: Number` — the factor parameterizing the smoothing method — default: `0.5` for `'catmull-rom'`, `0.4` for `'geometric'` * Parameters: * `options:` `Object` — the smoothing options — optional * See also: * `pathItem.smooth([options])` * `isFirst()` Checks if the this is the first segment in the `path.segments` array. * Returns: * `Boolean` — `true` if this is the first segment, `false` otherwise * `isLast()` Checks if the this is the last segment in the `path.segments` array. * Returns: * `Boolean` — `true` if this is the last segment, `false` otherwise * `reverse()` Reverses the `handleIn` and `handleOut` vectors of this segment, modifying the actual segment without creating a copy. * Returns: * `Segment` — the reversed segment * `reversed()` Returns the reversed the segment, without modifying the segment itself. * Returns: * `Segment` — the reversed segment * `remove()` Removes the segment from the path that it belongs to. * Returns: * `Boolean` — `true` if the segment was removed, `false` otherwise * `clone()` * Returns: * `Segment` * `toString()` * Returns: * `String` — a string representation of the segment * `transform(matrix)` Transform the segment by the specified matrix. * Parameters: * `matrix:` `Matrix` — the matrix to transform the segment by * `interpolate(from, to, factor)` Interpolates between the two specified segments and sets the point and handles of this segment accordingly. * Parameters: * `from:` `Segment` — the segment defining the geometry when `factor` is `0` * `to:` `Segment` — the segment defining the geometry when `factor` is `1` * `factor:` `Number` — the interpolation coefficient, typically between `0` and `1`, but extrapolation is possible too # Curve The Curve object represents the parts of a path that are connected by two following [`Segment`](/paths/segment) objects. The curves of a path can be accessed through its `path.curves` array. While a segment describe the anchor point and its incoming and outgoing handles, a Curve object describes the curve passing between two such segments. Curves and segments represent two different ways of looking at the same thing, but focusing on different aspects. Curves for example offer many convenient ways to work with parts of the path, finding lengths, positions or tangents at given offsets. ## Constructors * `Curve(segment1, segment2)` Creates a new curve object. * Parameters: * `segment1:` `Segment` * `segment2:` `Segment` * Returns: * `Curve` * `Curve(point1, handle1, handle2, point2)` Creates a new curve object. * Parameters: * `point1:` `Point` * `handle1:` `Point` * `handle2:` `Point` * `point2:` `Point` * Returns: * `Curve` ## Properties * `point1` The first anchor point of the curve. * Type: * `Point` * `point2` The second anchor point of the curve. * Type: * `Point` * `handle1` The handle point that describes the tangent in the first anchor point. * Type: * `Point` * `handle2` The handle point that describes the tangent in the second anchor point. * Type: * `Point` * `segment1` The first segment of the curve. Read only. * Type: * `Segment` * `segment2` The second segment of the curve. Read only. * Type: * `Segment` * `path` The path that the curve belongs to. Read only. * Type: * `Path` * `index` The index of the curve in the `path.curves` array. Read only. * Type: * `Number` * `next` The next curve in the `path.curves` array that the curve belongs to. Read only. * Type: * `Curve` * `previous` The previous curve in the `path.curves` array that the curve belongs to. Read only. * Type: * `Curve` * `selected` Specifies whether the points and handles of the curve are selected. * Type: * `Boolean` * `values` An array of 8 float values, describing this curve’s geometry in four absolute x/y pairs (point1, handle1, handle2, point2). This format is used internally for efficient processing of curve geometries, e.g. when calculating intersections or bounds. Note that the handles are converted to absolute coordinates. Read only. * Type: * Array of `Numbers` * `points` An array of 4 point objects, describing this curve’s geometry in absolute coordinates (point1, handle1, handle2, point2). Note that the handles are converted to absolute coordinates. Read only. * Type: * Array of `Point` objects * `length` The approximated length of the curve. Read only. * Type: * `Number` * `area` The area that the curve’s geometry is covering. Read only. * Type: * `Number` ### Bounding Boxes * `bounds` The bounding rectangle of the curve excluding stroke width. * Type: * `Rectangle` * `strokeBounds` The bounding rectangle of the curve including stroke width. * Type: * `Rectangle` * `handleBounds` The bounding rectangle of the curve including handles. * Type: * `Rectangle` ## Methods * `clone()` Returns a copy of the curve. * Returns: * `Curve` * `toString()` * Returns: * `String` — a string representation of the curve * `classify()` Determines the type of cubic Bézier curve via discriminant classification, as well as the curve-time parameters of the associated points of inflection, loops, cusps, etc. * Returns: * `Object` — the curve classification information as an object, see options * `info.type: String` — the type of Bézier curve, possible values are: `‘line’`, `‘quadratic’`, `‘serpentine’`, `‘cusp’`, `‘loop’`, `‘arch’` * `info.roots: Array of Numbers` — the curve-time parameters of the associated points of inflection for serpentine curves, loops, cusps, etc * `remove()` Removes the curve from the path that it belongs to, by removing its second segment and merging its handle with the first segment. * Returns: * `Boolean` — `true` if the curve was removed, `false` otherwise * `isFirst()` Checks if the this is the first curve in the `path.curves` array. * Returns: * `Boolean` — `true` if this is the first curve, `false` otherwise * `isLast()` Checks if the this is the last curve in the `path.curves` array. * Returns: * `Boolean` — `true` if this is the last curve, `false` otherwise * `getPart(from, to)` Creates a new curve as a sub-curve from this curve, its range defined by the given curve-time parameters. If `from` is larger than `to`, then the resulting curve will have its direction reversed. * Parameters: * `from:` `Number` — the curve-time parameter at which the sub-curve starts * `to:` `Number` — the curve-time parameter at which the sub-curve ends * Returns: * `Curve` — the newly create sub-curve * `divideAt(location)` Divides the curve into two curves at the given offset or location. The curve itself is modified and becomes the first part, the second part is returned as a new curve. If the curve belongs to a path item, a new segment is inserted into the path at the given location, and the second part becomes a part of the path as well. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve at which to divide * Returns: * `Curve` — the second part of the divided curve if the location is valid, {code null} otherwise * See also: * `divideAtTime(time)` * `divideAtTime(time)` Divides the curve into two curves at the given curve-time parameter. The curve itself is modified and becomes the first part, the second part is returned as a new curve. If the modified curve belongs to a path item, the second part is also added to the path. * Parameters: * `time:` `Number` — the curve-time parameter on the curve at which to divide * Returns: * `Curve` — the second part of the divided curve, if the offset is within the valid range, {code null} otherwise. * See also: * `divideAt(offset)` * `splitAt(location)` Splits the path this curve belongs to at the given offset. After splitting, the path will be open. If the path was open already, splitting will result in two paths. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve at which to split * Returns: * `Path` — the newly created path after splitting, if any * See also: * `path.splitAt(offset)` * `splitAtTime(time)` Splits the path this curve belongs to at the given offset. After splitting, the path will be open. If the path was open already, splitting will result in two paths. * Parameters: * `time:` `Number` — the curve-time parameter on the curve at which to split * Returns: * `Path` — the newly created path after splitting, if any * See also: * `path.splitAt(offset)` * `reversed()` Returns a reversed version of the curve, without modifying the curve itself. * Returns: * `Curve` — a reversed version of the curve * `clearHandles()` Clears the curve’s handles by setting their coordinates to zero, turning the curve into a straight line. ### Curve Tests * `hasHandles()` Checks if this curve has any curve handles set. * Returns: * `Boolean` — `true` if the curve has handles set, `false` otherwise * See also: * `curve.handle1` * `curve.handle2` * `segment.hasHandles`() * `path.hasHandles`() * `hasLength([epsilon])` Checks if this curve has any length. * Parameters: * `epsilon:` `Number` — the epsilon against which to compare the curve’s length — optional, default: `0` * Returns: * `Boolean` — `true` if the curve is longer than the given epsilon, `false` otherwise * `isStraight()` Checks if this curve appears as a straight line. This can mean that it has no handles defined, or that the handles run collinear with the line that connects the curve’s start and end point, not falling outside of the line. * Returns: * `Boolean` — `true` if the curve is straight, `false` otherwise * `isLinear()` Checks if this curve is parametrically linear, meaning that it is straight and its handles are positioned at 1/3 and 2/3 of the total length of the curve. * Returns: * `Boolean` — `true` if the curve is parametrically linear, `false` otherwise * `isCollinear(curve)` Checks if the the two curves describe straight lines that are collinear, meaning they run in parallel. * Parameters: * `curve:` `Curve` — the other curve to check against * Returns: * `Boolean` — `true` if the two lines are collinear, `false` otherwise * `isHorizontal()` Checks if the curve is a straight horizontal line. * Returns: * `Boolean` — `true` if the line is horizontal, `false` otherwise * `isVertical()` Checks if the curve is a straight vertical line. * Returns: * `Boolean` — `true` if the line is vertical, `false` otherwise ### Positions on Curves * `getLocationAt(offset)` Calculates the curve location at the specified offset on the curve. * Parameters: * `offset:` `Number` — the offset on the curve * Returns: * `CurveLocation` — the curve location at the specified the offset * `getLocationAtTime(time)` Calculates the curve location at the specified curve-time parameter on the curve. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `CurveLocation` — the curve location at the specified the location * `getTimeAt(offset[, start])` Calculates the curve-time parameter of the specified offset on the path, relative to the provided start parameter. If offset is a negative value, the parameter is searched to the left of the start parameter. If no start parameter is provided, a default of `0` for positive values of `offset` and `1` for negative values of `offset`. * Parameters: * `offset:` `Number` — the offset at which to find the curve-time, in curve length units * `start:` `Number` — the curve-time in relation to which the offset is determined — optional * Returns: * `Number` — the curve-time parameter at the specified location * `getTimesWithTangent(tangent)` Calculates the curve-time parameters where the curve is tangential to provided tangent. Note that tangents at the start or end are included. * Parameters: * `tangent:` `Point` — the tangent to which the curve must be tangential * Returns: * `Array of Numbers` — at most two curve-time parameters, where the curve is tangential to the given tangent * `getOffsetAtTime(time)` Calculates the curve offset at the specified curve-time parameter on the curve. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Number` — the curve offset at the specified the location * `getLocationOf(point)` Returns the curve location of the specified point if it lies on the curve, `null` otherwise. * Parameters: * `point:` `Point` — the point on the curve * Returns: * `CurveLocation` — the curve location of the specified point * `getOffsetOf(point)` Returns the length of the path from its beginning up to up to the specified point if it lies on the path, `null` otherwise. * Parameters: * `point:` `Point` — the point on the path * Returns: * `Number` — the length of the path up to the specified point * `getTimeOf(point)` Returns the curve-time parameter of the specified point if it lies on the curve, `null` otherwise. Note that if there is more than one possible solution in a self-intersecting curve, the first found result is returned. * Parameters: * `point:` `Point` — the point on the curve * Returns: * `Number` — the curve-time parameter of the specified point * `getNearestLocation(point)` Returns the nearest location on the curve to the specified point. * Parameters: * `point:` `Point` — the point for which we search the nearest location * Returns: * `CurveLocation` — the location on the curve that’s the closest to the specified point * `getNearestPoint(point)` Returns the nearest point on the curve to the specified point. * Parameters: * `point:` `Point` — the point for which we search the nearest point * Returns: * `Point` — the point on the curve that’s the closest to the specified point * `getPointAt(location)` Calculates the point on the curve at the given location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Point` — the point on the curve at the given location * `getTangentAt(location)` Calculates the normalized tangent vector of the curve at the given location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Point` — the normalized tangent of the curve at the given location * `getNormalAt(location)` Calculates the normal vector of the curve at the given location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Point` — the normal of the curve at the given location * `getWeightedTangentAt(location)` Calculates the weighted tangent vector of the curve at the given location, its length reflecting the curve velocity at that location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Point` — the weighted tangent of the curve at the given location * `getWeightedNormalAt(location)` Calculates the weighted normal vector of the curve at the given location, its length reflecting the curve velocity at that location. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Point` — the weighted normal of the curve at the given location * `getCurvatureAt(location)` Calculates the curvature of the curve at the given location. Curvatures indicate how sharply a curve changes direction. A straight line has zero curvature, where as a circle has a constant curvature. The curve’s radius at the given location is the reciprocal value of its curvature. * Parameters: * `location:` `Number`⟋`CurveLocation` — the offset or location on the curve * Returns: * `Number` — the curvature of the curve at the given location * `getPointAtTime(time)` Calculates the point on the curve at the given location. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Point` — the point on the curve at the given location * `getTangentAtTime(time)` Calculates the normalized tangent vector of the curve at the given location. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Point` — the normalized tangent of the curve at the given location * `getNormalAtTime(time)` Calculates the normal vector of the curve at the given location. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Point` — the normal of the curve at the given location * `getWeightedTangentAtTime(time)` Calculates the weighted tangent vector of the curve at the given location, its length reflecting the curve velocity at that location. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Point` — the weighted tangent of the curve at the given location * `getWeightedNormalAtTime(time)` Calculates the weighted normal vector of the curve at the given location, its length reflecting the curve velocity at that location. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Point` — the weighted normal of the curve at the given location * `getCurvatureAtTime(time)` Calculates the curvature of the curve at the given location. Curvatures indicate how sharply a curve changes direction. A straight line has zero curvature, where as a circle has a constant curvature. The curve’s radius at the given location is the reciprocal value of its curvature. * Parameters: * `time:` `Number` — the curve-time parameter on the curve * Returns: * `Number` — the curvature of the curve at the given location * `getIntersections(curve)` Returns all intersections between two `Curve` objects as an array of `CurveLocation` objects. * Parameters: * `curve:` `Curve` — the other curve to find the intersections with (if the curve itself or `null` is passed, the self intersection of the curve is returned, if it exists) * Returns: * `Array of CurveLocation` objects — the locations of all intersections between the curves # CurveLocation CurveLocation objects describe a location on [`Curve`](/paths/curve) objects, as defined by the curve-time `time`, a value between `0` (beginning of the curve) and `1` (end of the curve). If the curve is part of a `Path` item, its `index` inside the `path.curves` array is also provided. The class is in use in many places, such as `path.getLocationAt(offset)`, `path.getLocationOf(point)`, `pathItem.getNearestLocation(point)`, `pathItem.getIntersections(path)`, etc. ## Constructors * `CurveLocation(curve, time[, point])` Creates a new CurveLocation object. * Parameters: * `curve:` `Curve` * `time:` `Number` * `point:` `Point` — optional * Returns: * `CurveLocation` ## Properties * `segment` The segment of the curve which is closer to the described location. Read only. * Type: * `Segment` * `curve` The curve that this location belongs to. Read only. * Type: * `Curve` * `path` The path that this locations is situated on. Read only. * Type: * `Path` * `index` The index of the `curve` within the `path.curves` list, if it is part of a `Path` item. Read only. * Type: * `Number` * `time` The curve-time parameter, as used by various bezier curve calculations. It is value between `0` (beginning of the curve) and `1` (end of the curve). Read only. * Type: * `Number` * `point` The point which is defined by the `curve` and `time`. Read only. * Type: * `Point` * `offset` The length of the path from its beginning up to the location described by this object. If the curve is not part of a path, then the length within the curve is returned instead. Read only. * Type: * `Number` * `curveOffset` The length of the curve from its beginning up to the location described by this object. Read only. * Type: * `Number` * `intersection` The curve location on the intersecting curve, if this location is the result of a call to `pathItem.getIntersections(path)` / `curve.getIntersections(curve)`. Read only. * Type: * `CurveLocation` * `tangent` The tangential vector to the `curve` at the given location. Read only. * Type: * `Point` * `normal` The normal vector to the `curve` at the given location. Read only. * Type: * `Point` * `curvature` The curvature of the `curve` at the given location. Read only. * Type: * `Number` * `distance` The distance from the queried point to the returned location. Read only. * Type: * `Number` * See also: * `curve.getNearestLocation(point)` * `pathItem.getNearestLocation(point)` ## Methods * `equals(location)` Checks whether tow CurveLocation objects are describing the same location on a path, by applying the same tolerances as elsewhere when dealing with curve-time parameters. * Parameters: * `location:` `CurveLocation` * Returns: * `Boolean` — `true` if the locations are equal, `false` otherwise * `toString()` * Returns: * `String` — a string representation of the curve location ### Tests * `isTouching()` Checks if the location is an intersection with another curve and is merely touching the other curve, as opposed to crossing it. * Returns: * `Boolean` — `true` if the location is an intersection that is merely touching another curve, `false` otherwise * See also: * `isCrossing`() * `isCrossing()` Checks if the location is an intersection with another curve and is crossing the other curve, as opposed to just touching it. * Returns: * `Boolean` — `true` if the location is an intersection that is crossing another curve, `false` otherwise * See also: * `isTouching`() * `hasOverlap()` Checks if the location is an intersection with another curve and is part of an overlap between the two involved paths. * Returns: * `Boolean` — `true` if the location is an intersection that is part of an overlap between the two involved paths, `false` otherwise * See also: * `isCrossing`() * `isTouching`() # SymbolDefinition Symbols allow you to place multiple instances of an item in your project. This can save memory, since all instances of a symbol simply refer to the original item and it can speed up moving around complex objects, since internal properties such as segment lists and gradient positions don’t need to be updated with every transformation. ## Constructors * `SymbolDefinition(item[, dontCenter])` Creates a Symbol definition. * Parameters: * `item:` `Item` — the source item which is removed from the scene graph and becomes the symbol’s definition. * `dontCenter:` `Boolean` — optional, default: `false` * Returns: * `SymbolDefinition` Example:Placing 100 instances of a symbol: ```jsx var path = new Path.Star(new Point(0, 0), 6, 5, 13); path.style = { fillColor: 'white', strokeColor: 'black' }; // Create a symbol definition from the path: var definition = new SymbolDefinition(path); // Place 100 instances of the symbol definition: for (var i = 0; i < 100; i++) { // Place an instance of the symbol definition in the project: var instance = definition.place(); // Move the instance to a random position within the view: instance.position = Point.random() * view.size; // Rotate the instance by a random amount between // 0 and 360 degrees: instance.rotate(Math.random() * 360); // Scale the instance between 0.25 and 1: instance.scale(0.25 + Math.random() * 0.75); } ``` ## Properties * `project` The project that this symbol belongs to. Read only. * Type: * `Project` * `item` The item used as the symbol’s definition. * Type: * `Item` ## Methods * `place([position])` Places in instance of the symbol in the project. * Parameters: * `position:` `Point` — the position of the placed symbol — optional * Returns: * `SymbolItem` * `clone()` Returns a copy of the symbol. * Returns: * `SymbolDefinition` * `equals(symbol)` Checks whether the symbol’s definition is equal to the supplied symbol. * Parameters: * `symbol:` `SymbolDefinition` * Returns: * `Boolean` — `true` if they are equal, `false` otherwise # SymbolItem Extends [**`Item`**](/project-and-items/item) A symbol item represents an instance of a symbol which has been placed in a Paper.js project. ## Constructors * `SymbolItem(definition[, point])` Creates a new symbol item. * Parameters: * `definition:` `SymbolDefinition`⟋`Item` — the definition to place or an item to place as a symbol * `point:` `Point` — the center point of the placed symbol — optional * Returns: * `SymbolItem` Example:Placing 100 instances of a symbol: Create a star shaped path at {x: 0, y: 0}: ``` var path = new Path.Star({ center: new Point(0, 0), points: 6, radius1: 5, radius2: 13, fillColor: 'white', strokeColor: 'black' }); // Create a symbol definition from the path: var definition = new SymbolDefinition(path); // Place 100 instances of the symbol: for (var i = 0; i < 100; i++) { // Place an instance of the symbol in the project: var instance = new SymbolItem(definition); // Move the instance to a random position within the view: instance.position = Point.random() * view.size; // Rotate the instance by a random amount between // 0 and 360 degrees: instance.rotate(Math.random() * 360); // Scale the instance between 0.25 and 1: instance.scale(0.25 + Math.random() * 0.75); } ``` ## Properties * `definition` The symbol definition that the placed symbol refers to. * Type: * `SymbolDefinition` ## Properties inherited from `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ``` var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ``` var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ``` var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ``` var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ``` // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ``` 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 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ``` // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ``` // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ``` 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(); path.parent = group; // 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ``` 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ``` var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ``` var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ``` // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ``` // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ``` // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ``` // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ``` // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ``` // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ``` // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ``` 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ``` var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ``` var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ``` var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ``` var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `Item` * `exportSVG([options])` Exports the item with its content and child items as an SVG DOM. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the item converted to an SVG node or a `String` depending on `option.asString` value * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ``` // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ``` // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ``` // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ``` var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ``` // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ``` // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ``` 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ``` 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ``` function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ``` function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ``` 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ``` function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # Style Style is used for changing the visual styles of items contained within a Paper.js project and is returned by `item.style` and `project.currentStyle`. All properties of Style are also reflected directly in `Item`, i.e.: `item.fillColor`. To set multiple style properties in one go, you can pass an object to `item.style`. This is a convenient way to define a style once and apply it to a series of items: Example: Styling paths ```jsx var path = new Path.Circle(new Point(80, 50), 30); path.style = { fillColor: new Color(1, 0, 0), strokeColor: 'black', strokeWidth: 5 }; ``` Example: Styling text items ```jsx var text = new PointText(view.center); text.content = 'Hello world.'; text.style = { fontFamily: 'Courier New', fontWeight: 'bold', fontSize: 20, fillColor: 'red', justification: 'center' }; ``` Example: Styling groups ```jsx var path1 = new Path.Circle({ center: [100, 50], radius: 30 }); var path2 = new Path.Rectangle({ from: [170, 20], to: [230, 80] }); var group = new Group(path1, path2); // All styles set on a group are automatically // set on the children of the group: group.style = { strokeColor: 'black', dashArray: [4, 10], strokeWidth: 4, strokeCap: 'round' }; ``` ## Properties * `view` The view that this style belongs to. Read only. * Type: * `View` ### Stroke Style * `strokeColor` The color of the stroke. * Type: * `Color`⟋`null` Example:Setting the stroke color of a path: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle(new Point(80, 50), 35); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Default: * `1` * Type: * `Number` Example:Setting an item's stroke width: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle(new Point(80, 50), 35); // Set its stroke color to black: circle.strokeColor = 'black'; // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ```jsx var line = new Path(new Point(80, 50), new Point(420, 50)); line.strokeColor = 'black'; line.strokeWidth = 20; // Select the path, so we can see where the stroke is formed: line.selected = true; // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ```jsx var path = new Path(); path.add(new Point(80, 100)); path.add(new Point(120, 40)); path.add(new Point(160, 100)); path.strokeColor = 'black'; path.strokeWidth = 20; // Select the path, so we can see where the stroke is formed: path.selected = true; var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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` * `dashOffset` The dash offset of the stroke. * Default: * `0` * Type: * `Number` * `dashArray` Specifies an array containing the dash and gap lengths of the stroke. * Default: * `[]` * Type: * Array of `Numbers` Example: ```jsx var path = new Path.Circle(new Point(80, 50), 40); path.strokeWidth = 2; path.strokeColor = 'black'; // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `miterLimit` The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for `strokeJoin`, it is possible for the miter to extend far beyond the `strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `strokeWidth`. * Default: * `10` * Type: * `Number` ### Fill Style * `fillColor` The fill color. * Type: * `Color`⟋`null` Example:Setting the fill color of a path to red: ```jsx // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle(new Point(80, 50), 35); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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` ### Character Style * `fontFamily` The font-family to be used in text content. * Default: * `'sans-serif'` * Type: * `String` * `fontWeight` The font-weight to be used in text content. * Default: * `'normal'` * Type: * `String`⟋`Number` * `fontSize` The font size of text content, as a number in pixels, or as a string with optional units `'px'`, `'pt'` and `'em'`. * Default: * `10` * Type: * `Number`⟋`String` * `leading` The text leading of text content. * Default: * `fontSize * 1.2` * Type: * `Number`⟋`String` ### Paragraph Style * `justification` The justification of text paragraphs. * Values: * `'left'`, `'right'`, `'center'` * Default: * `'left'` * Type: * `String` # Color All properties and functions that expect color values in the form of instances of Color objects, also accept named colors and hex values as strings which are then converted to instances of `Color` internally. Example: Named color values: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30. var circle = new Path.Circle(new Point(80, 50), 30); // Pass a color name to the fillColor property, which is internally // converted to a Color. circle.fillColor = 'green'; ``` Example: Hex color values: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30. var circle = new Path.Circle(new Point(80, 50), 30); // Pass a hex string to the fillColor property, which is internally // converted to a Color. circle.fillColor = '#ff0000'; ``` ## Constructors * `Color(red, green, blue[, alpha])` Creates a RGB Color object. * Parameters: * `red:` `Number` — the amount of red in the color as a value between `0` and `1` * `green:` `Number` — the amount of green in the color as a value between `0` and `1` * `blue:` `Number` — the amount of blue in the color as a value between `0` and `1` * `alpha:` `Number` — the alpha of the color as a value between `0` and `1` — optional * Returns: * `Color` Example:Creating a RGB Color: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30: var circle = new Path.Circle(new Point(80, 50), 30); // 100% red, 0% blue, 50% blue: circle.fillColor = new Color(1, 0, 0.5); ``` * `Color(gray[, alpha])` Creates a gray Color object. * Parameters: * `gray:` `Number` — the amount of gray in the color as a value between `0` and `1` * `alpha:` `Number` — the alpha of the color as a value between `0` and `1` — optional * Returns: * `Color` Example:Creating a gray Color: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30: var circle = new Path.Circle(new Point(80, 50), 30); // Create a GrayColor with 50% gray: circle.fillColor = new Color(0.5); ``` * `Color(object)` Creates a HSB, HSL or gradient Color object from the properties of the provided object: * Options: * `hsb.hue: Number` — the hue of the color as a value in degrees between `0` and `360` * `hsb.saturation: Number` — the saturation of the color as a value between `0` and `1` * `hsb.brightness: Number` — the brightness of the color as a value between `0` and `1` * `hsb.alpha: Number` — the alpha of the color as a value between `0` and `1` * `hsl.hue: Number` — the hue of the color as a value in degrees between `0` and `360` * `hsl.saturation: Number` — the saturation of the color as a value between `0` and `1` * `hsl.lightness: Number` — the lightness of the color as a value between `0` and `1` * `hsl.alpha: Number` — the alpha of the color as a value between `0` and `1` * `gradient.gradient: Gradient` — the gradient object that describes the color stops and type of gradient to be used * `gradient.origin: Point` — the origin point of the gradient * `gradient.destination: Point` — the destination point of the gradient * `gradient.stops: Array of GradientStop` objects — the gradient stops describing the gradient, as an alternative to providing a gradient object * `gradient.radial: Boolean` — controls whether the gradient is radial, as an alternative to providing a gradient object * Parameters: * `object:` `Object` — an object describing the components and properties of the color * Returns: * `Color` Example:Creating a HSB Color: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30: var circle = new Path.Circle(new Point(80, 50), 30); // Create an HSB Color with a hue of 90 degrees, a saturation // 100% and a brightness of 100%: circle.fillColor = { hue: 90, saturation: 1, brightness: 1 }; ``` Example:Creating a HSL Color: ```jsx // Create a circle shaped path at {x: 80, y: 50} // with a radius of 30: var circle = new Path.Circle(new Point(80, 50), 30); // Create an HSL Color with a hue of 90 degrees, a saturation // 100% and a lightness of 50%: circle.fillColor = { hue: 90, saturation: 1, lightness: 0.5 }; ``` Example:Creating a gradient color from an object literal: ```jsx // Define two points which we will be using to construct // the path and to position the gradient color: var topLeft = view.center - [80, 80]; var bottomRight = view.center + [80, 80]; var path = new Path.Rectangle({ topLeft: topLeft, bottomRight: bottomRight, // Fill the path with a gradient of three color stops // that runs between the two points we defined earlier: fillColor: { stops: ['yellow', 'red', 'blue'], origin: topLeft, destination: bottomRight } }); ``` * `Color(color)` Creates a Color object from a CSS string. All common CSS color string formats are supported: - Named colors (e.g. `'red'`, `'fuchsia'`, …) - Hex strings (`'#ffff00'`, `'#ff0'`, …) - RGB strings (`'rgb(255, 128, 0)'`, `'rgba(255, 128, 0, 0.5)'`, …) - HSL strings (`'hsl(180deg, 20%, 50%)'`, `'hsla(3.14rad, 20%, 50%, 0.5)'`, …) * Parameters: * `color:` `String` — the color’s CSS string representation * Returns: * `Color` Example: ```jsx var circle = new Path.Circle({ center: [80, 50], radius: 30, fillColor: new Color('rgba(255, 255, 0, 0.5)') }); ``` * `Color(gradient, origin, destination[, highlight])` Creates a gradient Color object. * Parameters: * `gradient:` `Gradient` * `origin:` `Point` * `destination:` `Point` * `highlight:` `Point` — optional * Returns: * `Color` Example:Applying a linear gradient color containing evenly distributed color stops: ```jsx // Define two points which we will be using to construct // the path and to position the gradient color: var topLeft = view.center - [80, 80]; var bottomRight = view.center + [80, 80]; // Create a rectangle shaped path between // the topLeft and bottomRight points: var path = new Path.Rectangle(topLeft, bottomRight); // Create the gradient, passing it an array of colors to be converted // to evenly distributed color stops: var gradient = new Gradient(['yellow', 'red', 'blue']); // Have the gradient color run between the topLeft and // bottomRight points we defined earlier: var gradientColor = new Color(gradient, topLeft, bottomRight); // Set the fill color of the path to the gradient color: path.fillColor = gradientColor; ``` Example:Applying a radial gradient color containing unevenly distributed color stops: ```jsx // Create a circle shaped path at the center of the view // with a radius of 80: var path = new Path.Circle({ center: view.center, radius: 80 }); // The stops array: yellow mixes with red between 0 and 15%, // 15% to 30% is pure red, red mixes with black between 30% to 100%: var stops = [ ['yellow', 0], ['red', 0.15], ['red', 0.3], ['black', 0.9] ]; // Create a radial gradient using the color stops array: var gradient = new Gradient(stops, true); // We will use the center point of the circle shaped path as // the origin point for our gradient color var from = path.position; // The destination point of the gradient color will be the // center point of the path + 80pt in horizontal direction: var to = path.position + [80, 0]; // Create the gradient color: var gradientColor = new Color(gradient, from, to); // Set the fill color of the path to the gradient color: path.fillColor = gradientColor; ``` ## Operators * `+number`, `+color` Returns the addition of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Color` — the addition of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color + 1; console.log(result); // { red: 1, blue: 1, green: 1 } ``` Returns the addition of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to add * Returns: * `Color` — the addition of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(1, 0, 0); var result = color1 + color2; console.log(result); // { red: 1, blue: 1, green: 1 } ``` * `-number`, `-color` Returns the subtraction of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Color` — the subtraction of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color - 1; console.log(result); // { red: 0, blue: 0, green: 0 } ``` Returns the subtraction of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to subtract * Returns: * `Color` — the subtraction of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(1, 0, 0); var result = color1 - color2; console.log(result); // { red: 0, blue: 1, green: 1 } ``` * `*number`, `*color` Returns the multiplication of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply * Returns: * `Color` — the multiplication of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color * 0.5; console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 } ``` Returns the multiplication of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to multiply * Returns: * `Color` — the multiplication of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(0.5, 0, 0.5); var result = color1 * color2; console.log(result); // { red: 0, blue: 0, green: 0.5 } ``` * `/number`, `/color` Returns the division of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide * Returns: * `Color` — the division of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color / 2; console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 } ``` Returns the division of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to divide * Returns: * `Color` — the division of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(0.5, 0, 0.5); var result = color1 / color2; console.log(result); // { red: 0, blue: 0, green: 1 } ``` ## Properties * `type` The type of the color as a string. * Type: * `String` Example: ```jsx var color = new Color(1, 0, 0); console.log(color.type); // 'rgb' ``` * `components` The color components that define the color, including the alpha value if defined. Read only. * Type: * Array of `Numbers` * `alpha` The color’s alpha value as a number between `0` and `1`. All colors of the different subclasses support alpha values. * Default: * `1` * Type: * `Number` Example: A filled path with a half transparent stroke: ```jsx var circle = new Path.Circle(new Point(80, 50), 30); // Fill the circle with red and give it a 20pt green stroke: circle.style = { fillColor: 'red', strokeColor: 'green', strokeWidth: 20 }; // Make the stroke half transparent: circle.strokeColor.alpha = 0.5; ``` ### RGB Components * `red` The amount of red in the color as a value between `0` and `1`. * Type: * `Number` Example: Changing the amount of red in a color: ```jsx var circle = new Path.Circle(new Point(80, 50), 30); circle.fillColor = 'blue'; // Blue + red = purple: circle.fillColor.red = 1; ``` * `green` The amount of green in the color as a value between `0` and `1`. * Type: * `Number` Example: Changing the amount of green in a color: ```jsx var circle = new Path.Circle(new Point(80, 50), 30); // First we set the fill color to red: circle.fillColor = 'red'; // Red + green = yellow: circle.fillColor.green = 1; ``` * `blue` The amount of blue in the color as a value between `0` and `1`. * Type: * `Number` Example: Changing the amount of blue in a color: ```jsx var circle = new Path.Circle(new Point(80, 50), 30); // First we set the fill color to red: circle.fillColor = 'red'; // Red + blue = purple: circle.fillColor.blue = 1; ``` ### Gray Components * `gray` The amount of gray in the color as a value between `0` and `1`. * Type: * `Number` ### HSB Components * `hue` The hue of the color as a value in degrees between `0` and `360`. * Type: * `Number` Example: Changing the hue of a color: ```jsx var circle = new Path.Circle(new Point(80, 50), 30); circle.fillColor = 'red'; circle.fillColor.hue += 30; ``` Example: Hue cycling: ```jsx // Create a rectangle shaped path, using the dimensions // of the view: var path = new Path.Rectangle(view.bounds); path.fillColor = 'red'; function onFrame(event) { path.fillColor.hue += 0.5; } ``` * `saturation` The saturation of the color as a value between `0` and `1`. * Type: * `Number` * `brightness` The brightness of the color as a value between `0` and `1`. * Type: * `Number` ### HSL Components * `lightness` The lightness of the color as a value between `0` and `1`. Note that all other components are shared with HSB. * Type: * `Number` ### Gradient Components * `gradient` The gradient object describing the type of gradient and the stops. * Type: * `Gradient` * `highlight` The highlight point of the gradient. * Type: * `Point` Example: Create a circle shaped path at the center of the view, using 40% of the height of the view as its radius and fill it with a radial gradient color: ```jsx var path = new Path.Circle({ center: view.center, radius: view.bounds.height * 0.4 }); path.fillColor = { gradient: { stops: ['yellow', 'red', 'black'], radial: true }, origin: path.position, destination: path.bounds.rightCenter }; function onMouseMove(event) { // Set the origin highlight of the path's gradient color // to the position of the mouse: path.fillColor.highlight = event.point; } ``` ## Methods * `set(...values)` Sets the color to the passed values. Note that any sequence of parameters that is supported by the various `Color`() constructors also work for calls of `set()`. * Parameters: * `values:` `any value` * Returns: * `Color` * `convert(type)` Converts the color to another type. * Parameters: * `type:` `String` — the color type to convert to. Possible values: `‘rgb’`, `‘gray’`, `‘hsb’`, `‘hsl’` * Returns: * `Color` — the converted color as a new instance * `hasAlpha()` Checks if the color has an alpha value. * Returns: * `Boolean` — `true` if the color has an alpha value, `false` otherwise * `equals(color)` Checks if the component color values of the color are the same as those of the supplied one. * Parameters: * `color:` `Color` — the color to compare with * Returns: * `Boolean` — `true` if the colors are the same, `false` otherwise * `clone()` * Returns: * `Color` — a copy of the color object ### String Representations * `toString()` * Returns: * `String` — a string representation of the color * `toCSS(hex)` Returns the color as a CSS string. * Parameters: * `hex:` `Boolean` — whether to return the color in hexadecimal representation or as a CSS RGB / RGBA string. * Returns: * `String` — a CSS string representation of the color * `transform(matrix)` Transform the gradient color by the specified matrix. * Parameters: * `matrix:` `Matrix` — the matrix to transform the gradient color by ### Math Operator Functions * `add(number)` Returns the addition of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to add * Returns: * `Color` — the addition of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color + 1; console.log(result); // { red: 1, blue: 1, green: 1 } ``` * `add(color)` Returns the addition of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to add * Returns: * `Color` — the addition of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(1, 0, 0); var result = color1 + color2; console.log(result); // { red: 1, blue: 1, green: 1 } ``` * `subtract(number)` Returns the subtraction of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to subtract * Returns: * `Color` — the subtraction of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color - 1; console.log(result); // { red: 0, blue: 0, green: 0 } ``` * `subtract(color)` Returns the subtraction of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to subtract * Returns: * `Color` — the subtraction of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(1, 0, 0); var result = color1 - color2; console.log(result); // { red: 0, blue: 1, green: 1 } ``` * `multiply(number)` Returns the multiplication of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to multiply * Returns: * `Color` — the multiplication of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color * 0.5; console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 } ``` * `multiply(color)` Returns the multiplication of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to multiply * Returns: * `Color` — the multiplication of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(0.5, 0, 0.5); var result = color1 * color2; console.log(result); // { red: 0, blue: 0, green: 0.5 } ``` * `divide(number)` Returns the division of the supplied value to both coordinates of the color as a new color. The object itself is not modified! * Parameters: * `number:` `Number` — the number to divide * Returns: * `Color` — the division of the color and the value as a new color Example: ```jsx var color = new Color(0.5, 1, 1); var result = color / 2; console.log(result); // { red: 0.25, blue: 0.5, green: 0.5 } ``` * `divide(color)` Returns the division of the supplied color to the color as a new color. The object itself is not modified! * Parameters: * `color:` `Color` — the color to divide * Returns: * `Color` — the division of the two colors as a new color Example: ```jsx var color1 = new Color(0, 1, 1); var color2 = new Color(0.5, 0, 0.5); var result = color1 / color2; console.log(result); // { red: 0, blue: 0, green: 1 } ``` ## Static Methods * `Color.random()` Returns a color object with random `red`, `green` and `blue` values between `0` and `1`. * Returns: * `Color` — the newly created color object Example: ```jsx var circle = new Path.Circle(view.center, 50); // Set a random color as circle fill color. circle.fillColor = Color.random(); ``` # Gradient The Gradient object. Example:Applying a linear gradient color containing evenly distributed color stops: ```jsx // Define two points which we will be using to construct // the path and to position the gradient color: var topLeft = view.center - [80, 80]; var bottomRight = view.center + [80, 80]; // Create a rectangle shaped path between // the topLeft and bottomRight points: var path = new Path.Rectangle({ topLeft: topLeft, bottomRight: bottomRight, // Fill the path with a gradient of three color stops // that runs between the two points we defined earlier: fillColor: { gradient: { stops: ['yellow', 'red', 'blue'] }, origin: topLeft, destination: bottomRight } }); ``` Example:Create a circle shaped path at the center of the view, using 40% of the height of the view as its radius and fill it with a radial gradient color: ```jsx var path = new Path.Circle({ center: view.center, radius: view.bounds.height * 0.4 }); // Fill the path with a radial gradient color with three stops: // yellow from 0% to 5%, mix between red from 5% to 20%, // mix between red and black from 20% to 100%: path.fillColor = { gradient: { stops: [['yellow', 0.05], ['red', 0.2], ['black', 1]], radial: true }, origin: path.position, destination: path.bounds.rightCenter }; ``` ## Properties * `stops` The gradient stops on the gradient ramp. * Type: * Array of `GradientStop` objects * `radial` Specifies whether the gradient is radial or linear. * Type: * `Boolean` ## Methods * `clone()` * Returns: * `Gradient` — a copy of the gradient * `equals(gradient)` Checks whether the gradient is equal to the supplied gradient. * Parameters: * `gradient:` `Gradient` * Returns: * `Boolean` — `true` if they are equal, `false` otherwise # GradientStop The GradientStop object. ## Constructors * `GradientStop([color[, offset]])` Creates a GradientStop object. * Parameters: * `color:` `Color` — the color of the stop — optional, default: `new Color(0, 0, 0)` * `offset:` `Number` — the position of the stop on the gradient ramp as a value between `0` and `1`; `null` or `undefined` for automatic assignment. — optional, default: `null` * Returns: * `GradientStop` ## Properties * `offset` The ramp-point of the gradient stop as a value between `0` and `1`. * Type: * `Number` Example:Animating a gradient's ramp points: ```jsx // Create a circle shaped path at the center of the view, // using 40% of the height of the view as its radius // and fill it with a radial gradient color: var path = new Path.Circle({ center: view.center, radius: view.bounds.height * 0.4 }); path.fillColor = { gradient: { stops: [['yellow', 0.05], ['red', 0.2], ['black', 1]], radial: true }, origin: path.position, destination: path.bounds.rightCenter }; var gradient = path.fillColor.gradient; // This function is called each frame of the animation: function onFrame(event) { var blackStop = gradient.stops[2]; // Animate the offset between 0.7 and 0.9: blackStop.offset = Math.sin(event.time * 5) * 0.1 + 0.8; // Animate the offset between 0.2 and 0.4 var redStop = gradient.stops[1]; redStop.offset = Math.sin(event.time * 3) * 0.1 + 0.3; } ``` * `color` The color of the gradient stop. * Type: * `Color` Example:Animating a gradient's ramp points: ```jsx // Create a circle shaped path at the center of the view, // using 40% of the height of the view as its radius // and fill it with a radial gradient color: var path = new Path.Circle({ center: view.center, radius: view.bounds.height * 0.4 }); path.fillColor = { gradient: { stops: [['yellow', 0.05], ['red', 0.2], ['black', 1]], radial: true }, origin: path.position, destination: path.bounds.rightCenter }; var redStop = path.fillColor.gradient.stops[1]; var blackStop = path.fillColor.gradient.stops[2]; // This function is called each frame of the animation: function onFrame(event) { // Animate the offset between 0.7 and 0.9: blackStop.offset = Math.sin(event.time * 5) * 0.1 + 0.8; // Animate the offset between 0.2 and 0.4 redStop.offset = Math.sin(event.time * 3) * 0.1 + 0.3; } ``` ## Methods * `clone()` * Returns: * `GradientStop` — a copy of the gradient-stop # Tween Allows tweening `Object` properties between two states for a given duration. To tween properties on Paper.js `Item` instances, `item.tween(from, to, options)` can be used, which returns created tween instance. ## Constructors * `Tween(object, from, to, duration[, easing[, start]])` Creates a new tween. * Parameters: * `object:` `Object` — the object to tween the properties on * `from:` `Object` — the state at the start of the tweening * `to:` `Object` — the state at the end of the tweening * `duration:` `Number` — the duration of the tweening * `easing:` `String`⟋`Function` — the type of the easing function or the easing function — optional, default: `‘linear’` * `start:` `Boolean` — whether to start tweening automatically — optional, default: `true` * Returns: * `Tween` — the newly created tween ## Properties ### Event Handlers * `onUpdate` The function to be called when the tween is updated. It receives an object as its sole argument, containing the current progress of the tweening and the factor calculated by the easing function. * Type: * `Function`⟋`null` Example:Display tween progression values: ```jsx var circle = new Path.Circle({ center: view.center, radius: 40, fillColor: 'blue' }); var tween = circle.tweenTo( { fillColor: 'red' }, { duration: 2000, easing: 'easeInCubic' } ); var progressText = new PointText(view.center + [60, -10]); var factorText = new PointText(view.center + [60, 10]); // Install event using onUpdate() property: tween.onUpdate = function(event) { progressText.content = 'progress: ' + event.progress.toFixed(2); }; // Install event using on('update') method: tween.on('update', function(event) { factorText.content = 'factor: ' + event.factor.toFixed(2); }); ``` ## Methods * `then(function)` Set a function that will be executed when the tween completes. * Parameters: * `function:` `Function` — the function to execute when the tween completes * Returns: * `Tween` Example:Tweens chaining: ```jsx var circle = new Path.Circle({ center: view.center, radius: 40, fillColor: 'blue' }); // Tween color from blue to red. var tween = circle.tweenTo({ fillColor: 'red' }, 2000); // When the first tween completes... tween.then(function() { // ...tween color back to blue. circle.tweenTo({ fillColor: 'blue' }, 2000); }); ``` * `start()` Start tweening. * Returns: * `Tween` Example:Manually start tweening. ```jsx var circle = new Path.Circle({ center: view.center, radius: 40, fillColor: 'blue' }); var tween = circle.tweenTo( { fillColor: 'red' }, { duration: 2000, start: false } ); tween.start(); ``` * `stop()` Stop tweening. * Returns: * `Tween` Example:Stop a tween before it completes. ```jsx var circle = new Path.Circle({ center: view.center, radius: 40, fillColor: 'blue' }); // Start tweening from blue to red for 2 seconds. var tween = circle.tweenTo({ fillColor: 'red' }, 2000); // After 1 second... setTimeout(function(){ // ...stop tweening. tween.stop(); }, 1000); ``` # TextItem Extends [**`Item`**](/project-and-items/item) The TextItem type allows you to create typography. Its functionality is inherited by different text item types such as `[PointText](PointText%20b65facc515f74b5ca4d27a8229b32789.md)`, and `AreaText` (coming soon). They each add a layer of functionality that is unique to their type, but share the underlying properties and functions that they inherit from TextItem. ## Properties * `content` The text contents of the text item. * Type: * `String` Example:Setting the content of a PointText item: ``` // Create a point-text item at {x: 30, y: 30}: var text = new PointText(new Point(30, 30)); text.fillColor = 'black'; // Set the content of the text item: text.content = 'Hello world'; ``` Example:Interactive example, move your mouse over the view below: ``` // Create a point-text item at {x: 30, y: 30}: var text = new PointText(new Point(30, 30)); text.fillColor = 'black'; text.content = 'Move your mouse over the view, to see its position'; function onMouseMove(event) { // Each time the mouse is moved, set the content of // the point text to describe the position of the mouse: text.content = 'Your position is: ' + event.point.toString(); } ``` ### Character Style * `fontFamily` The font-family to be used in text content. * Default: * `'sans-serif'` * Type: * `String` * `fontWeight` The font-weight to be used in text content. * Default: * `'normal'` * Type: * `String`⟋`Number` * `fontSize` The font size of text content, as a number in pixels, or as a string with optional units `'px'`, `'pt'` and `'em'`. * Default: * `10` * Type: * `Number`⟋`String` * `leading` The text leading of text content. * Default: * `fontSize * 1.2` * Type: * `Number`⟋`String` ### Paragraph Style * `justification` The justification of text paragraphs. * Values: * `'left'`, `'right'`, `'center'` * Default: * `'left'` * Type: * `String` ## Properties inherited from `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ``` var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ``` var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ``` var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ``` var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ``` // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ``` 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 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ``` // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ``` // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ``` 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(); path.parent = group; // 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ``` 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ``` var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ``` var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ``` // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ``` // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ``` // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ``` // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ``` // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ``` // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ``` // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ``` 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ``` var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ``` var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ``` var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ``` var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `Item` * `exportSVG([options])` Exports the item with its content and child items as an SVG DOM. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the item converted to an SVG node or a `String` depending on `option.asString` value * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ``` // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ``` // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ``` // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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 transformed * Returns: * `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: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ``` var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ``` // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ``` // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ``` 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ``` 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ``` function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ``` function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ``` 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ``` function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` # PointText Extends [**`Item`**](/project-and-items/item), [**`TextItem`**](/typography/textitem) A PointText item represents a piece of typography in your Paper.js project which starts from a certain point and extends by the amount of characters contained in it. ## Constructors * `PointText(point)` Creates a point text item * Parameters: * `point:` `Point` — the position where the text will start * Returns: * `PointText` — the newly created point text Example: ``` var text = new PointText(new Point(200, 50)); text.justification = 'center'; text.fillColor = 'black'; text.content = 'The contents of the point text'; ``` * `PointText(object)` Creates a point text item from the properties described by an object literal. * Parameters: * `object:` `Object` — an object containing properties describing the path’s attributes * Returns: * `PointText` — the newly created point text Example: ``` var text = new PointText({ point: [50, 50], content: 'The contents of the point text', fillColor: 'black', fontFamily: 'Courier New', fontWeight: 'bold', fontSize: 25 }); ``` ## Properties * `point` The PointText’s anchor point * Type: * `Point` ## Properties inherited from `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and add path to it as a child: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'red'; ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; ``` Example:Copying the style of another item: ``` var path = new Path.Circle({ center: [50, 50], radius: 30, fillColor: 'red' }); var path2 = new Path.Circle({ center: new Point(180, 50), radius: 20 }); // Copy the path style of path: path2.style = path.style; ``` Example:Applying the same style object to multiple items: ``` var myStyle = { fillColor: 'red', strokeColor: 'blue', strokeWidth: 4 }; var path = new Path.Circle({ center: [50, 50], radius: 30 }); path.style = myStyle; var path2 = new Path.Circle({ center: new Point(150, 50), radius: 20 }); path2.style = myStyle; ``` * `locked` Specifies whether the item is locked. When set to `true`, item interactions with the mouse are disabled. * Default: * `false` * Type: * `Boolean` Example: ``` var unlockedItem = new Path.Circle({ center: view.center - [35, 0], radius: 30, fillColor: 'springgreen', onMouseDown: function() { this.fillColor = Color.random(); } }); var lockedItem = new Path.Circle({ center: view.center + [35, 0], radius: 30, fillColor: 'crimson', locked: true, // This event won't be triggered because the item is locked. onMouseDown: function() { this.fillColor = Color.random(); } }); new PointText({ content: 'Click on both circles to see which one is locked.', point: view.center - [0, 35], justification: 'center' }); ``` * `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: ``` var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; ``` * `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: ``` // Create a white rectangle in the background // with the same dimensions as the view: var background = new Path.Rectangle(view.bounds); background.fillColor = 'white'; var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue' }); // Set the blend mode of circle2: circle2.blendMode = 'multiply'; ``` * `opacity` The opacity of the item as a value between `0` and `1`. * Default: * `1` * Type: * `Number` Example:Making an item 50% transparent: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'red' }); var circle2 = new Path.Circle({ center: new Point(120, 50), radius: 35, fillColor: 'blue', strokeColor: 'green', strokeWidth: 10 }); // Make circle2 50% transparent: circle2.opacity = 0.5; ``` * `selected` 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. * Default: * `false` * Type: * `Boolean` * See also: * `project.selectedItems` * `segment.selected` * `curve.selected` * `point.selected` Example:Selecting an item: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path ``` * `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: ``` 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 ``` ### 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’s `bounds` rectangle. * Type: * `Point` Example:Changing the position of a path: ``` // 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 circle.position += new Point(100, 50); ``` Example:Changing the x coordinate of an item's position: ``` // Create a circle at position { x: 20, y: 20 } var circle = new Path.Circle({ center: new Point(20, 20), radius: 10, fillColor: 'red' }); // Move the circle 100 points to the right circle.position.x += 100; ``` * `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 to `null`, meaning the `rectangle.center` of the item’s `bounds` 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 with `applyMatrix` set to `false`, 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 with `applyMatrix` set to `false`, 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 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.). * 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: ``` 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(); path.parent = group; // 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 ``` * `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, use `item.removeChildren`(). To add items to the children list, use `item.addChild(item)` or `item.insertChild(index, item)`. * Type: * Array of `Item` objects Example:Accessing items in the children array: ``` 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: group.children[0].fillColor = 'red'; ``` Example:Accessing children by name: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the name of the path: path.name = 'example'; // Create a group and move the path into it: var group = new Group(); group.addChild(path); // The path can be accessed by name: group.children['example'].fillColor = 'orange'; ``` Example:Passing an array of items to item.children: ``` var path = new Path.Circle({ center: [80, 50], radius: 35 }); var group = new Group(); group.children = [path]; // The path is the first child of the group: group.firstChild.fillColor = 'green'; ``` * `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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set its stroke color to RGB red: circle.strokeColor = new Color(1, 0, 0); ``` * `strokeWidth` The width of the stroke. * Type: * `Number` Example:Setting an item's stroke width: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35, strokeColor: 'red' }); // Set its stroke width to 10: circle.strokeWidth = 10; ``` * `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: ``` var line = new Path({ segments: [[80, 50], [420, 50]], strokeColor: 'black', strokeWidth: 20, selected: true }); // Set the stroke cap of the line to be round: line.strokeCap = 'round'; // Copy the path and set its stroke cap to be square: var line2 = line.clone(); line2.position.y += 50; line2.strokeCap = 'square'; // Make another copy and set its stroke cap to be butt: var line2 = line.clone(); line2.position.y += 100; line2.strokeCap = 'butt'; ``` * `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: ``` var path = new Path({ segments: [[80, 100], [120, 40], [160, 100]], strokeColor: 'black', strokeWidth: 20, // Select the path, in order to see where the stroke is formed: selected: true }); var path2 = path.clone(); path2.position.x += path2.bounds.width * 1.5; path2.strokeJoin = 'round'; var path3 = path2.clone(); path3.position.x += path3.bounds.width * 1.5; path3.strokeJoin = 'bevel'; ``` * `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: ``` var path = new Path.Circle({ center: [80, 50], radius: 40, strokeWidth: 2, strokeColor: 'black' }); // Set the dashed stroke to [10pt dash, 4pt gap]: path.dashArray = [10, 4]; ``` * `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 the `item.strokeWidth` of the path. The miterLimit imposes a limit on the ratio of the miter length to the `item.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: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 35: var circle = new Path.Circle({ center: [80, 50], radius: 35 }); // Set the fill color of the circle to RGB red: circle.fillColor = new Color(1, 0, 0); ``` * `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: ``` var circle = new Path.Circle({ center: [80, 50], radius: 35, fillColor: 'white', // Set the shadow color of the circle to RGB black: shadowColor: new Color(0, 0, 0), // Set the shadow blur radius to 12: shadowBlur: 12, // Offset the shadow by { x: 5, y: 5 } shadowOffset: new Point(5, 5) }); ``` * `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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `view.onFrame` Example:Creating an animation: ``` // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; path.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: this.rotate(3); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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 is pressed on the item, // set its fill color to red: path.onMouseDown = function(event) { this.fillColor = 'red'; } ``` Example:Press the mouse on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is pressed on the item, remove it: path.onMouseDown = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseDrag` Example:Press and drag the mouse on the blue circle to move it: ``` // Create a circle shaped path at the center of the view: var path = new Path.Circle({ center: view.center, radius: 50, fillColor: 'blue' }); // Install a drag event handler that moves the path along. path.onMouseDrag = function(event) { path.position += event.delta; } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseUp` Example:Release the mouse button over the circle shaped path, to make it red: ``` // 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 is released over the item, // set its fill color to red: path.onMouseUp = function(event) { this.fillColor = '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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onClick` Example:Click on the circle shaped path, to make it red: ``` // 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 is clicked on the item, // set its fill color to red: path.onClick = function(event) { this.fillColor = 'red'; } ``` Example:Click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse clicks on the item, remove it: path.onClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onDoubleClick` Example:Double click on the circle shaped path, to make it red: ``` // 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 is double clicked on the item, // set its fill color to red: path.onDoubleClick = function(event) { this.fillColor = 'red'; } ``` Example:Double click on the circle shaped paths to remove them: ``` // Loop 30 times: for (var i = 0; i < 30; i++) { // Create a circle shaped path at a random position // in the view: var path = new Path.Circle({ center: Point.random() * view.size, radius: 25, fillColor: 'black', strokeColor: 'white' }); // When the mouse is double clicked on the item, remove it: path.onDoubleClick = function(event) { this.remove(); } } ``` * `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 with `event.stopPropagation`() or by returning `false` from the handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseMove` Example:Move over the circle shaped path, to change its opacity: ``` // 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 moves on top of the item, set its opacity // to a random value between 0 and 1: path.onMouseMove = function(event) { this.opacity = Math.random(); } ``` * `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 with `event.stopPropagation`() or by returning `false` 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. ``` // 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: path.onMouseLeave = function(event) { this.fillColor = '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. ``` 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: path.onMouseLeave = leave; } ``` * `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 with `event.stopPropagation`() or by returning `false` 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: ``` // 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: path.onMouseLeave = function(event) { this.fillColor = 'red'; } ``` ## Methods inherited from `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 ``` var circle = new Path.Circle({ center: [80, 50], radius: 35 }); circle.set({ strokeColor: 'red', strokeWidth: 10, fillColor: 'black', selected: true }); ``` * `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 to `true`, 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: ``` var circle = new Path.Circle({ center: [50, 50], radius: 10, fillColor: 'red' }); // Make 20 copies of the circle: for (var i = 0; i < 20; i++) { var copy = circle.clone(); // Distribute the copies horizontally, so we can see them: copy.position.x += i * copy.bounds.width; } ``` * `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 from * `excludeMatrix:` `Boolean` — whether to exclude the transformation matrix when copying all attributes * `rasterize([resolution[, insert]])` Rasterizes the item into a newly created Raster object. The item itself is not removed after rasterization. * Parameters: * `resolution:` `Number` — the resolution of the raster in pixels per inch (DPI). If not specified, the value of `view.resolution` is used. — optional, default: `view.resolution` * `insert:` `Boolean` — specifies whether the raster should be inserted into the scene graph. When set to `true`, it is inserted above the original — optional, default: `true` * Returns: * `Raster` — the newly created raster item Example:Rasterizing an item: ``` var circle = new Path.Circle({ center: [50, 50], radius: 5, fillColor: 'red' }); // Create a rasterized version of the path: var raster = circle.rasterize(); // Move it 100pt to the right: raster.position.x += 100; // Scale the path and the raster by 300%, so we can compare them: circle.scale(5); raster.scale(5); ``` ### Geometric Tests * `contains(point)` Checks whether the item’s geometry contains the given point. * Parameters: * `point:` `Point` — the point to check for * Returns: * `Boolean` Example:Click within and outside the star below Create a star shaped path: ``` var path = new Path.Star({ center: [50, 50], points: 12, radius1: 20, radius2: 40, fillColor: 'black' }); // Whenever the user presses the mouse: function onMouseDown(event) { // If the position of the mouse is within the path, // set its fill color to red, otherwise set it to // black: if (path.contains(event.point)) { path.fillColor = 'red'; } else { path.fillColor = 'black'; } } ``` * `isInside(rect)` * Parameters: * `rect:` `Rectangle` — the rectangle to check against * Returns: * `Boolean` * `intersects(item)` * Parameters: * `item:` `Item` — the item to check against * Returns: * `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` or `Layer`) 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`.hitTolerance * `options.class: Function` — only hit-test against a specific item class, or any of its sub-classes, by providing the constructor function against which an `instanceof` 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: Return `true` to return the result, `false` to keep searching * `options.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 for `segment.point` of `Path` items — default: `true` * `options.curves: Boolean` — hit-test the curves of path items, without taking the stroke color or width into account * `options.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 items * `options.position: Boolean` — hit-test the `item.position` of of items, which depends on the setting of `item.pivot` * `options.center: Boolean` — hit-test the `rectangle.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 have `Item#guide` set to `true` * `options.selected: Boolean` — only hit selected items * 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: * `HitResult` — a hit result object describing what exactly was hit or `null` if nothing was hit * `hitTestAll(point[, options])` Performs a hit-test on the item and its children (if it is a `Group` or `Layer`) 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 or `null` if nothing was hit * See 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 against * Returns: * `Boolean` — `true` if the item matches all the criteria, `false` otherwise * See 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 against * `compare:` `Object` — the value, function or regular expression to compare against * Returns: * `Boolean` — `true` if the item matches the state, `false` otherwise * See 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` or `options.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 the `options` object * `options.class: Function` — the constructor function of the item type to match against * `options.inside: Rectangle` — the rectangle in which the items need to be fully contained * `options.overlapping: Rectangle` — the rectangle with which the items need to at least partly overlap * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Array of Item` objects — the list of matching descendant items * See 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`. See `project.getItems(match)` for a selection of illustrated examples. * Parameters: * `options:` `Object`⟋`Function` — the criteria to match against * Returns: * `Item` — the first descendant item matching the given criteria * See 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 a `Object` or a `String` — default: `true` * `options.precision: Number` — the amount of fractional digits in numbers used in JSON data — default: `5` * Parameters: * `options:` `Object` — the serialization options — optional * Returns: * `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 from * Returns: * `Item` * `exportSVG([options])` Exports the item with its content and child items as an SVG DOM. * Options: * `options.bounds: String`⟋`Rectangle` — the bounds of the area to export, either as a string (`‘view’`, `content’`), or a `Rectangle` object: `'view'` uses the view bounds, `'content'` uses the stroke bounds of all content — default: `‘view’` * `options.matrix: Matrix` — the matrix with which to transform the exported content: If `options.bounds` is set to `'view'`, `paper.view.matrix` is used, for all other settings of `options.bounds` the identity matrix is used. — default: `paper.view.matrix` * `options.asString: Boolean` — whether a SVG node or a `String` is to be returned — default: `false` * `options.precision: Number` — the amount of fractional digits in numbers used in SVG data — default: `5` * `options.matchShapes: Boolean` — whether path items should tried to be converted to SVG shape items (rect, circle, ellipse, line, polyline, polygon), if their geometries match — default: `false` * `options.embedImages: Boolean` — 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: `true` * Parameters: * `options:` `Object` — the export options — optional * Returns: * `SVGElement`⟋`String` — the item converted to an SVG node or a `String` depending on `option.asString` value * `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 converted `item` and the original `svg` 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 that `importSVG()` 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`.applyMatrix * Parameters: * `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 — optional * Returns: * `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 converted `item` and the original `svg` 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 child * Returns: * `Item` — the added item, or `null` 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 item * `item:` `Item` — the item to be inserted as a child * Returns: * `Item` — the inserted item, or `null` 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 of `Item` objects — the items to be added as children * Returns: * `Array of Item` objects — the added items, or `null` 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 of `Item` objects — the items to be appended as children * Returns: * `Array of Item` objects — the inserted items, or `null` if inserted was not possible * `insertAbove(item)` Inserts this item above the specified item. * Parameters: * `item:` `Item` — the item above which it should be inserted * Returns: * `Item` — the inserted item, or `null` if inserting was not possible * `insertBelow(item)` Inserts this item below the specified item. * Parameters: * `item:` `Item` — the item below which it should be inserted * Returns: * `Item` — the inserted item, or `null` 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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to add the item to * Returns: * `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 a `Project`. * Parameters: * `owner:` `Project`⟋`Layer`⟋`Group`⟋`CompoundPath` — the item or project to copy the item to * Returns: * `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 item * Returns: * `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 the `end` index from the parent’s `children` array. * Parameters: * `start:` `Number` — the beginning index, inclusive * `end:` `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, a `TextItem` with no text content and a `Path` 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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 against * Returns: * `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 angle * `center:` `Point` — optional, default: `item.position` * See also: * `matrix.rotate(angle[, center])` Example:Rotating an item: ``` // Create a rectangle shaped path with its top left // point at {x: 80, y: 25} and a size of {width: 50, height: 50}: var path = new Path.Rectangle(new Point(80, 25), new Size(50, 50)); path.fillColor = 'black'; // Rotate the path by 30 degrees: path.rotate(30); ``` Example:Rotating an item around a specific point: ``` // Create a rectangle shaped path with its top left // point at {x: 175, y: 50} and a size of {width: 100, height: 100}: var topLeft = new Point(175, 50); var size = new Size(100, 100); var path = new Path.Rectangle(topLeft, size); path.fillColor = 'black'; // Draw a circle shaped path in the center of the view, // to show the rotation point: var circle = new Path.Circle({ center: view.center, radius: 5, fillColor: 'white' }); // Each frame rotate the path 3 degrees around the center point // of the view: function onFrame(event) { path.rotate(3, view.center); } ``` * `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 factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item from its center point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path by 150% from its center point circle.scale(1.5); ``` Example:Scaling an item from a specific point: ``` // Create a circle shaped path at { x: 80, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [80, 50], radius: 20, fillColor: 'red' }); // Scale the path 150% from its bottom left corner circle.scale(1.5, circle.bounds.bottomLeft); ``` * `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 factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `item.position` Example:Scaling an item horizontally by 300%: ``` // Create a circle shaped path at { x: 100, y: 50 } // with a radius of 20: var circle = new Path.Circle({ center: [100, 50], radius: 20, fillColor: 'red' }); // Scale the path horizontally by 300% circle.scale(3, 1); ``` * `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 point * `center:` `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 factor * `ver:` `Number` — the vertical shear factor * `center:` `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 degrees * `center:` `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 degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `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 transformed * Returns: * `Point` — the transformed point as a new instance * `localToGlobal(point)` * `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 transformed * Returns: * `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 transformed * Returns: * `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: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds); ``` Example:Fitting an item to the bounding rectangle of another item's bounding rectangle with the fill parameter set to true: ``` // 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 rectangular path: circlePath.fitBounds(path.bounds, true); ``` Example:Fitting an item to the bounding rectangle of the view ``` var path = new Path.Circle({ center: [80, 50], radius: 30, fillColor: 'red' }); // Fit the path to the bounding rectangle of the view: path.fitBounds(view.bounds); ``` ### 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 a `MouseEvent` or `Event` object as its sole argument * 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. ``` // 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: path.on('mouseleave', function() { this.fillColor = 'black'; }); ``` * `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. ``` // 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: path.on({ mouseenter: function(event) { this.fillColor = 'red'; }, mouseleave: function(event) { this.fillColor = '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 black. ``` 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: path.on(pathHandlers); } ``` * `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 detached * Returns: * `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 event * Returns: * `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 next `tool.onMouseMove` event is fired. * `options.drag: undefined` — {Boolena) remove the item when the next `tool.onMouseDrag` event is fired. * `options.down: undefined` — {Boolean) remove the item when the next `tool.onMouseDown` event is fired. * `options.up: undefined` — {Boolean) remove the item when the next `tool.onMouseUp` event is fired. * Parameters: * `options:` `Object` Example:Click and drag below: ``` 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: path.removeOn({ drag: true, down: true }); } ``` * `removeOnMove()` Removes the item when the next `tool.onMouseMove` event is fired. Example:Move your mouse below: ``` function onMouseMove(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' }); // On the next move event, automatically remove the path: path.removeOnMove(); } ``` * `removeOnDown()` Removes the item when the next `tool.onMouseDown` event is fired. Example:Click a few times below: ``` function onMouseDown(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, next time the mouse is pressed: path.removeOnDown(); } ``` * `removeOnDrag()` Removes the item when the next `tool.onMouseDrag` event is fired. Example:Click and drag below: ``` 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' }); // On the next drag event, automatically remove the path: path.removeOnDrag(); } ``` * `removeOnUp()` Removes the item when the next `tool.onMouseUp` event is fired. Example:Click a few times below: ``` function onMouseDown(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, when the mouse is released: path.removeOnUp(); } ``` ### Tweening Functions * `tween(from, to, options)` Tween item between two states. * Options: * `options.duration: Number` — the duration of the tweening * `options.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 tweening * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` Example:Tween fillColor: ```jsx var path = new Path.Circle({ radius: view.bounds.height * 0.4, center: view.center }); path.tween( { fillColor: 'blue' }, { fillColor: 'red' }, 3000 ); ``` Example:Tween rotation: ```jsx var path = new Shape.Rectangle({ fillColor: 'red', center: [50, view.center.y], size: [60, 60] }); path.tween({ rotation: 180, 'position.x': view.bounds.width - 50, 'fillColor.hue': '+= 90' }, { easing: 'easeInOutCubic', duration: 2000 }); ``` * `tween(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween a nested property with relative values ```jsx var path = new Path.Rectangle({ size: [100, 100], position: view.center, fillColor: 'red', }); var delta = { x: path.bounds.width / 2, y: 0 }; path.tween({ 'segments[1].point': ['+=', delta], 'segments[2].point.x': '-= 50' }, 3000); ``` * `tween(options)` Tween item. * Parameters: * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Start an empty tween and just use the update callback: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center, }); var pathFrom = path.clone({ insert: false }) var pathTo = new Path.Rectangle({ position: view.center, rectangle: path.bounds, insert: false }); path.tween(2000).onUpdate = function(event) { path.interpolate(pathFrom, pathTo, event.factor) }; ``` * `tweenTo(to, options)` Tween item to a state. * Parameters: * `to:` `Object` — the state at the end of the tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `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 tweening * `options:` `Object`⟋`Number` — the options or the duration * Returns: * `Tween` * See also: * `item.tween(from, to, options)` Example:Tween fillColor from red to the path's initial fillColor: ```jsx var path = new Path.Circle({ fillColor: 'blue', radius: view.bounds.height * 0.4, center: view.center }); path.tweenFrom({ fillColor: 'red' }, { duration: 1000 }); ``` ## Properties inherited from `TextItem` * `content` The text contents of the text item. * Type: * `String` Example:Setting the content of a PointText item: ``` // Create a point-text item at {x: 30, y: 30}: var text = new PointText(new Point(30, 30)); text.fillColor = 'black'; // Set the content of the text item: text.content = 'Hello world'; ``` Example:Interactive example, move your mouse over the view below: ``` // Create a point-text item at {x: 30, y: 30}: var text = new PointText(new Point(30, 30)); text.fillColor = 'black'; text.content = 'Move your mouse over the view, to see its position'; function onMouseMove(event) { // Each time the mouse is moved, set the content of // the point text to describe the position of the mouse: text.content = 'Your position is: ' + event.point.toString(); } ``` ### Character Style * `fontFamily` The font-family to be used in text content. * Default: * `'sans-serif'` * Type: * `String` * `fontWeight` The font-weight to be used in text content. * Default: * `'normal'` * Type: * `String`⟋`Number` * `fontSize` The font size of text content, as a number in pixels, or as a string with optional units `'px'`, `'pt'` and `'em'`. * Default: * `10` * Type: * `Number`⟋`String` * `leading` The text leading of text content. * Default: * `fontSize * 1.2` * Type: * `Number`⟋`String` ### Paragraph Style * `justification` The justification of text paragraphs. * Values: * `'left'`, `'right'`, `'center'` * Default: * `'left'` * Type: * `String` # View The View object wraps an HTML element and handles drawing and user interaction through mouse and keyboard for it. It offer means to scroll the view, find the currently visible bounds in project coordinates, or the center, both useful for constructing artwork that should appear centered on screen. ## Properties * `autoUpdate` Controls whether the view is automatically updated in the next animation frame on changes, or whether you prefer to manually call `update`() or `requestUpdate`() after changes. Note that this is `true` by default, except for Node.js, where manual updates make more sense. * Type: * `Boolean` * `element` The underlying native element. Read only. * Type: * `HTMLCanvasElement` * `pixelRatio` The ratio between physical pixels and device-independent pixels (DIPs) of the underlying canvas / device. It is `1` for normal displays, and `2` or more for high-resolution displays. Read only. * Type: * `Number` * `resolution` The resoltuion of the underlying canvas / device in pixel per inch (DPI). It is `72` for normal displays, and `144` for high-resolution displays with a pixel-ratio of `2`. Read only. * Type: * `Number` * `viewSize` The size of the view. Changing the view’s size will resize it’s underlying element. * Type: * `Size` * `bounds` The bounds of the currently visible area in project coordinates. Read only. * Type: * `Rectangle` * `size` The size of the visible area in project coordinates. Read only. * Type: * `Size` * `center` The center of the visible area in project coordinates. * Type: * `Point` * `zoom` The view’s zoom factor by which the project coordinates are magnified. * Type: * `Number` * See also: * `scaling` * `rotation` The current rotation angle of the view, as described by its `matrix`. * Type: * `Number` * `scaling` The current scale factor of the view, as described by its `matrix`. * Type: * `Point` * See also: * `zoom` * `matrix` The view’s transformation matrix, defining the view onto the project’s contents (position, zoom level, rotation, etc). * Type: * `Matrix` ### Event Handlers * `onFrame` 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 fired * `event.time: Number` — the total amount of time passed since the first frame event in seconds * `event.delta: Number` — the time passed in seconds since the last frame event * See also: * `item.onFrame` Example:Creating an animation: ```jsx // Create a rectangle shaped path with its top left point at: // {x: 50, y: 25} and a size of {width: 50, height: 50} var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; view.onFrame = function(event) { // Every frame, rotate the path by 3 degrees: path.rotate(3); } ``` * `onResize` Handler function that is called whenever a view is resized. * Type: * `Function`⟋`null` Example:Repositioning items when a view is resized: ```jsx // Create a circle shaped path in the center of the view: var path = new Path.Circle(view.bounds.center, 30); path.fillColor = 'red'; view.onResize = function(event) { // Whenever the view is resized, move the path to its center: path.position = view.center; } ``` * `onMouseDown` The function to be called when the mouse button is pushed down on the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onMouseDown` * `onMouseDrag` The function to be called when the mouse position changes while the mouse is being dragged over the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onMouseDrag` * `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. * Type: * `Function`⟋`null` * See also: * `item.onMouseUp` * `onClick` The function to be called when the mouse clicks on the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onClick` * `onDoubleClick` The function to be called when the mouse double clicks on the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onDoubleClick` * `onMouseMove` The function to be called repeatedly while the mouse moves over the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onMouseMove` * `onMouseEnter` The function to be called when the mouse moves over the view. This function will only be called again, once the mouse moved outside of the view 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, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `item.onMouseEnter` * `onMouseLeave` The function to be called when the mouse moves out of the view. The function receives a `MouseEvent` object which contains information about the mouse event. Note that such mouse events bubble up the scene graph hierarchy, reaching the view at the end, unless they are stopped before with `event.stopPropagation`() or by returning `false` from a handler. * Type: * `Function`⟋`null` * See also: * `view.onMouseLeave` ## Methods * `remove()` Removes this view from the project and frees the associated element. * `update()` Updates the view if there are changes. Note that when using built-in event hanlders for interaction, animation and load events, this method is invoked for you automatically at the end. * Returns: * `Boolean` — `true` if the view was updated, `false` otherwise * `requestUpdate()` Requests an update of the view if there are changes through the browser’s requestAnimationFrame() mechanism for smooth animation. Note that when using built-in event handlers for interaction, animation and load events, updates are automatically invoked for you automatically at the end. * `play()` Makes all animation play by adding the view to the request animation loop. * `pause()` Makes all animation pause by removing the view from the request animation loop. * `isVisible()` Checks whether the view is currently visible within the current browser viewport. * Returns: * `Boolean` — `true` if the view is visible, `false` otherwise * `isInserted()` Checks whether the view is inserted into the browser DOM. * Returns: * `Boolean` — `true` if the view is inserted, `false` otherwise ### Transform Functions * `translate(delta)` Translates (scrolls) the view by the given offset vector. * Parameters: * `delta:` `Point` — the offset to translate the view by * `rotate(angle[, center])` Rotates the view by a given angle around the given center point. Angles are oriented clockwise and measured in degrees. * Parameters: * `angle:` `Number` — the rotation angle * `center:` `Point` — optional, default: `view.center` * See also: * `matrix.rotate(angle[, center])` * `scale(scale[, center])` Scales the view by the given value from its center point, or optionally from a supplied point. * Parameters: * `scale:` `Number` — the scale factor * `center:` `Point` — optional, default: `view.center` * `scale(hor, ver[, center])` Scales the view by the given values from its center point, or optionally from a supplied point. * Parameters: * `hor:` `Number` — the horizontal scale factor * `ver:` `Number` — the vertical scale factor * `center:` `Point` — optional, default: `view.center` * `shear(shear[, center])` Shears the view 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 point * `center:` `Point` — optional, default: `view.center` * See also: * `matrix.shear(shear[, center])` * `shear(hor, ver[, center])` Shears the view by the given values from its center point, or optionally by a supplied point. * Parameters: * `hor:` `Number` — the horizontal shear factor * `ver:` `Number` — the vertical shear factor * `center:` `Point` — optional, default: `view.center` * See also: * `matrix.shear(hor, ver[, center])` * `skew(skew[, center])` Skews the view by the given angles from its center point, or optionally by a supplied point. * Parameters: * `skew:` `Point` — the horizontal and vertical skew angles in degrees * `center:` `Point` — optional, default: `view.center` * See also: * `matrix.shear(skew[, center])` * `skew(hor, ver[, center])` Skews the view by the given angles from its center point, or optionally by a supplied point. * Parameters: * `hor:` `Number` — the horizontal skew angle in degrees * `ver:` `Number` — the vertical sskew angle in degrees * `center:` `Point` — optional, default: `view.center` * See also: * `matrix.shear(hor, ver[, center])` * `transform(matrix)` Transform the view. * Parameters: * `matrix:` `Matrix` — the matrix by which the view shall be transformed * `projectToView(point)` Converts the passed point from project coordinate space to view coordinate space, which is measured in browser pixels in relation to the position of the view element. * Parameters: * `point:` `Point` — the point in project coordinates to be converted * Returns: * `Point` — the point converted into view coordinates * `viewToProject(point)` Converts the passed point from view coordinate space to project coordinate space. * Parameters: * `point:` `Point` — the point in view coordinates to be converted * Returns: * `Point` — the point converted into project coordinates * `getEventPoint(event)` Determines and returns the event location in project coordinate space. * Parameters: * `event:` `Event` — the native event object for which to determine the location. * Returns: * `Point` — the event point in project coordinates. ### Event Handling * `on(type, function)` Attach an event handler to the view. * Parameters: * `type:` `String` — the type of event: `‘frame’`, `‘resize’`, `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘click’`, `‘doubleclick’`, `‘mousemove’`, `‘mouseenter’`, `‘mouseleave’` * `function:` `Function` — the function to be called when the event occurs, receiving a `MouseEvent` or `Event` object as its sole argument * Returns: * `View` — this view itself, so calls can be chained Example:Create a rectangle shaped path with its top left point at: {x: 50, y: 25} and a size of {width: 50, height: 50} ```jsx var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; var frameHandler = function(event) { // Every frame, rotate the path by 3 degrees: path.rotate(3); }; view.on('frame', frameHandler); ``` * `on(param)` Attach one or more event handlers to the view. * Parameters: * `param:` `Object` — an object literal containing one or more of the following properties: `frame`, `resize` * Returns: * `View` — this view itself, so calls can be chained Example:Create a rectangle shaped path with its top left point at: {x: 50, y: 25} and a size of {width: 50, height: 50} ```jsx var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; var frameHandler = function(event) { // Every frame, rotate the path by 3 degrees: path.rotate(3); }; view.on({ frame: frameHandler }); ``` * `off(type, function)` Detach an event handler from the view. * Parameters: * `type:` `String` — the event type: `‘frame’`, `‘resize’`, `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘click’`, `‘doubleclick’`, `‘mousemove’`, `‘mouseenter’`, `‘mouseleave’` * `function:` `Function` — the function to be detached * Returns: * `View` — this view itself, so calls can be chained Example:Create a rectangle shaped path with its top left point at: {x: 50, y: 25} and a size of {width: 50, height: 50} ```jsx var path = new Path.Rectangle(new Point(50, 25), new Size(50, 50)); path.fillColor = 'black'; var frameHandler = function(event) { // Every frame, rotate the path by 3 degrees: path.rotate(3); }; view.on({ frame: frameHandler }); // When the user presses the mouse, // detach the frame handler from the view: function onMouseDown(event) { view.off('frame'); } ``` * `off(param)` Detach one or more event handlers from the view. * Parameters: * `param:` `Object` — an object literal containing one or more of the following properties: `frame`, `resize` * Returns: * `View` — this view itself, so calls can be chained * `emit(type, event)` Emit an event on the view. * Parameters: * `type:` `String` — the event type: `‘frame’`, `‘resize’`, `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘click’`, `‘doubleclick’`, `‘mousemove’`, `‘mouseenter’`, `‘mouseleave’` * `event:` `Object` — an object literal containing properties describing the event * Returns: * `Boolean` — `true` if the event had listeners, `false` otherwise * `responds(type)` Check if the view has one or more event handlers of the specified type. * Parameters: * `type:` `String` — the event type: `‘frame’`, `‘resize’`, `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘click’`, `‘doubleclick’`, `‘mousemove’`, `‘mouseenter’`, `‘mouseleave’` * Returns: * `Boolean` — `true` if the view has one or more event handlers of the specified type, `false` otherwise # Event The Event object is the base class for any of the other event types, such as `[MouseEvent](MouseEvent%2089db2df80d0b44ae9a8ffe9f3f4b051c.md)`, `[ToolEvent](ToolEvent%20fb046e93f06f459c81050c846073e385.md)` and `[KeyEvent](KeyEvent%20fea979a99b97464cab44d0ae91000dff.md)`. ## Properties * `timeStamp` The time at which the event was created, in milliseconds since the epoch. Read only. * Type: * `Number` * `modifiers` The current state of the keyboard modifiers. Read only. * Type: * `object` * See also: * `Key.modifiers` ## Methods * `preventDefault()` Cancels the event if it is cancelable, without stopping further propagation of the event. * `stopPropagation()` Prevents further propagation of the current event. * `stop()` Cancels the event if it is cancelable, and stops stopping further propagation of the event. This is has the same effect as calling both `stopPropagation`() and `preventDefault`(). Any handler can also return `false` to indicate that `stop()` should be called right after. # MouseEvent Extends **`[Event](Event%20701eceeb8e6f49ec8a30675a8da31f48.md)`** The MouseEvent object is received by the `[Item](Item%20eab4980134ff44238bc91e6d4a28d6f9.md)`’s mouse event handlers `item.onMouseDown`, `item.onMouseDrag`, `item.onMouseMove`, `item.onMouseUp`, `item.onClick`, `item.onDoubleClick`, `item.onMouseEnter` and `item.onMouseLeave`. The MouseEvent object is the only parameter passed to these functions and contains information about the mouse event. ## Properties * `type` The type of mouse event. * Values: * `'mousedown'`, `'mouseup'`, `'mousedrag'`, `'click'`, `'doubleclick'`, `'mousemove'`, `'mouseenter'`, `'mouseleave'` * Type: * `String` * `point` The position of the mouse in project coordinates when the event was fired. * Type: * `Point` * `target` The item that dispatched the event. It is different from `currentTarget` when the event handler is called during the bubbling phase of the event. * Type: * `Item` * `currentTarget` The current target for the event, as the event traverses the scene graph. It always refers to the element the event handler has been attached to as opposed to `target` which identifies the element on which the event occurred. * Type: * `Item` * `delta` * Type: * `Point` ## Methods * `toString()` * Returns: * `String` — a string representation of the mouse event ## Properties inherited from `Event` * `timeStamp` The time at which the event was created, in milliseconds since the epoch. Read only. * Type: * `Number` * `modifiers` The current state of the keyboard modifiers. Read only. * Type: * `object` * See also: * `Key.modifiers` ## Methods inherited from `Event` * `preventDefault()` Cancels the event if it is cancelable, without stopping further propagation of the event. * `stopPropagation()` Prevents further propagation of the current event. * `stop()` Cancels the event if it is cancelable, and stops stopping further propagation of the event. This is has the same effect as calling both `stopPropagation`() and `preventDefault`(). Any handler can also return `false` to indicate that `stop()` should be called right after. # Tool The Tool object refers to a script that the user can interact with by using the mouse and keyboard and can be accessed through the global `tool` variable. All its properties are also available in the paper scope. The global `tool` variable only exists in scripts that contain mouse handler functions (`onMouseMove`, `onMouseDown`, `onMouseDrag`, `onMouseUp`) or a keyboard handler function (`onKeyDown`, `onKeyUp`). Example: ```jsx var path; // Only execute onMouseDrag when the mouse // has moved at least 10 points: tool.minDistance = 10; tool.onMouseDown = function(event) { // Create a new path every time the mouse is clicked path = new Path(); path.add(event.point); path.strokeColor = 'black'; } tool.onMouseDrag = function(event) { // Add a point to the path every time the mouse is dragged path.add(event.point); } ``` ## Properties * `minDistance` The minimum distance the mouse has to drag before firing the onMouseDrag event, since the last onMouseDrag event. * Type: * `Number` * `maxDistance` The maximum distance the mouse has to drag before firing the onMouseDrag event, since the last onMouseDrag event. * Type: * `Number` * `fixedDistance` * Type: * `Number` ### Mouse Event Handlers * `onMouseDown` The function to be called when the mouse button is pushed down. The function receives a `ToolEvent` object which contains information about the tool event. * Type: * `Function`⟋`null` Example:Creating circle shaped paths where the user presses the mouse button: ```jsx tool.onMouseDown = function(event) { // Create a new circle shaped path with a radius of 10 // at the position of the mouse (event.point): var path = new Path.Circle({ center: event.point, radius: 10, fillColor: 'black' }); } ``` * `onMouseDrag` The function to be called when the mouse position changes while the mouse is being dragged. The function receives a `ToolEvent` object which contains information about the tool event. * Type: * `Function`⟋`null` Example:Draw a line by adding a segment to a path on every mouse drag event: ```jsx // Create an empty path: var path = new Path({ strokeColor: 'black' }); tool.onMouseDrag = function(event) { // Add a segment to the path at the position of the mouse: path.add(event.point); } ``` * `onMouseMove` The function to be called the mouse moves within the project view. The function receives a `ToolEvent` object which contains information about the tool event. * Type: * `Function`⟋`null` Example:Moving a path to the position of the mouse: ```jsx // Create a circle shaped path with a radius of 10 at {x: 0, y: 0}: var path = new Path.Circle({ center: [0, 0], radius: 10, fillColor: 'black' }); tool.onMouseMove = function(event) { // Whenever the user moves the mouse, move the path // to that position: path.position = event.point; } ``` * `onMouseUp` The function to be called when the mouse button is released. The function receives a `ToolEvent` object which contains information about the tool event. * Type: * `Function`⟋`null` Example:Creating circle shaped paths where the user releases the mouse: ```jsx tool.onMouseUp = function(event) { // Create a new circle shaped path with a radius of 10 // at the position of the mouse (event.point): var path = new Path.Circle({ center: event.point, radius: 10, fillColor: 'black' }); } ``` ### Keyboard Event Handlers * `onKeyDown` The function to be called when the user presses a key on the keyboard. The function receives a `KeyEvent` object which contains information about the keyboard event. If the function returns `false`, the keyboard event will be prevented from bubbling up. This can be used for example to stop the window from scrolling, when you need the user to interact with arrow keys. * Type: * `Function`⟋`null` Example:Scaling a path whenever the user presses the space bar: ```jsx // Create a circle shaped path: var path = new Path.Circle({ center: new Point(50, 50), radius: 30, fillColor: 'red' }); tool.onKeyDown = function(event) { if (event.key == 'space') { // Scale the path by 110%: path.scale(1.1); // Prevent the key event from bubbling return false; } } ``` * `onKeyUp` The function to be called when the user releases a key on the keyboard. The function receives a `KeyEvent` object which contains information about the keyboard event. If the function returns `false`, the keyboard event will be prevented from bubbling up. This can be used for example to stop the window from scrolling, when you need the user to interact with arrow keys. * Type: * `Function`⟋`null` Example: ```jsx tool.onKeyUp = function(event) { if (event.key == 'space') { console.log('The spacebar was released!'); } } ``` ## Methods * `activate()` Activates this tool, meaning `paperScope.tool` will point to it and it will be the one that receives tool events. * `remove()` Removes this tool from the `paperScope.tools` list. ### Event Handling * `on(type, function)` Attach an event handler to the tool. * Parameters: * `type:` `String` — the event type: `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘mousemove’`, `‘keydown’`, `‘keyup’` * `function:` `Function` — the function to be called when the event occurs, receiving a `ToolEvent` object as its sole argument * Returns: * `Tool` — this tool itself, so calls can be chained * `on(param)` Attach one or more event handlers to the tool. * Parameters: * `param:` `Object` — an object literal containing one or more of the following properties: `mousedown`, `mouseup`, `mousedrag`, `mousemove`, `keydown`, `keyup` * Returns: * `Tool` — this tool itself, so calls can be chained * `off(type, function)` Detach an event handler from the tool. * Parameters: * `type:` `String` — the event type: `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘mousemove’`, `‘keydown’`, `‘keyup’` * `function:` `Function` — the function to be detached * Returns: * `Tool` — this tool itself, so calls can be chained * `off(param)` Detach one or more event handlers from the tool. * Parameters: * `param:` `Object` — an object literal containing one or more of the following properties: `mousedown`, `mouseup`, `mousedrag`, `mousemove`, `keydown`, `keyup` * Returns: * `Tool` — this tool itself, so calls can be chained * `emit(type, event)` Emit an event on the tool. * Parameters: * `type:` `String` — the event type: `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘mousemove’`, `‘keydown’`, `‘keyup’` * `event:` `Object` — an object literal containing properties describing the event * Returns: * `Boolean` — `true` if the event had listeners, `false` otherwise * `responds(type)` Check if the tool has one or more event handlers of the specified type. * Parameters: * `type:` `String` — the event type: `‘mousedown’`, `‘mouseup’`, `‘mousedrag’`, `‘mousemove’`, `‘keydown’`, `‘keyup’` * Returns: * `Boolean` — `true` if the tool has one or more event handlers of the specified type, `false` otherwise # ToolEvent Extends `[Event](Event%20701eceeb8e6f49ec8a30675a8da31f48.md)` ToolEvent The ToolEvent object is received by the `Tool`’s mouse event handlers `tool.onMouseDown`, `tool.onMouseDrag`, `tool.onMouseMove` and `tool.onMouseUp`. The ToolEvent object is the only parameter passed to these functions and contains information about the mouse event. ## Properties * `type` The type of tool event. * Values: * `'mousedown'`, `'mouseup'`, `'mousemove'`, `'mousedrag'` * Type: * `String` * `point` The position of the mouse in project coordinates when the event was fired. * Type: * `Point` Example: ```jsx function onMouseDrag(event) { // the position of the mouse when it is dragged console.log(event.point); } function onMouseUp(event) { // the position of the mouse when it is released console.log(event.point); } ``` * `lastPoint` The position of the mouse in project coordinates when the previous event was fired. * Type: * `Point` * `downPoint` The position of the mouse in project coordinates when the mouse button was last clicked. * Type: * `Point` * `middlePoint` The point in the middle between `lastPoint` and `point`. This is a useful position to use when creating artwork based on the moving direction of the mouse, as returned by `delta`. * Type: * `Point` * `delta` The difference between the current position and the last position of the mouse when the event was fired. In case of the mouseup event, the difference to the mousedown position is returned. * Type: * `Point` * `count` The number of times the mouse event was fired. * Type: * `Number` * `item` The item at the position of the mouse (if any). If the item is contained within one or more `Group` or `CompoundPath` items, the most top level group or compound path that it is contained within is returned. * Type: * `Item` ## Methods * `toString()` * Returns: * `String` — a string representation of the tool event ## Properties inherited from `Event` * `timeStamp` The time at which the event was created, in milliseconds since the epoch. Read only. * Type: * `Number` * `modifiers` The current state of the keyboard modifiers. Read only. * Type: * `object` * See also: * `Key.modifiers` ## Methods inherited from `Event` * `preventDefault()` Cancels the event if it is cancelable, without stopping further propagation of the event. * `stopPropagation()` Prevents further propagation of the current event. * `stop()` Cancels the event if it is cancelable, and stops stopping further propagation of the event. This is has the same effect as calling both `stopPropagation`() and `preventDefault`(). Any handler can also return `false` to indicate that `stop()` should be called right after. # Key ## Static Properties * `Key.modifiers` The current state of the keyboard modifiers. * Type: * `Object` * Options: * `modifiers.shift: Boolean` — `true` if the shift key is pressed, `false` otherwise. * `modifiers.control: Boolean` — `true` if the control key is pressed, `false` otherwise. * `modifiers.alt: Boolean` — `true` if the alt/option key is pressed, `false` otherwise. * `modifiers.meta: Boolean` — `true` if the meta/windows/command key is pressed, `false` otherwise. * `modifiers.capsLock: Boolean` — `true` if the caps-lock key is active, `false` otherwise. * `modifiers.space: Boolean` — `true` if the space key is pressed, `false` otherwise. * `modifiers.option: Boolean` — `true` if the alt/option key is pressed, `false` otherwise. This is the same as `modifiers.alt` * `modifiers.command: Boolean` — `true` if the meta key is pressed on Mac, or the control key is pressed on Windows and Linux, `false` otherwise. ## Static Methods * `Key.isDown(key)` Checks whether the specified key is pressed. * Parameters: * `key:` `String` — any character or special key descriptor: `‘enter’`, `‘space’`, `‘shift’`, `‘control’`, `‘alt’`, `‘meta’`, `‘caps-lock’`, `‘left’`, `‘up’`, `‘right’`, `‘down’`, `‘escape’`, `‘delete’`, … * Returns: * `Boolean` — `true` if the key is pressed, `false` otherwise Example:Whenever the user clicks, create a circle shaped path. If the 'a' key is pressed, fill it with red, otherwise fill it with blue: ```jsx function onMouseDown(event) { var path = new Path.Circle(event.point, 10); if (Key.isDown('a')) { path.fillColor = 'red'; } else { path.fillColor = 'blue'; } } ``` # KeyEvent Extends **`[Event](Event%20701eceeb8e6f49ec8a30675a8da31f48.md)`** The KeyEvent object is received by the `Tool`’s keyboard handlers `tool.onKeyDown`, `tool.onKeyUp`. The KeyEvent object is the only parameter passed to these functions and contains information about the keyboard event. ## Properties * `type` The type of mouse event. * Values: * `'keydown'`, `'keyup'` * Type: * `String` * `character` The character representation of the key that caused this key event, taking into account the current key-modifiers (e.g. shift, control, caps-lock, etc.) * Type: * `String` * `key` The key that caused this key event, either as a lower-case character or special key descriptor. * Values: * `'enter'`, `'space'`, `'shift'`, `'control'`, `'alt'`, `'meta'`, `'caps-lock'`, `'left'`, `'up'`, `'right'`, `'down'`, `'escape'`, `'delete'`, … * Type: * `String` ## Methods * `toString()` * Returns: * `String` — a string representation of the key event ## Properties inherited from `Event` * `timeStamp` The time at which the event was created, in milliseconds since the epoch. Read only. * Type: * `Number` * `modifiers` The current state of the keyboard modifiers. Read only. * Type: * `object` * See also: * `Key.modifiers` ## Methods inherited from `Event` * `preventDefault()` Cancels the event if it is cancelable, without stopping further propagation of the event. * `stopPropagation()` Prevents further propagation of the current event. * `stop()` Cancels the event if it is cancelable, and stops stopping further propagation of the event. This is has the same effect as calling both `stopPropagation`() and `preventDefault`(). Any handler can also return `false` to indicate that `stop()` should be called right after. # PaperScope The `PaperScope` class represents the scope associated with a Paper context. When working with PaperScript, these scopes are automatically created for us, and through clever scoping the properties and methods of the active scope seem to become part of the global scope. When working with normal JavaScript code, `PaperScope` objects need to be manually created and handled. Paper classes can only be accessed through `PaperScope` objects. Thus in PaperScript they are global, while in JavaScript, they are available on the global `paper` object. For JavaScript you can use `paperScope.install(scope)` to install the Paper classes and objects on the global scope. Note that when working with more than one scope, this still works for classes, but not for objects like `paperScope.project`, since they are not updated in the injected scope if scopes are switched. The global `paper` object is simply a reference to the currently active `PaperScope`. ## Constructors * `PaperScope()` Creates a PaperScope object. * Returns: * `PaperScope` ## Properties * `version` The version of Paper.js, as a string. Read only. * Type: * `String` * `settings` Gives access to paper’s configurable settings. * Type: * `Object` * Options: * `settings.insertItems: Boolean` — controls whether newly created items are automatically inserted into the scene graph, by adding them to `project.activeLayer` — default: `true` * `settings.applyMatrix: Boolean` — controls what value newly created items have their `item.applyMatrix` property set to (Note that not all items can set this to `false`) — default: `true` * `settings.handleSize: Number` — the size of the curve handles when drawing selections — default: `4` * `settings.hitTolerance: Number` — the default tolerance for hit- tests, when no value is specified — default: `0` * `project` The currently active project. * Type: * `Project` * `projects` The list of all open projects within the current Paper.js context. * Type: * Array of `Project` objects * `view` The reference to the active project’s view. Read only. * Type: * `View` * `tool` The reference to the active tool. * Type: * `Tool` * `tools` The list of available tools. * Type: * Array of `Tool` objects ## Methods * `execute(code[, options])` Compiles the PaperScript code into a compiled function and executes it. The compiled function receives all properties of this `PaperScope` as arguments, to emulate a global scope with unaffected performance. It also installs global view and tool handlers automatically on the respective objects. * Options: * `options.url: String` — the url of the source, for source-map debugging * `options.source: String` — the source to be used for the source- mapping, in case the code that’s passed in has already been mingled. * Parameters: * `code:` `String` — the PaperScript code * `options:` `Object` — the compilation options — optional * `install(scope)` Injects the paper scope into any other given scope. Can be used for example to inject the currently active PaperScope into the window’s global scope, to emulate PaperScript-style globally accessible Paper classes and objects. **Please note:** Using this method may override native constructors (e.g. Path). This may cause problems when using Paper.js in conjunction with other libraries that rely on these constructors. Keep the library scoped if you encounter issues caused by this. * Parameters: * `scope:` Example: ``` paper.install(window); ``` * `setup(element)` Sets up an empty project for us. If a canvas is provided, it also creates a `View` for it, both linked to this scope. * Parameters: * `element:` `HTMLCanvasElement`⟋`String`⟋`Size` — the HTML canvas element this scope should be associated with, or an ID string by which to find the element, or the size of the canvas to be created for usage in a web worker. * `activate()` Activates this PaperScope, so all newly created items will be placed in its active project. ## Static Methods * `PaperScope.get(id)` Retrieves a PaperScope object with the given scope id. * Parameters: * `id:` * Returns: * `PaperScope` # PaperScript ## Static Methods * `PaperScript.compile(code[, options])` Compiles PaperScript code into JavaScript code. * Options: * `options.url: String` — the url of the source, for source-map generation * `options.source: String` — the source to be used for the source- mapping, in case the code that’s passed in has already been mingled. * Parameters: * `code:` `String` — the PaperScript code * `options:` `Object` — the compilation options — optional * Returns: * `Object` — an object holding the compiled PaperScript translated into JavaScript code along with source-maps and other information. * `PaperScript.execute(code, scope[, options])` Compiles the PaperScript code into a compiled function and executes it. The compiled function receives all properties of the passed `PaperScope` as arguments, to emulate a global scope with unaffected performance. It also installs global view and tool handlers automatically on the respective objects. * Options: * `options.url: String` — the url of the source, for source-map generation * `options.source: String` — the source to be used for the source- mapping, in case the code that’s passed in has already been mingled. * Parameters: * `code:` `String` — the PaperScript code * `scope:` `PaperScope` — the scope for which the code is executed * `options:` `Object` — the compilation options — optional * Returns: * `Object` — the exports defined in the executed code * `PaperScript.load([script])` Loads, compiles and executes PaperScript code in the HTML document. Note that this method is executed automatically for all scripts in the document through a window load event. You can optionally call it earlier (e.g. from a DOM ready event), or you can mark scripts to be ignored by setting the attribute `ignore="true"` or `data-paper-ignore="true"`, and call the `PaperScript.load(script)` method for each script separately when needed. * Parameters: * `script:` `HTMLScriptElement` — the script to load. If none is provided, all scripts of the HTML document are iterated over and loaded — optional, default: `null` * Returns: * `PaperScope` — the scope produced for the passed `script`, or `undefined` of multiple scripts area loaded