paper 0.15.0 → 0.17.0

package/dist/docs/classes/Project.html

@@ -80,6 +80,32 @@
 		<h2>Properties</h2>
 		
 			
+<div id="currenttextstyle" class="member">
+<div class="member-link">
+<a name="currenttextstyle" href="#currenttextstyle"><tt><b>currentTextStyle</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The style new text items take in a hosted project, in place of <a href="../classes/Project.html#currentstyle"><tt>currentStyle</tt></a>, when the host sets one: for hosts whose new text has defaults of its own, such as a black fill without a stroke whatever new paths take. Paths keep taking the current style.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			<a href="../classes/Style.html"><tt>Style</tt></a>
+		</li>
+	</ul>
+    
+	
+	
+</div>
+
+</div>
+</div>
+		
+			
 <div id="host" class="member">
 <div class="member-link">
 <a name="host" href="#host"><tt><b>host</b></tt></a>
@@ -87,10 +113,14 @@
 <div class="member-description hidden">
 
 <div class="member-text">
-	<p>The host document that the project&rsquo;s items come from. Setting it creates the project&rsquo;s layers from the host&rsquo;s records. All items are created as shells that load their content and children from the host on first access.</p>
-<p>The host provides: - <code>getChildren(key)</code>, which returns the records of the children of  the node with the given key, or of the top level for <code>null</code>, as  columns: <code>keys</code>, <code>types</code> (indices into <code>typeNames</code>), <code>typeNames</code>,  <code>flags</code> (selected: 1, visible: 2, locked: 4, strokeScaling: 8,  clipMask: 64, guide: 128, empty: 256), <code>boxes</code> (bounds,  strokeBounds and roughBounds in the item&rsquo;s coordinates, 12 numbers  per item), and the sparse objects <code>names</code> and <code>matrices</code>. - <code>getItem(key)</code>, which returns the node&rsquo;s own content in the form  of <a href="../classes/Item.html#importjson-json"><tt>item.importJSON(json)</tt></a>, without children. Linked text  gives <code>linked</code>, the keys of its story&rsquo;s text items in order, and  leaves out its story. - <code>getStory(key)</code>, for linked text, which returns its story with the  key of any of its text items: <code>content</code> or <code>runs</code>, <code>paragraphs</code>,  and the character and paragraph styles, as  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a> writes them in the JSON of a  text item. - <code>getAncestorKeys(key)</code>, which returns the keys from the top level  down to the node&rsquo;s parent. - Optionally <code>layOut(json, start, key)</code>, which lays out a text item  from <code>start</code> in its story, given as the JSON string that  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a> writes of it as the script holds  it, or as <code>null</code> where the script didn&rsquo;t change it since it  loaded or the host took its changes with  <a href="../classes/Project.html#takechanges"><tt>project.takeChanges</tt></a>(), for the host to lay out its own  node, and returns  <code>{ end, lines }</code>: where its visible text ends, and  its lines, each <code>{ start, end, x, y, width, lineHeight, ascent,
+	<p>The host document that the project&rsquo;s items come from. Setting it creates the project&rsquo;s layers from the host&rsquo;s records. All items are created as shells that load their content and children from the host on first access. The host draws its items, so setting it also turns off <a href="../classes/View.html#autoupdate"><tt>view.autoUpdate</tt></a>, which would draw them all and load them in full.</p>
+<p>The host provides: - <code>getChildren(key)</code>, which returns the records of the children of  the node with the given key, or of the top level for <code>null</code>, as  columns: <code>keys</code>, <code>types</code> (indices into <code>typeNames</code>), <code>typeNames</code>,  <code>flags</code> (selected: 1, visible: 2, locked: 4, strokeScaling: 8,  clipMask: 64, guide: 128, empty: 256), optionally <code>boxes</code>  (bounds, strokeBounds and roughBounds in the item&rsquo;s coordinates, 12  numbers per item), and the sparse objects <code>names</code> and <code>matrices</code>. - <code>getBounds(key)</code>, for hosts that don&rsquo;t send <code>boxes</code>, which returns  the node&rsquo;s 12 numbers, or <code>null</code> for an empty node. Items ask for  them when their bounds are needed, and again after the host sent  their record again. - <code>getItem(key)</code>, which returns the node&rsquo;s own content in the form  of <a href="../classes/Item.html#importjson-json"><tt>item.importJSON(json)</tt></a>, without children. Linked text  gives <code>linked</code>, the keys of its story&rsquo;s text items in order, and  leaves out its story. Rasters give their <code>size</code> without a <code>source</code>  and <code>crossOrigin</code>. - <code>getImage(key)</code>, for rasters, which returns the node&rsquo;s pixels as a  canvas with a 2D context, of the size that <code>getItem()</code> gives.  Rasters load them on first access to their pixels, and Paper.js  never loads them by itself, except to draw them. Rasters whose  pixels the host fails to give draw nothing. - <code>getStory(key)</code>, for linked text, which returns its story with the  key of any of its text items: <code>content</code> or <code>runs</code>, <code>paragraphs</code>,  and the character and paragraph styles, as  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a> writes them in the JSON of a  text item. - <code>getAncestorKeys(key)</code>, which returns the keys from the top level  down to the node&rsquo;s parent. - Optionally <code>layOut(json, start, key)</code>, which lays out a text item  from <code>start</code> in its story, given as the JSON string that  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a> writes of it as the script holds  it, or as <code>null</code> where the script didn&rsquo;t change it since it  loaded or the host took its changes with  <a href="../classes/Project.html#takechanges"><tt>project.takeChanges</tt></a>(), for the host to lay out its own  node, and returns  <code>{ end, lines }</code>: where its visible text ends, and  its lines, each <code>{ start, end, x, y, width, lineHeight, ascent,
   descent, pieces }</code>, with pieces <code>{ start, end, x, y, dx, width,
-  rotation, size, ascent, descent, lineHeight }</code> and an optional  <code>content</code>, as for a hyphen, all in the item&rsquo;s coordinates. <code>key</code>  is null for text that the host doesn&rsquo;t know yet. Without it,  Paper.js lays out text itself.</p>
+  rotation, size, ascent, descent, lineHeight }</code> and an optional  <code>content</code>, as for a hyphen, all in the item&rsquo;s coordinates. <code>key</code>  is null for text that the host doesn&rsquo;t know yet. Without it,  Paper.js lays out text itself. - <code>getDefinition(key)</code>, for the pattern and symbol definitions that  the host shares between its items, which the JSON of its items  refers to as <code>[&#39;@key&#39;]</code>, as in <code>fillColor: [&#39;pattern&#39;,
+  [&#39;@pattern/Dots&#39;], matrix]</code> or <code>definition: [&#39;@symbol/Star&#39;]</code>.  It returns the definition in the form of  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a>, with its whole item:  <code>[&#39;PatternDefinition&#39;, item, { tile, spacing }]</code> or  <code>[&#39;SymbolDefinition&#39;, item]</code>, always: for a key that it has no  definition of, an empty one of the type, as  <code>[&#39;SymbolDefinition&#39;, [&#39;Group&#39;, {}]]</code>. Each definition loads  once, and the JSON of the items that use it, as  <a href="../classes/Item.html#exportjson-options"><tt>item.exportJSON(options)</tt></a> writes it, refers to it by its  key again. Definitions that scripts create have no key, and are  written out whole, until the host sets their <code>key</code>, which it can  only set once. <a href="../classes/Project.html#takechanges"><tt>project.takeChanges</tt></a>() lists those that the  changed items use first, nested ones first, as  <code>{ definition, flags }</code> with the <code>ChangeFlag.INSERTION</code> flag,  followed by the changes of the host&rsquo;s definitions. Renaming those  isn&rsquo;t supported. - <code>getDefinitionKeys(type)</code>, which returns the keys of all the  host&rsquo;s definitions of the type, <code>&#39;SymbolDefinition&#39;</code> or  <code>&#39;PatternDefinition&#39;</code>, for <a href="../classes/Project.html#symboldefinitions"><tt>symbolDefinitions</tt></a> and  <a href="../classes/Project.html#patterndefinitions"><tt>patternDefinitions</tt></a>.</p>
+<p>Items that move into a project with another host load in full from their own host first, and drop their keys, so they are new items there. They bring copies without keys of the symbol and pattern definitions of their host along, shared by the items of one insertion or copy, so the new host takes them as new ones too. Linked text brings a copy of its story along, which flows on through the items that stay. Host items can&rsquo;t enter the project of another host.</p>
+<p>The host draws the items, and the selection. To show what scripts draw in <a href="../classes/Item.html#ondraw"><tt>item.onDraw</tt></a> and <a href="../classes/Item.html#ondrawselection"><tt>item.onDrawSelection</tt></a>, it calls <code>project.draw(ctx, matrix, pixelRatio)</code>, which in a hosted project only calls these handlers, with the context, the view&rsquo;s matrix and pixel ratio that the host gives, for the visible items that have them, and for the selected ones. Handlers of classes, such as <code>Path.onDraw</code>, load all items once. The host asks <a href="../classes/Project.html#hasdrawhandlers"><tt>hasDrawHandlers</tt></a>() whether it needs to call it.</p>
+<p><a href="../classes/Project.html#takechanges"><tt>project.takeChanges</tt></a>() marks the changes of the items whose children changed in order other than by new items inserted and items removed, which the other changes don&rsquo;t tell, with <code>reordered: true</code>: the host reads their children whole, and can place the others&rsquo; new items by their indices.</p>
 	
 	
 	
@@ -134,6 +164,58 @@
     
 	
 	
+</div>
+
+</div>
+</div>
+		
+			
+<div id="onactivate" class="member">
+<div class="member-link">
+<a name="onactivate" href="#onactivate"><tt><b>onActivate</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The function to be called when the project is activated through <a href="../classes/Project.html#activate"><tt>activate</tt></a>(). The function receives the previously active project, which is the project itself when it was already active.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			<tt>Function</tt>⟋<tt>null</tt>
+		</li>
+	</ul>
+    
+	
+	
+</div>
+
+</div>
+</div>
+		
+			
+<div id="ondeactivate" class="member">
+<div class="member-link">
+<a name="ondeactivate" href="#ondeactivate"><tt><b>onDeactivate</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The function to be called when another project is activated through <a href="../classes/Project.html#activate"><tt>activate</tt></a>() while this one is active, or when this one is removed while active.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			<tt>Function</tt>⟋<tt>null</tt>
+		</li>
+	</ul>
+    
+	
+	
 </div>
 
 </div>
@@ -372,6 +454,34 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
     
 	
 	
+</div>
+
+</div>
+</div>
+		
+			
+<div id="patterndefinitions" class="member">
+<div class="member-link">
+<a name="patterndefinitions" href="#patterndefinitions"><tt><b>patternDefinitions</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The pattern definitions that the fill and stroke colors of the items in the project use.</p>
+	
+		<p>Read only.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			Array of <a href="../classes/PatternDefinition.html"><tt>PatternDefinition</tt></a> objects
+		</li>
+	</ul>
+    
+	
+	
 </div>
 
 </div>
@@ -409,6 +519,63 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
 
 
 
+    <div class="reference-members">
+    	<h2>Static Properties</h2>
+        
+            
+<div id="onactivate" class="member">
+<div class="member-link">
+<a name="onactivate" href="#onactivate"><tt><b>Project.onActivate</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The function to be called when any project is activated, as <a href="../classes/Project.html#onactivate"><tt>onActivate</tt></a> is for a single project, including the projects that activate themselves when they are created, with <code>this</code> set to the project. <code>Project.on(&#39;activate&#39;, handler)</code> and <code>Project.off(&#39;activate&#39;, handler)</code> attach and detach them too. Classes are shared by all <a href="../classes/PaperScope.html"><tt>PaperScope</tt></a> objects, and so are their handlers.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			<tt>Function</tt>⟋<tt>null</tt>
+		</li>
+	</ul>
+    
+	
+	
+</div>
+
+</div>
+</div>
+        
+            
+<div id="ondeactivate" class="member">
+<div class="member-link">
+<a name="ondeactivate" href="#ondeactivate"><tt><b>Project.onDeactivate</b></tt></a>
+</div>
+<div class="member-description hidden">
+
+<div class="member-text">
+	<p>The function to be called when any project is deactivated, as <a href="../classes/Project.html#ondeactivate"><tt>onDeactivate</tt></a> is for a single project, see <a href="../classes/Project.html#onactivate"><tt>Project.onActivate</tt></a>.</p>
+	
+	
+	
+	<ul class="member-list">
+		<h4>Type:</h4>
+		<li>
+			<tt>Function</tt>⟋<tt>null</tt>
+		</li>
+	</ul>
+    
+	
+	
+</div>
+
+</div>
+</div>
+        
+    </div>
+
 
 
 <!-- ============================== methods ================================ -->
@@ -452,6 +619,35 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
 
 	
 	
+</div>
+</div>
+</div>
+
+	
+<div id="hasdrawhandlers" class="member">
+<div class="member-link">
+<a name="hasdrawhandlers" href="#hasdrawhandlers"><tt><b>hasDrawHandlers</b>()</tt></a>
+</div>
+<div class="member-description hidden">
+<div class="member-text">
+	<p>Checks whether any item of the project or class has draw handlers, <a href="../classes/Item.html#ondraw"><tt>item.onDraw</tt></a> or, for the selected items, <a href="../classes/Item.html#ondrawselection"><tt>item.onDrawSelection</tt></a>, for hosts that draw the items themselves, see <a href="../classes/Project.html#host"><tt>host</tt></a>.</p>
+    
+	
+	
+	<ul class="member-list">
+		<h4>Returns:</h4>
+		
+			<li>
+<tt><tt>Boolean</tt></tt>&nbsp;&mdash;&nbsp;<tt>true</tt> if drawing the project calls any handlers, <tt>false</tt> otherwise
+</li>
+
+		
+	</ul>
+
+
+
+	
+	
 </div>
 </div>
 </div>
@@ -463,7 +659,7 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
 </div>
 <div class="member-description hidden">
 <div class="member-text">
-	<p>Updates the items of changed host nodes, given in the column format of the host&rsquo;s <code>getChildren()</code>, with two more flags: 16 when the node&rsquo;s own content changed, so the item loads it again on next access, and 32 when its list of children changed, so it loads them again right away if it had loaded them, keeping the items of nodes that remain. Nodes without items are skipped.</p>
+	<p>Updates the items of changed host nodes, given in the column format of the host&rsquo;s <code>getChildren()</code>, with two more flags: 16 when the node&rsquo;s own content changed, so the item loads it again on next access, and 32 when its list of children changed, so it loads them again right away if it had loaded them, keeping the items of nodes that remain. Nodes without items are skipped. <code>definitions</code> lists the keys of changed definitions of the host&rsquo;s <code>getDefinition()</code>, which load again right away into the same objects, so the colors and symbol items that use them change along. A definition that the host no longer has, for which <code>getDefinition()</code> may return <code>null</code> here, is emptied and draws nothing. The columns may hold only definitions.</p>
     
 	
 <ul class="member-list">
@@ -494,7 +690,7 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
 </div>
 <div class="member-description hidden">
 <div class="member-text">
-	<p>Returns the changes logged since tracking was activated or since the last call, and clears the log. Each item is listed once, with the <a href="../classes/ChangeFlag.html"><tt>ChangeFlag</tt></a> values of all its changes combined. Removed items are listed with the <code>ChangeFlag.INSERTION</code> flag.</p>
+	<p>Returns the changes logged since tracking was activated or since the last call, and clears the log. Each item is listed once, with the <a href="../classes/ChangeFlag.html"><tt>ChangeFlag</tt></a> values of all its changes combined. Removed items are listed with the <code>ChangeFlag.INSERTION</code> flag, and items that moved to another project are left out, as that one lists them. Symbol and pattern definitions whose item, tile, spacing or name changed are listed too, as <code>{ definition, flags }</code>.</p>
     
 	
 	
@@ -502,7 +698,7 @@ var path2 = new Path.Circle(new Point(175, 50), 20);
 		<h4>Returns:</h4>
 		
 			<li>
-<tt>Array of <tt>Object</tt> objects</tt>&nbsp;&mdash;&nbsp;the changes as <code>{ item, flags }</code> objects, or <code>null</code>  if <a href="../classes/Project.html#trackchanges"><tt>trackChanges</tt></a> is off
+<tt>Array of <tt>Object</tt> objects</tt>&nbsp;&mdash;&nbsp;the changes as <code>{ item, flags }</code> and  <code>{ definition, flags }</code> objects, or <code>null</code> if <a href="../classes/Project.html#trackchanges"><tt>trackChanges</tt></a>  is off
 </li>
 
 		
@@ -1373,6 +1569,12 @@ for (var i = 0; i < items.length; i++) {
 <li><tt>options.reuseImages: <tt>Boolean</tt></tt> &mdash; whether raster images with  the same content should only be exported once into the <code>&lt;defs&gt;</code>  element, and placed through <code>&lt;use&gt;</code> elements referencing it &mdash;&nbsp;default: <tt>false</tt></li>
 <li><tt>options.idPrefix: <tt>String</tt></tt> &mdash; a prefix for the ids generated  for definitions such as gradients, clip paths and symbols, to keep  them unique when several exported SVGs are placed in one document &mdash;&nbsp;default: <tt>&rsquo;&rsquo;</tt></li>
 <li><tt>options.reduceAttributes: <tt>Boolean</tt></tt> &mdash; wether to only include  style attributes in the SVG output that differ from their parents,  or to always include them (much faster but leading to redundancies). &mdash;&nbsp;default: <tt>true</tt></li>
+<li>[options.processNode] {Function} the function to process the
+    SVG node made for each exported item, receiving an object with the
+    `item` and its `node`: It can change the node, e.g. to add attributes
+    that Paper.js doesn't export, or return a node to replace it with. It
+    is called before the item's name, style, visibility and data are set
+    on the node, which replace attributes of the same names.</li>
 </ul>
 	
 <ul class="member-list">
@@ -1401,7 +1603,22 @@ for (var i = 0; i < items.length; i++) {
 
 
 	
-	
+	<h4>Example:<span class="description">Export layers as Inkscape layers. Setting the attributes with their namespace has the exported SVG declare it:</span></h4>
+
+
+<pre><code>var ns = 'http://www.inkscape.org/namespaces/inkscape';
+var svg = project.exportSVG({
+    asString: true,
+    processNode: function(arg) {
+        var item = arg.item;
+        if (item instanceof Layer) {
+            arg.node.setAttributeNS(ns, 'inkscape:groupmode', 'layer');
+            if (item.name)
+                arg.node.setAttributeNS(ns, 'inkscape:label', item.name);
+        }
+    }
+});</code></pre>
+
 </div>
 </div>
 </div>
@@ -1415,6 +1632,7 @@ for (var i = 0; i < items.length; i++) {
 <div class="member-text">
 	<p>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 <a href="../classes/Project.html#clear"><tt>project.clear</tt></a>() to do so.</p>
 <p><code>&lt;symbol&gt;</code> elements are imported as <a href="../classes/SymbolDefinition.html"><tt>SymbolDefinition</tt></a> items, and the <code>&lt;use&gt;</code> elements that place them as <a href="../classes/SymbolItem.html"><tt>SymbolItem</tt></a> items. The styles that <code>&lt;use&gt;</code> elements inherit don&rsquo;t reach the symbols&rsquo; content.</p>
+<p>The layers in SVG content that Paper.js exported come back as <a href="../classes/Layer.html"><tt>Layer</tt></a> items inside the imported group. To make the layers of a project&rsquo;s SVG the layers of a project again, add them to it with <code>item.children.slice().forEach(project.addLayer, project)</code>.</p>
 <p>URLs are fetched as they are, so validate URLs that come from untrusted sources first, especially on servers, where they could reach internal addresses.</p>
     <ul class="member-list">
 <h4>Options:</h4>
@@ -1426,6 +1644,13 @@ for (var i = 0; i < items.length; i++) {
 <li><tt>options.onError: <tt>Function</tt></tt> &mdash; the callback function to call if an  error occurs during loading. Only required when loading from external  resources.</li>
 <li><tt>options.insert: <tt>Boolean</tt></tt> &mdash; whether the imported items should  be added to the project that <code>importSVG()</code> is called on &mdash;&nbsp;default: <tt>true</tt></li>
 <li><tt>options.applyMatrix: <tt>Boolean</tt></tt> &mdash; whether the imported items should have their transformation  matrices applied to their contents or not &mdash;&nbsp;default: <tt><a href="../classes/PaperScope.html#settings"><tt>paperScope.settings</tt></a>.applyMatrix</tt></li>
+<li>[options.processItem] {Function} the function to process the
+    item made for each imported SVG element, receiving an object with
+    the `item` and its `node`: It can read attributes that Paper.js
+    doesn't import, or return an item to replace it with. It is called
+    after the element's attributes and data are applied to the item, so
+    it can extend `item.data`. A replacement item doesn't receive them:
+    copy them over from `item` as needed.</li>
 </ul>
 	
 <ul class="member-list">
@@ -1461,7 +1686,24 @@ for (var i = 0; i < items.length; i++) {
 
 
 	
-	
+	<h4>Example:<span class="description">Keep the SVG `class` attribute of items in their data, and export it again:</span></h4>
+
+
+<pre><code>var item = project.importSVG(svg, {
+    processItem: function(arg) {
+        var className = arg.node.getAttribute('class');
+        if (className)
+            arg.item.data.className = className;
+    }
+});
+var exported = project.exportSVG({
+    processNode: function(arg) {
+        var className = arg.item.data.className;
+        if (className)
+            arg.node.setAttribute('class', className);
+    }
+});</code></pre>
+
 </div>
 </div>
 </div>
@@ -1523,7 +1765,7 @@ for (var i = 0; i < items.length; i++) {
 
 <!-- =========================== copyright notice ========================== -->
 <p class="footer">
-Paper.js v0.15.0<br>
+Paper.js v0.17.0<br>
 Copyright &#169; 2011—2026 <a href="http://www.lehni.org" target="_blank">J&uuml;rg Lehni</a> &amp; <a href="http://www.jonathanpuckey.com" target="_blank">Jonathan Puckey</a>. All Rights Reserved.</p>
 <div class="content-end"></div>