paper 0.16.0 → 0.17.0

package/dist/docs/classes/Project.html

@@ -113,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>
 	
 	
 	
@@ -160,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>
@@ -398,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>
@@ -435,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 ================================ -->
@@ -478,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>
@@ -489,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">
@@ -520,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>
     
 	
 	
@@ -528,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>
 
 		
@@ -1595,7 +1765,7 @@ var exported = project.exportSVG({
 
 <!-- =========================== copyright notice ========================== -->
 <p class="footer">
-Paper.js v0.16.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>