UNPKG

paper

Version:

The Swiss Army Knife of Vector Graphics Scripting

2,336 lines (1,564 loc) 158 kB
<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <title>Group</title> <base target="class-frame"> <link href="../assets/css/docs.css" rel="stylesheet" type="text/css"> <script src="../assets/js/paper.js"></script> <script src="../assets/js/jquery.js"></script> <script src="../assets/js/codemirror.js"></script> <script src="../assets/js/docs.js"></script> </head> <body> <article class="reference"> <div class="reference-class"> <h1>Group</h1> <p> Extends <b><a href="../classes/Item.html"><tt>Item</tt></a></b></p> <p>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.</p> </div> <!-- =============================== constructors ========================== --> <div class="reference-members"> <h2>Constructors</h2> <div id="group" class="member"> <div class="member-link"> <a name="group" href="#group"><tt><b>Group</b>([children])</tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Creates a new Group item and places it at the top of the active layer.</p> <ul class="member-list"> <h4>Parameters:</h4> <li> <tt>children:</tt> Array of <a href="../classes/Item.html"><tt>Item</tt></a> objects &mdash;&nbsp;An array of children that will be added to the newly created group &mdash;&nbsp;optional </li> </ul> <ul class="member-list"> <h4>Returns:</h4> <li> <tt><a href="../classes/Group.html"><tt>Group</tt></a></tt> </li> </ul> <h4>Example:<span class="description">Create a group containing two paths:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-0"> 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-0"></canvas></div> </div> <h4>Example:<span class="description">Click in the view to add a path to the group, which in turn is rotated every frame:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-1"> 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); } </script> <div class="canvas"><canvas width="516" height="320" id="canvas-1"></canvas></div> </div> </div> </div> </div> <div id="group-object" class="member"> <div class="member-link"> <a name="group-object" href="#group-object"><tt><b>Group</b>(object)</tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Creates a new Group item and places it at the top of the active layer.</p> <ul class="member-list"> <h4>Parameters:</h4> <li> <tt>object:</tt> <tt>Object</tt> &mdash;&nbsp;an object containing the properties to be set on the group </li> </ul> <ul class="member-list"> <h4>Returns:</h4> <li> <tt><a href="../classes/Group.html"><tt>Group</tt></a></tt> </li> </ul> <h4>Example:</h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-2"> 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 }); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-2"></canvas></div> </div> </div> </div> </div> </div> <!-- ================================ properties =========================== --> <div class="reference-members"> <h2>Properties</h2> <div id="clipped" class="member"> <div class="member-link"> <a name="clipped" href="#clipped"><tt><b>clipped</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies whether the group item is to be clipped. When setting to <code>true</code>, the first child in the group is automatically defined as the clipping mask.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> <h4>Example:</h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-3"> 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; } </script> <div class="canvas"><canvas width="516" height="100" id="canvas-3"></canvas></div> </div> </div> </div> </div> </div> <!-- =========================== inherited properties ====================== --> <div class="reference-members"><h2>Properties inherited from <a href="../classes/Item.html"><tt>Item</tt></a></h2> <div id="id" class="member"> <div class="member-link"> <a name="id" href="#id"><tt><b>id</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The unique id of the item.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <div id="classname" class="member"> <div class="member-link"> <a name="classname" href="#classname"><tt><b>className</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The class name of the item as a string.</p> <ul class="member-list"> <h4>Values:</h4> <li><tt>'Group'</tt>, <tt>'Layer'</tt>, <tt>'Path'</tt>, <tt>'CompoundPath'</tt>, <tt>'Shape'</tt>, <tt>'Raster'</tt>, <tt>'SymbolItem'</tt>, <tt>'PointText'</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> </div> </div> </div> <div id="name" class="member"> <div class="member-link"> <a name="name" href="#name"><tt><b>name</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The name of the item. If the item has a name, it can be accessed by name through its parent&rsquo;s children list.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> <h4>Example:</h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-4"> 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'; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-4"></canvas></div> </div> </div> </div> </div> <div id="style" class="member"> <div class="member-link"> <a name="style" href="#style"><tt><b>style</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The path style of the item.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Style.html"><tt>Style</tt></a> </li> </ul> <h4>Example:<span class="description">Applying several styles to an item in one go, by passing an object to its style property:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-5"> var circle = new Path.Circle({ center: [80, 50], radius: 30 }); circle.style = { fillColor: 'blue', strokeColor: 'red', strokeWidth: 5 }; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-5"></canvas></div> </div> <h4>Example:<span class="description">Copying the style of another item:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-6"> 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-6"></canvas></div> </div> <h4>Example:<span class="description">Applying the same style object to multiple items:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-7"> 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-7"></canvas></div> </div> </div> </div> </div> <div id="locked" class="member"> <div class="member-link"> <a name="locked" href="#locked"><tt><b>locked</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies whether the item is locked. When set to <code>true</code>, item interactions with the mouse are disabled.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>false</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> <h4>Example:</h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-8"> 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' }); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-8"></canvas></div> </div> </div> </div> </div> <div id="visible" class="member"> <div class="member-link"> <a name="visible" href="#visible"><tt><b>visible</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies whether the item is visible. When set to <code>false</code>, the item won&rsquo;t be drawn.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>true</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> <h4>Example:<span class="description">Hiding an item:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-9"> var path = new Path.Circle({ center: [50, 50], radius: 20, fillColor: 'red' }); // Hide the path: path.visible = false; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-9"></canvas></div> </div> </div> </div> </div> <div id="blendmode" class="member"> <div class="member-link"> <a name="blendmode" href="#blendmode"><tt><b>blendMode</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The blend mode with which the item is composited onto the canvas. Both the standard canvas compositing modes, as well as the new CSS blend modes are supported. If blend-modes cannot be rendered natively, they are emulated. Be aware that emulation can have an impact on performance.</p> <ul class="member-list"> <h4>Values:</h4> <li><tt>'normal'</tt>, <tt>'multiply'</tt>, <tt>'screen'</tt>, <tt>'overlay'</tt>, <tt>'soft-light'</tt>, <tt>'hard- light'</tt>, <tt>'color-dodge'</tt>, <tt>'color-burn'</tt>, <tt>'darken'</tt>, <tt>'lighten'</tt>, <tt>'difference'</tt>, <tt>'exclusion'</tt>, <tt>'hue'</tt>, <tt>'saturation'</tt>, <tt>'luminosity'</tt>, <tt>'color'</tt>, <tt>'add'</tt>, <tt>'subtract'</tt>, <tt>'average'</tt>, <tt>'pin-light'</tt>, <tt>'negation'</tt>, <tt>'source-over'</tt>, <tt>'source-in'</tt>, <tt>'source-out'</tt>, <tt>'source-atop'</tt>, <tt>'destination-over'</tt>, <tt>'destination-in'</tt>, <tt>'destination-out'</tt>, <tt>'destination-atop'</tt>, <tt>'lighter'</tt>, <tt>'darker'</tt>, <tt>'copy'</tt>, <tt>'xor'</tt></li> </ul> <ul class="member-list"> <h4>Default:</h4> <li><tt>'normal'</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> <h4>Example:<span class="description">Setting an item's blend mode:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-10"> // 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'; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-10"></canvas></div> </div> </div> </div> </div> <div id="opacity" class="member"> <div class="member-link"> <a name="opacity" href="#opacity"><tt><b>opacity</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The opacity of the item as a value between <code>0</code> and <code>1</code>.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>1</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> <h4>Example:<span class="description">Making an item 50% transparent:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-11"> 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-11"></canvas></div> </div> </div> </div> </div> <div id="selected" class="member"> <div class="member-link"> <a name="selected" href="#selected"><tt><b>selected</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies whether the item is selected. This will also return <code>true</code> for <a href="../classes/Group.html"><tt>Group</tt></a> items if they are partially selected, e.g. groups containing selected or partially selected paths.</p> <p>Paper.js draws the visual outlines of selected items on top of your project. This can be useful for debugging, as it allows you to see the construction of paths, position of path curves, individual segment points and bounding boxes of symbol and raster items.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>false</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> <ul class="member-list"> <h4>See also:</h4> <li><tt><a href="../classes/Project.html#selecteditems"><tt>project.selectedItems</tt></a></tt></li> <li><tt><a href="../classes/Segment.html#selected"><tt>segment.selected</tt></a></tt></li> <li><tt><a href="../classes/Curve.html#selected"><tt>curve.selected</tt></a></tt></li> <li><tt><a href="../classes/Point.html#selected"><tt>point.selected</tt></a></tt></li> </ul> <h4>Example:<span class="description">Selecting an item:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-12"> var path = new Path.Circle({ center: [80, 50], radius: 35 }); path.selected = true; // Select the path </script> <div class="canvas"><canvas width="516" height="100" id="canvas-12"></canvas></div> </div> </div> </div> </div> <div id="clipmask" class="member"> <div class="member-link"> <a name="clipmask" href="#clipmask"><tt><b>clipMask</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>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.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>false</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> </div> </div> </div> <div id="data" class="member"> <div class="member-link"> <a name="data" href="#data"><tt><b>data</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>A plain javascript object which can be used to store arbitrary data on the item.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Object</tt> </li> </ul> <h4>Example:</h4> <pre><code>var path = new Path(); path.data.remember = 'milk';</code></pre> <h4>Example:</h4> <pre><code>var path = new Path(); path.data.malcolm = new Point(20, 30); console.log(path.data.malcolm.x); // 20</code></pre> <h4>Example:</h4> <pre><code>var path = new Path(); path.data = { home: 'Omicron Theta', found: 2338, pets: ['Spot'] }; console.log(path.data.pets.length); // 1</code></pre> <h4>Example:</h4> <pre><code>var path = new Path({ data: { home: 'Omicron Theta', found: 2338, pets: ['Spot'] } }); console.log(path.data.pets.length); // 1</code></pre> </div> </div> </div> <h3>Position and Bounding Boxes</h3> <div id="position" class="member"> <div class="member-link"> <a name="position" href="#position"><tt><b>position</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item&rsquo;s position within the parent item&rsquo;s coordinate system. By default, this is the <a href="../classes/Rectangle.html#center"><tt>rectangle.center</tt></a> of the item&rsquo;s <a href="../classes/Item.html#bounds"><tt>bounds</tt></a> rectangle.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Point.html"><tt>Point</tt></a> </li> </ul> <h4>Example:<span class="description">Changing the position of a path:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-13"> // 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); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-13"></canvas></div> </div> <h4>Example:<span class="description">Changing the x coordinate of an item's position:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-14"> // 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-14"></canvas></div> </div> </div> </div> </div> <div id="pivot" class="member"> <div class="member-link"> <a name="pivot" href="#pivot"><tt><b>pivot</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item&rsquo;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 <a href="../classes/Item.html#position"><tt>position</tt></a>. By default, it is set to <code>null</code>, meaning the <a href="../classes/Rectangle.html#center"><tt>rectangle.center</tt></a> of the item&rsquo;s <a href="../classes/Item.html#bounds"><tt>bounds</tt></a> rectangle is used as pivot.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>null</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Point.html"><tt>Point</tt></a> </li> </ul> </div> </div> </div> <div id="bounds" class="member"> <div class="member-link"> <a name="bounds" href="#bounds"><tt><b>bounds</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The bounding rectangle of the item excluding stroke width.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Rectangle.html"><tt>Rectangle</tt></a> </li> </ul> </div> </div> </div> <div id="strokebounds" class="member"> <div class="member-link"> <a name="strokebounds" href="#strokebounds"><tt><b>strokeBounds</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The bounding rectangle of the item including stroke width.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Rectangle.html"><tt>Rectangle</tt></a> </li> </ul> </div> </div> </div> <div id="handlebounds" class="member"> <div class="member-link"> <a name="handlebounds" href="#handlebounds"><tt><b>handleBounds</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The bounding rectangle of the item including handles.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Rectangle.html"><tt>Rectangle</tt></a> </li> </ul> </div> </div> </div> <div id="internalbounds" class="member"> <div class="member-link"> <a name="internalbounds" href="#internalbounds"><tt><b>internalBounds</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The bounding rectangle of the item without any matrix transformations.</p> <p>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.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Rectangle.html"><tt>Rectangle</tt></a> </li> </ul> </div> </div> </div> <div id="rotation" class="member"> <div class="member-link"> <a name="rotation" href="#rotation"><tt><b>rotation</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The current rotation angle of the item, as described by its <a href="../classes/Item.html#matrix"><tt>matrix</tt></a>. Please note that this only returns meaningful values for items with <a href="../classes/Item.html#applymatrix"><tt>applyMatrix</tt></a> set to <code>false</code>, meaning they do not directly bake transformations into their content.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <div id="scaling" class="member"> <div class="member-link"> <a name="scaling" href="#scaling"><tt><b>scaling</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The current scale factor of the item, as described by its <a href="../classes/Item.html#matrix"><tt>matrix</tt></a>. Please note that this only returns meaningful values for items with <a href="../classes/Item.html#applymatrix"><tt>applyMatrix</tt></a> set to <code>false</code>, meaning they do not directly bake transformations into their content.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Point.html"><tt>Point</tt></a> </li> </ul> </div> </div> </div> <div id="matrix" class="member"> <div class="member-link"> <a name="matrix" href="#matrix"><tt><b>matrix</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item&rsquo;s transformation matrix, defining position and dimensions in relation to its parent item in which it is contained.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Matrix.html"><tt>Matrix</tt></a> </li> </ul> </div> </div> </div> <div id="globalmatrix" class="member"> <div class="member-link"> <a name="globalmatrix" href="#globalmatrix"><tt><b>globalMatrix</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item&rsquo;s global transformation matrix in relation to the global project coordinate space. Note that the view&rsquo;s transformations resulting from zooming and panning are not factored in.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Matrix.html"><tt>Matrix</tt></a> </li> </ul> </div> </div> </div> <div id="viewmatrix" class="member"> <div class="member-link"> <a name="viewmatrix" href="#viewmatrix"><tt><b>viewMatrix</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item&rsquo;s global matrix in relation to the view coordinate space. This means that the view&rsquo;s transformations resulting from zooming and panning are factored in.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Matrix.html"><tt>Matrix</tt></a> </li> </ul> </div> </div> </div> <div id="applymatrix" class="member"> <div class="member-link"> <a name="applymatrix" href="#applymatrix"><tt><b>applyMatrix</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Controls whether the transformations applied to the item (e.g. through <a href="../classes/Item.html#transform-matrix"><tt>transform(matrix)</tt></a>, <a href="../classes/Item.html#rotate-angle"><tt>rotate(angle)</tt></a>, <a href="../classes/Item.html#scale-scale"><tt>scale(scale)</tt></a>, etc.) are stored in its <a href="../classes/Item.html#matrix"><tt>matrix</tt></a> property, or whether they are directly applied to its contents or children (passed on to the segments in <a href="../classes/Path.html"><tt>Path</tt></a> items, the children of <a href="../classes/Group.html"><tt>Group</tt></a> items, etc.).</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>true</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> </div> </div> </div> <h3>Project Hierarchy</h3> <div id="project" class="member"> <div class="member-link"> <a name="project" href="#project"><tt><b>project</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The project that this item belongs to.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Project.html"><tt>Project</tt></a> </li> </ul> </div> </div> </div> <div id="view" class="member"> <div class="member-link"> <a name="view" href="#view"><tt><b>view</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The view that this item belongs to.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/View.html"><tt>View</tt></a> </li> </ul> </div> </div> </div> <div id="layer" class="member"> <div class="member-link"> <a name="layer" href="#layer"><tt><b>layer</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The layer that this item is contained within.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Layer.html"><tt>Layer</tt></a> </li> </ul> </div> </div> </div> <div id="parent" class="member"> <div class="member-link"> <a name="parent" href="#parent"><tt><b>parent</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The item that this item is contained within.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Item.html"><tt>Item</tt></a> </li> </ul> <h4>Example:</h4> <pre><code>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</code></pre> <h4>Example:<span class="description">Setting the parent of the item to another item</span></h4> <pre><code>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</code></pre> <h4>Example:<span class="description">Setting the parent of an item in the constructor</span></h4> <pre><code>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</code></pre> </div> </div> </div> <div id="children" class="member"> <div class="member-link"> <a name="children" href="#children"><tt><b>children</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The children items contained within this item. Items that define a <a href="../classes/Item.html#name"><tt>name</tt></a> can also be accessed by name.</p> <p><b>Please note:</b> The children array should not be modified directly using array functions. To remove single items from the children list, use <a href="../classes/Item.html#remove"><tt>item.remove</tt></a>(), to remove all items from the children list, use <a href="../classes/Item.html#removechildren"><tt>item.removeChildren</tt></a>(). To add items to the children list, use <a href="../classes/Item.html#addchild-item"><tt>item.addChild(item)</tt></a> or <a href="../classes/Item.html#insertchild-index-item"><tt>item.insertChild(index, item)</tt></a>.</p> <ul class="member-list"> <h4>Type:</h4> <li> Array of <a href="../classes/Item.html"><tt>Item</tt></a> objects </li> </ul> <h4>Example:<span class="description">Accessing items in the children array:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-15"> 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'; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-15"></canvas></div> </div> <h4>Example:<span class="description">Accessing children by name:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-16"> 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'; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-16"></canvas></div> </div> <h4>Example:<span class="description">Passing an array of items to item.children:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-17"> 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'; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-17"></canvas></div> </div> </div> </div> </div> <div id="firstchild" class="member"> <div class="member-link"> <a name="firstchild" href="#firstchild"><tt><b>firstChild</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The first item contained within this item. This is a shortcut for accessing <code>item.children[0]</code>.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Item.html"><tt>Item</tt></a> </li> </ul> </div> </div> </div> <div id="lastchild" class="member"> <div class="member-link"> <a name="lastchild" href="#lastchild"><tt><b>lastChild</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The last item contained within this item.This is a shortcut for accessing <code>item.children[item.children.length - 1]</code>.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Item.html"><tt>Item</tt></a> </li> </ul> </div> </div> </div> <div id="nextsibling" class="member"> <div class="member-link"> <a name="nextsibling" href="#nextsibling"><tt><b>nextSibling</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The next item on the same level as this item.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Item.html"><tt>Item</tt></a> </li> </ul> </div> </div> </div> <div id="previoussibling" class="member"> <div class="member-link"> <a name="previoussibling" href="#previoussibling"><tt><b>previousSibling</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The previous item on the same level as this item.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Item.html"><tt>Item</tt></a> </li> </ul> </div> </div> </div> <div id="index" class="member"> <div class="member-link"> <a name="index" href="#index"><tt><b>index</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The index of this item within the list of its parent&rsquo;s children.</p> <p>Read only.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <h3>Stroke Style</h3> <div id="strokecolor" class="member"> <div class="member-link"> <a name="strokecolor" href="#strokecolor"><tt><b>strokeColor</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The color of the stroke.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Color.html"><tt>Color</tt></a>⟋<tt>null</tt> </li> </ul> <h4>Example:<span class="description">Setting the stroke color of a path:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-18"> // 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); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-18"></canvas></div> </div> </div> </div> </div> <div id="strokewidth" class="member"> <div class="member-link"> <a name="strokewidth" href="#strokewidth"><tt><b>strokeWidth</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The width of the stroke.</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> <h4>Example:<span class="description">Setting an item's stroke width:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-19"> // 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; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-19"></canvas></div> </div> </div> </div> </div> <div id="strokecap" class="member"> <div class="member-link"> <a name="strokecap" href="#strokecap"><tt><b>strokeCap</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The shape to be used at the beginning and end of open <a href="../classes/Path.html"><tt>Path</tt></a> items, when they have a stroke.</p> <ul class="member-list"> <h4>Values:</h4> <li><tt>'round'</tt>, <tt>'square'</tt>, <tt>'butt'</tt></li> </ul> <ul class="member-list"> <h4>Default:</h4> <li><tt>'butt'</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> <h4>Example:<span class="description">A look at the different stroke caps:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-20"> 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'; </script> <div class="canvas"><canvas width="516" height="200" id="canvas-20"></canvas></div> </div> </div> </div> </div> <div id="strokejoin" class="member"> <div class="member-link"> <a name="strokejoin" href="#strokejoin"><tt><b>strokeJoin</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The shape to be used at the segments and corners of <a href="../classes/Path.html"><tt>Path</tt></a> items when they have a stroke.</p> <ul class="member-list"> <h4>Values:</h4> <li><tt>'miter'</tt>, <tt>'round'</tt>, <tt>'bevel'</tt></li> </ul> <ul class="member-list"> <h4>Default:</h4> <li><tt>'miter'</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> <h4>Example:<span class="description">A look at the different stroke joins:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-21"> 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'; </script> <div class="canvas"><canvas width="516" height="120" id="canvas-21"></canvas></div> </div> </div> </div> </div> <div id="dashoffset" class="member"> <div class="member-link"> <a name="dashoffset" href="#dashoffset"><tt><b>dashOffset</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The dash offset of the stroke.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>0</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <div id="strokescaling" class="member"> <div class="member-link"> <a name="strokescaling" href="#strokescaling"><tt><b>strokeScaling</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies whether the stroke is to be drawn taking the current affine transformation into account (the default behavior), or whether it should appear as a non-scaling stroke.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>true</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Boolean</tt> </li> </ul> </div> </div> </div> <div id="dasharray" class="member"> <div class="member-link"> <a name="dasharray" href="#dasharray"><tt><b>dashArray</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Specifies an array containing the dash and gap lengths of the stroke.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>[]</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> Array of <tt>Numbers</tt> </li> </ul> <h4>Example:</h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-22"> 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]; </script> <div class="canvas"><canvas width="516" height="100" id="canvas-22"></canvas></div> </div> </div> </div> </div> <div id="miterlimit" class="member"> <div class="member-link"> <a name="miterlimit" href="#miterlimit"><tt><b>miterLimit</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The miter limit of the stroke. When two line segments meet at a sharp angle and miter joins have been specified for <a href="../classes/Item.html#strokejoin"><tt>item.strokeJoin</tt></a>, it is possible for the miter to extend far beyond the <a href="../classes/Item.html#strokewidth"><tt>item.strokeWidth</tt></a> of the path. The miterLimit imposes a limit on the ratio of the miter length to the <a href="../classes/Item.html#strokewidth"><tt>item.strokeWidth</tt></a>.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>10</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <h3>Fill Style</h3> <div id="fillcolor" class="member"> <div class="member-link"> <a name="fillcolor" href="#fillcolor"><tt><b>fillColor</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The fill color of the item.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Color.html"><tt>Color</tt></a>⟋<tt>null</tt> </li> </ul> <h4>Example:<span class="description">Setting the fill color of a path to red:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-23"> // 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); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-23"></canvas></div> </div> </div> </div> </div> <div id="fillrule" class="member"> <div class="member-link"> <a name="fillrule" href="#fillrule"><tt><b>fillRule</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The fill-rule with which the shape gets filled. Please note that only modern browsers support fill-rules other than <code>&#39;nonzero&#39;</code>.</p> <ul class="member-list"> <h4>Values:</h4> <li><tt>'nonzero'</tt>, <tt>'evenodd'</tt></li> </ul> <ul class="member-list"> <h4>Default:</h4> <li><tt>'nonzero'</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>String</tt> </li> </ul> </div> </div> </div> <h3>Shadow Style</h3> <div id="shadowcolor" class="member"> <div class="member-link"> <a name="shadowcolor" href="#shadowcolor"><tt><b>shadowColor</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The shadow color.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Color.html"><tt>Color</tt></a>⟋<tt>null</tt> </li> </ul> <h4>Example:<span class="description">Creating a circle with a black shadow:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-24"> 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) }); </script> <div class="canvas"><canvas width="516" height="100" id="canvas-24"></canvas></div> </div> </div> </div> </div> <div id="shadowblur" class="member"> <div class="member-link"> <a name="shadowblur" href="#shadowblur"><tt><b>shadowBlur</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The shadow&rsquo;s blur radius.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>0</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Number</tt> </li> </ul> </div> </div> </div> <div id="shadowoffset" class="member"> <div class="member-link"> <a name="shadowoffset" href="#shadowoffset"><tt><b>shadowOffset</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The shadow&rsquo;s offset.</p> <ul class="member-list"> <h4>Default:</h4> <li><tt>0</tt></li> </ul> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Point.html"><tt>Point</tt></a> </li> </ul> </div> </div> </div> <h3>Selection Style</h3> <div id="selectedcolor" class="member"> <div class="member-link"> <a name="selectedcolor" href="#selectedcolor"><tt><b>selectedColor</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>The color the item is highlighted with when selected. If the item does not specify its own color, the color defined by its layer is used instead.</p> <ul class="member-list"> <h4>Type:</h4> <li> <a href="../classes/Color.html"><tt>Color</tt></a>⟋<tt>null</tt> </li> </ul> </div> </div> </div> <h3>Event Handlers</h3> <div id="onframe" class="member"> <div class="member-link"> <a name="onframe" href="#onframe"><tt><b>onFrame</b></tt></a> </div> <div class="member-description hidden"> <div class="member-text"> <p>Item level handler function to be called on each frame of an animation. The function receives an event object which contains information about the frame event:</p> <ul class="member-list"> <h4>Type:</h4> <li> <tt>Function</tt>⟋<tt>null</tt> </li> </ul> <ul class="member-list"> <h4>Options:</h4> <li><tt>event.count: <tt>Number</tt></tt> &mdash; the number of times the frame event was fired</li> <li><tt>event.time: <tt>Number</tt></tt> &mdash; the total amount of time passed since the first frame event in seconds</li> <li><tt>event.delta: <tt>Number</tt></tt> &mdash; the time passed in seconds since the last frame event</li> </ul> <ul class="member-list"> <h4>See also:</h4> <li><tt><a href="../classes/View.html#onframe"><tt>view.onFrame</tt></a></tt></li> </ul> <h4>Example:<span class="description">Creating an animation:</span></h4> <div class="paperscript split"> <div class="buttons"> <div class="button run">Run</div> </div> <script type="text/paperscript" canvas="canvas-25"> // 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); } </script> <div class="canvas"><canvas width="516" height="100" id="canvas-25"></canvas></div> </div> </div> </div> </d