scrawl-canvas

<!DOCTYPE html> <html> <head> <title>Position mixin</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;"> <link rel="stylesheet" media="all" href="../../docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <ul id="jump_to"> <li> <a class="large" href="javascript:void(0);">Jump To …</a> <a class="small" href="javascript:void(0);">+</a> <div id="jump_wrapper"> <div id="jump_page_wrapper"> <div id="jump_page"> <a class="source" href="../core/animationloop.html"> ./source/core/animationloop.js </a> <a class="source" href="../core/document.html"> ./source/core/document.js </a> <a class="source" href="../core/events.html"> ./source/core/events.js </a> <a class="source" href="../core/init.html"> ./source/core/init.js </a> <a class="source" href="../core/library.html"> ./source/core/library.js </a> <a class="source" href="../core/random-seed.html"> ./source/core/random-seed.js </a> <a class="source" href="../core/snippets.html"> ./source/core/snippets.js </a> <a class="source" href="../core/userInteraction.html"> ./source/core/userInteraction.js </a> <a class="source" href="../core/utilities.html"> ./source/core/utilities.js </a> <a class="source" href="../factory/action.html"> ./source/factory/action.js </a> <a class="source" href="../factory/anchor.html"> ./source/factory/anchor.js </a> <a class="source" href="../factory/animation.html"> ./source/factory/animation.js </a> <a class="source" href="../factory/bezier.html"> ./source/factory/bezier.js </a> <a class="source" href="../factory/block.html"> ./source/factory/block.js </a> <a class="source" href="../factory/canvas.html"> ./source/factory/canvas.js </a> <a class="source" href="../factory/cell.html"> ./source/factory/cell.js </a> <a class="source" href="../factory/cog.html"> ./source/factory/cog.js </a> <a class="source" href="../factory/color.html"> ./source/factory/color.js </a> <a class="source" href="../factory/conicGradient.html"> ./source/factory/conicGradient.js </a> <a class="source" href="../factory/coordinate.html"> ./source/factory/coordinate.js </a> <a class="source" href="../factory/crescent.html"> ./source/factory/crescent.js </a> <a class="source" href="../factory/element.html"> ./source/factory/element.js </a> <a class="source" href="../factory/emitter.html"> ./source/factory/emitter.js </a> <a class="source" href="../factory/filter.html"> ./source/factory/filter.js </a> <a class="source" href="../factory/filterEngine-bluenoiseData.html"> ./source/factory/filterEngine-bluenoiseData.js </a> <a class="source" href="../factory/filterEngine.html"> ./source/factory/filterEngine.js </a> <a class="source" href="../factory/fontAttributes.html"> ./source/factory/fontAttributes.js </a> <a class="source" href="../factory/gradient.html"> ./source/factory/gradient.js </a> <a class="source" href="../factory/grid.html"> ./source/factory/grid.js </a> <a class="source" href="../factory/group.html"> ./source/factory/group.js </a> <a class="source" href="../factory/imageAsset.html"> ./source/factory/imageAsset.js </a> <a class="source" href="../factory/line.html"> ./source/factory/line.js </a> <a class="source" href="../factory/lineSpiral.html"> ./source/factory/lineSpiral.js </a> <a class="source" href="../factory/loom.html"> ./source/factory/loom.js </a> <a class="source" href="../factory/mesh.html"> ./source/factory/mesh.js </a> <a class="source" href="../factory/net.html"> ./source/factory/net.js </a> <a class="source" href="../factory/noiseAsset.html"> ./source/factory/noiseAsset.js </a> <a class="source" href="../factory/oval.html"> ./source/factory/oval.js </a> <a class="source" href="../factory/palette.html"> ./source/factory/palette.js </a> <a class="source" href="../factory/particle.html"> ./source/factory/particle.js </a> <a class="source" href="../factory/particleForce.html"> ./source/factory/particleForce.js </a> <a class="source" href="../factory/particleHistory.html"> ./source/factory/particleHistory.js </a> <a class="source" href="../factory/particleSpring.html"> ./source/factory/particleSpring.js </a> <a class="source" href="../factory/particleWorld.html"> ./source/factory/particleWorld.js </a> <a class="source" href="../factory/pattern.html"> ./source/factory/pattern.js </a> <a class="source" href="../factory/phrase.html"> ./source/factory/phrase.js </a> <a class="source" href="../factory/picture.html"> ./source/factory/picture.js </a> <a class="source" href="../factory/polygon.html"> ./source/factory/polygon.js </a> <a class="source" href="../factory/polyline.html"> ./source/factory/polyline.js </a> <a class="source" href="../factory/quadratic.html"> ./source/factory/quadratic.js </a> <a class="source" href="../factory/quaternion.html"> ./source/factory/quaternion.js </a> <a class="source" href="../factory/radialGradient.html"> ./source/factory/radialGradient.js </a> <a class="source" href="../factory/rawAsset.html"> ./source/factory/rawAsset.js </a> <a class="source" href="../factory/rdAsset.html"> ./source/factory/rdAsset.js </a> <a class="source" href="../factory/rectangle.html"> ./source/factory/rectangle.js </a> <a class="source" href="../factory/renderAnimation.html"> ./source/factory/renderAnimation.js </a> <a class="source" href="../factory/shape.html"> ./source/factory/shape.js </a> <a class="source" href="../factory/spiral.html"> ./source/factory/spiral.js </a> <a class="source" href="../factory/spriteAsset.html"> ./source/factory/spriteAsset.js </a> <a class="source" href="../factory/stack.html"> ./source/factory/stack.js </a> <a class="source" href="../factory/star.html"> ./source/factory/star.js </a> <a class="source" href="../factory/state.html"> ./source/factory/state.js </a> <a class="source" href="../factory/tetragon.html"> ./source/factory/tetragon.js </a> <a class="source" href="../factory/ticker.html"> ./source/factory/ticker.js </a> <a class="source" href="../factory/tracer.html"> ./source/factory/tracer.js </a> <a class="source" href="../factory/tween.html"> ./source/factory/tween.js </a> <a class="source" href="../factory/unstackedElement.html"> ./source/factory/unstackedElement.js </a> <a class="source" href="../factory/vector.html"> ./source/factory/vector.js </a> <a class="source" href="../factory/videoAsset.html"> ./source/factory/videoAsset.js </a> <a class="source" href="../factory/wheel.html"> ./source/factory/wheel.js </a> <a class="source" href="anchor.html"> ./source/mixin/anchor.js </a> <a class="source" href="asset.html"> ./source/mixin/asset.js </a> <a class="source" href="assetAdvancedFunctionality.html"> ./source/mixin/assetAdvancedFunctionality.js </a> <a class="source" href="assetConsumer.html"> ./source/mixin/assetConsumer.js </a> <a class="source" href="base.html"> ./source/mixin/base.js </a> <a class="source" href="cascade.html"> ./source/mixin/cascade.js </a> <a class="source" href="delta.html"> ./source/mixin/delta.js </a> <a class="source" href="displayShape.html"> ./source/mixin/displayShape.js </a> <a class="source" href="dom.html"> ./source/mixin/dom.js </a> <a class="source" href="entity.html"> ./source/mixin/entity.js </a> <a class="source" href="filter.html"> ./source/mixin/filter.js </a> <a class="source" href="mimic.html"> ./source/mixin/mimic.js </a> <a class="source" href="path.html"> ./source/mixin/path.js </a> <a class="source" href="pattern.html"> ./source/mixin/pattern.js </a> <a class="source" href="pivot.html"> ./source/mixin/pivot.js </a> <a class="source" href="position.html"> ./source/mixin/position.js </a> <a class="source" href="shapeBasic.html"> ./source/mixin/shapeBasic.js </a> <a class="source" href="shapeCurve.html"> ./source/mixin/shapeCurve.js </a> <a class="source" href="shapePathCalculation.html"> ./source/mixin/shapePathCalculation.js </a> <a class="source" href="styles.html"> ./source/mixin/styles.js </a> <a class="source" href="tween.html"> ./source/mixin/tween.js </a> </div> </div> </li> </ul> <ul class="sections"> <li id="section-1"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-1">§</a> </div> <h1 id="position-mixin">Position mixin</h1> <p>This mixin defines the key attributes and functionality of Scrawl-canvas <strong>artefact objects</strong>. </p> <p>We define an artefact as something that can be displayed in a Scrawl-canvas <a href="../factory/stack.html">Canvas</a> or <a href="../factory/stack.html">Stack</a> wrapper - both of which wrap DOM elements in the web page document - <canvas>, and other DOM elements (most commonly a <div> element), respectively.</p> <ul> <li>We call canvas based artefacts <strong>entity objects</strong> - these objects represent a shape, path or image drawn in the canvas. </li> <li>Entitys include: <a href="../factory/block.html">Block</a>; <a href="../factory/grid.html">Grid</a>; <a href="../factory/loom.html">Loom</a>; <a href="../factory/phrase.html">Phrase</a> for text; <a href="../factory/picture.html">Picture</a> for images, videos, etc; <a href="../factory/shape.html">Shape</a>s of various types; and <a href="../factory/wheel.html">Wheel</a>.</li> <li><strong>Other artefacts</strong> live in stack containers. They include nested Stack wrappers, Canvas wrappers (which can exist outside of a stack); and <a href="../factory/element.html">Element</a> wrappers for other direct child elements.</li> </ul> <h5 id="positioning">Positioning</h5> <p>Artefacts break away from the normal flow mechanisms of the HTML document; instead they are explicitly positioned within their containers in a variety of ways:</p> <ul> <li><strong>absolute</strong> positioning - where we give the artefact a coordinate, measured in pixels from the top left corner of the container (<code>[0, 0]</code>, <code>[347, 26.4]</code>, etc). </li> <li><strong>relative</strong> positioning - where we supply the artefact with percentage coordinates, with <code>['0%', '0%']</code> representing the top left corner of the container, and <code>['100%', '100%']</code> its bottom right corner.</li> <li><strong>reference</strong> positioning - this is where an artefact will use another artefact’s <em><strong>current</strong></em> (not given) coordinate to determine its own position. We can reference by <code>pivot</code>, or by <code>mimic</code>, or by <code>path</code>.</li> </ul> <p>Scrawl-canvas uses <a href="../factory/coordinate.html">Coordinate Arrays</a> - <code>[x, y]</code> - for storing artefact coordinates. The <em><strong>Javascript types</strong></em> of the <code>x</code> and <code>y</code> parts of the coordinate can be either Numbers or Strings, and do not need to match each other: <code>['5%', 20]</code> and <code>[10, '15.4%']</code> are as valid as <code>[10, 20]</code> and <code>['5%', '15.4%']</code>.</p> <h5 id="the-artefact-rotation-reflection-point">The artefact ‘rotation-reflection’ point</h5> <p>Every artefact has a <strong>start</strong> coordinate which, by default, is set at the artefact’s top-left corner - even for Wheels and Shapes! </p> <ul> <li>When we rotate an artefact, we rotate it around this coordinate. When we <em><strong>flip</strong></em> entity artefacts, we flip them around the artefact’s local horizontal or vertical axis drawn through this coordinate. </li> <li>Thus what we call a ‘start’ coordinate is in fact the artefact’s <strong>Rotation-Reflection</strong> point.</li> </ul> <p>The R-R point does not need to be at the artefact’s top-left corner. We can move it by giving the artefact a <strong>handle</strong> coordinate - a distance measured from the artefact’s top-left corner. Just as for the start coordinate, we can set the handle coordinate using absolute, relative or reference values:</p> <ul> <li><strong>absolute</strong> handles - where we give the artefact a distance, measured in pixels from its top left corner . </li> <li><strong>relative</strong> handles - where we supply the artefact with percentage distances measured against the artefact’s own dimensions.</li> <li><strong>reference</strong> handles.</li> <li>In all cases, <em><strong>the distancing effect is along the artefact’s local horizontal and vertical axes</strong></em> - if the artefact is rotated, then those axes will not be perpendicular to the containing Canvas or Stack axes.</li> </ul> <p>Normally this is enough information to position an artefact in its container. However there may be times when we need to move the artefact’s R-R point a given distance along the container axes. We can achieve this by giving the artefact an <strong>offset</strong> coordinate.</p> <ul> <li><strong>absolute</strong> offsets - where we give the artefact a distance, measured in pixels from its top left corner. </li> <li><strong>relative</strong> offsets - where we supply the artefact with percentage distances measured against the <em><strong>container’s dimensions</strong></em>.</li> <li><strong>reference</strong> offsets.</li> </ul> <p>An artefact can have both a handle and an offset; handle distances move the R-R point along the artefact’s axes (which may be diagonal lines), while offsets move it along the container’s axes.</p> <h5 id="artefact-dimensions">Artefact dimensions</h5> <p>Another use for Coordinate Arrays is to <strong>set the artefact’s dimensions - their width and height values</strong>. In this case we can think of the coordinate in terms of <code>[w, h]</code>. All artefacts, except Shape and Loom entitys, require dimension data.</p> <p>Just as for positioning data, an artefact’s dimensions data can be supplied in absolute, relative or reference terms:</p> <ul> <li><strong>absolute</strong> dimensions - where we give the artefact a width and height, measured in pixels from its top left corner. </li> <li><strong>relative</strong> dimensions - where we supply the artefact with percentage widths and height values, measured against the <em><strong>container’s dimensions</strong></em>.</li> <li><strong>reference</strong> dimensions.</li> </ul> <h5 id="artefact-pseudo-attributes">Artefact pseudo-attributes</h5> <p>Scrawl-canvas uses the following pseudo-attributes to make working with Coordinates easier:</p> <ul> <li><strong>startX</strong> and <strong>startY</strong> - for getting and setting the <code>start</code> (R-R) Coordinate values</li> <li><strong>handleX</strong> and <strong>handleY</strong> - for getting and setting the <code>handle</code> Coordinate values</li> <li><strong>offsetX</strong> and <strong>offsetY</strong> - for getting and setting the <code>offset</code> Coordinate values</li> <li><strong>width</strong> and <strong>height</strong> - for getting and setting the <code>dimensions</code> Coordinate values</li> </ul> <p>Scrawl-canvas also supports the following <em><strong>pseudo-values</strong></em>, which can be used when setting <strong>relative</strong> coordinates:</p> <ul> <li><code>['left', 'top']</code> == <code>['0%', '0%']</code></li> <li><code>['center', 'center']</code> == <code>['50%', '50%']</code></li> <li><code>['bottom', 'right']</code> == <code>['100%', '100%']</code></li> </ul> <pre><code><span class="hljs-comment">// The following code creates a block entity</span> <span class="hljs-comment">// - half the width and height of its canvas</span> <span class="hljs-comment">// - positioned in the middle of the canvas:</span> scrawl.<span class="hljs-title function_">makeBlock</span>({ <span class="hljs-attr">name</span>: <span class="hljs-string">'my-block'</span>, <span class="hljs-attr">startX</span>: <span class="hljs-string">'center'</span>, <span class="hljs-attr">startY</span>: <span class="hljs-string">'center'</span>, <span class="hljs-attr">handleX</span>: <span class="hljs-string">'center'</span>, <span class="hljs-attr">handleY</span>: <span class="hljs-string">'center'</span>, <span class="hljs-attr">width</span>: <span class="hljs-string">'50%'</span>, <span class="hljs-attr">height</span>: <span class="hljs-string">'50%'</span>, <span class="hljs-attr">lineWidth</span>: <span class="hljs-number">10</span>, <span class="hljs-attr">fillStyle</span>: <span class="hljs-string">'blue'</span>, <span class="hljs-attr">strokeStyle</span>: <span class="hljs-string">'red'</span>, <span class="hljs-attr">method</span>: <span class="hljs-string">'fillThenDraw'</span>, }); </code></pre> <h5 id="referencing-other-artefacts">Referencing other artefacts</h5> <p>Scrawl-canvas allows an artefact to reference other artefacts. The referenced objects supply data back to the first artefact, which it then uses to update its position and dimensions. </p> <ul> <li>This all happens automatically once the reference is set up, with updates occuring as part of the Scrawl-canvas <strong>Display cycle</strong>.</li> <li>To move a group of artefacts as a single unit, we can set up one as the reference artefact, with the rest using handles and offsets to supply distancing data from the reference. Updates to the reference artefact will now be transmitted automatically to all artefacts using it as their <code>pivot</code> or <code>mimic</code>.</li> </ul> <p>We <strong>create a reference</strong> by setting the value of one or more of the following attributes to a reference artefact’s name-String, or to the object itself:</p> <ul> <li><code>pivot</code> - once set, we can then use the referenced artefact’s <strong>start</strong> coordinate as this artefact’s start value. With appropriate flags set, we can add this artefact’s <strong>handle</strong> and <strong>offset</strong> coordinates to the start value.</li> <li><code>mimic</code> - extends the ‘pivot’ concept to include dimensions, alongside adding this artefact’s data to the referenced artefact’s data in various ways.</li> <li><code>path</code> - use a Shape entity’s path to determine this artefact’s position and rotation values.</li> </ul> <p>We <strong>action a reference</strong> by setting this artefact’s <code>lockTo</code> Array attribute. Ther lock array is similar to coordinate Arrays: it is a two-element array of Strings in the form <code>[x-lock, y-lock]</code>. Five lock strings are supported:</p> <ul> <li><code>start</code> - use this artefact’s own start (and other) values</li> <li><code>pivot</code> - use the pivot reference artefact’s start (and other) values</li> <li><code>mimic</code> - use the mimic reference artefact’s start (and other) values</li> <li><code>path</code> - use the Shape entity’s path to calculate this artefact’s start (and rotation) values</li> <li><code>mouse</code> - use the mouse/touch cursor’s current position as the reference for this artefact’s start value</li> </ul> <p>The <strong>lockTo</strong> Array supports the pseudo-attributes <strong>lockXTo</strong> and <strong>lockYTo</strong> to make working with it easier.</p> <ul> <li>Setting <code>lockTo</code> sets both elements of the Array to the supplied String</li> <li><code>lockXTo</code> and <code>lockYTo</code> allow us to separate the x and y coordinates</li> </ul> <p>For instance if we set the lock to <code>['start', 'mouse']</code> we can make the artefact track the mouse across the container along an (invisible) vertical line, whose position is determined by the artefact’s x coordinate value.</p> <h5 id="artefact-rotation">Artefact rotation</h5> <p>Scrawl-canvas artefacts can be rotated around their <strong>Rotation-Reflection point</strong>: </p> <ul> <li>Entity artefacts, being representations of 2-dimensional graphical shapes drawn on a <canvas> element, are restricted to rotating around the R-R point’s <em><strong>z-axis</strong></em>.</li> <li>Other artefacts, when part of a Stack container, can be rotated in 3 dimensions along the R-R point’s <em><strong>x-axis</strong></em>, <em><strong>y-axis</strong></em> and <em><strong>z-axis</strong></em>.</li> </ul> <p>Scrawl canvas measures rotations in <strong>degrees</strong>, not radians. An artefact’s rotation values are stored in the following attributes:</p> <ul> <li><strong>roll</strong> - for <code>z-axis</code> rotations</li> <li><strong>yaw</strong> - for <code>y-axis</code> rotations</li> <li><strong>pitch</strong> - for <code>x-axis</code> rotations</li> </ul> <p>These <strong>euler</strong> attributes are named after the <a href="https://en.wikipedia.org/wiki/Aircraft_principal_axes">Aircraft principal axes</a> - mainly because I find it difficult to keep the mathematical representations in my head when thinking about rotations in 3 dimensions, but an image of an aircraft is a lot easier to visualize.</p> <ul> <li>Internally, Scrawl-canvas stores rotational data in <a href="../factory/quaternion.html">Quaternion objects</a> rather than in matrices.</li> </ul> <p>Instead of 3D rotations, entity artefacts have two Boolean flags - <strong>flipReverse</strong>, <strong>flipUpend</strong> - which determine the orientation of the entity when it stamps itself on the display. </p> <ul> <li>a <code>reversed</code> entity is effectively flipped 180° around a vertical line passing through that entity’s rotation-reflection (start) point - a face looking to the right will now look to the left</li> <li>an <code>upended</code> entity is effectively flipped 180° around a horizontal line passing through that entity’s rotation-reflection (start) point - a normal face will now appear upside-down</li> </ul> <p>We can <em><strong>emulate 3D rotations for Picture entity artefacts</strong></em> using the <a href="../factory/loom.html">Loom entity</a> - see Demo <a href="../../demo/dom-015.html">DOM-015</a> for an example of this in action.</p> <h5 id="collision-detection">Collision detection</h5> <p>Collision detection functionality - beyond mouse drag-and-drop - has been removed from Scrawl-canvas since v8.2.0</p> </div> </li> <li id="section-2"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-2">§</a> </div> <h4 id="imports">Imports</h4> </div> <div class="content"><div class='highlight'><pre><span class="hljs-keyword">import</span> { artefact, group, tween, particle } <span class="hljs-keyword">from</span> <span class="hljs-string">'../core/library.js'</span>; <span class="hljs-keyword">import</span> { λ<span class="hljs-literal">null</span>, mergeOver, isa_obj, xt, xta, xto, xtGet, addStrings, pushUnique, isa_boolean, Ωempty } <span class="hljs-keyword">from</span> <span class="hljs-string">'../core/utilities.js'</span>; <span class="hljs-keyword">import</span> { currentCorePosition } <span class="hljs-keyword">from</span> <span class="hljs-string">'../core/userInteraction.js'</span>; <span class="hljs-keyword">import</span> { makeCoordinate, requestCoordinate, releaseCoordinate } <span class="hljs-keyword">from</span> <span class="hljs-string">'../factory/coordinate.js'</span>; <span class="hljs-keyword">import</span> { requestCell, releaseCell } <span class="hljs-keyword">from</span> <span class="hljs-string">'../factory/cell.js'</span>;</pre></div></div> </li> <li id="section-3"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-3">§</a> </div> <h4 id="export-function">Export function</h4> </div> <div class="content"><div class='highlight'><pre><span class="hljs-keyword">export</span> <span class="hljs-keyword">default</span> <span class="hljs-keyword">function</span> (<span class="hljs-params">P = Ωempty</span>) {</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-4">§</a> </div> <h4 id="shared-attributes">Shared attributes</h4> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-keyword">let</span> defaultAttributes = {</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-5">§</a> </div> <p><strong>group</strong> - every Scrawl-canvas artefact should belong to at least one Group, and can belong to more than one Group. Groups can be used for a variety of purposes, and play a major role in the <strong>Display cycle</strong> and in <strong>collision detection</strong>.</p> <ul> <li>Most group-related functionality takes place elsewhere. An artefact’s <code>group</code> attribute is used mainly as a ‘convenience handle’, to make moving an artefact from one Group to another a bit easier.</li> <li>As part of an artefact’s initialization, the code will assign the artefact to a Group. We can indicate which Group to assign the new artefact to by setting the argument attribute to the Group’s name attribute String, or to the Group itself - the set code will automatically update this attribute to a reference to the Group object:</li> </ul> <pre><code><span class="hljs-keyword">let</span> myGroup = scrawl.<span class="hljs-title function_">buildGroup</span>({ <span class="hljs-attr">name</span>: <span class="hljs-string">'my-first-group'</span>, }); <span class="hljs-keyword">let</span> myBlock = scrawl.<span class="hljs-title function_">makeBlock</span>({ <span class="hljs-attr">group</span>: myGroup, }); </code></pre> <ul> <li>Similarly the <strong>set</strong> function’s object argument can accept a name String, or the new group’s object itself:</li> </ul> <pre><code>myBlock.<span class="hljs-title function_">set</span>({ <span class="hljs-attr">group</span>: <span class="hljs-string">'my-first-group'</span>, }); </code></pre> <ul> <li>If no group value is supplied when building a new <strong>entity</strong>, then the <em><strong>current group</strong></em> will be assigned as the entity’s group. This is a Scrawl-canvas ‘global’ value which will update whenever the user sets a Canvas wrapper as the current canvas:</li> </ul> <pre><code>scrawl.<span class="hljs-title function_">setCurrentCanvas</span>(<span class="hljs-string">'my-other-canvas'</span>); </code></pre> <ul> <li>For some Canvas and Stack wrappers, the value of their group attribute will be set to <code>root</code> - this indicates that the wrapper’s DOM element is not contained within another Stack.</li> <li>TODO: we need to decide whether we want a user-available scrawl.setCurrentStack function and, if yes, how that will impact on the core/document.js <strong>currentGroup</strong> variable exported by that module - given that we will then have both currentStack and currentCanvas variables, but only one currentGroup variable shared between them.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">group</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-6">§</a> </div> <p>The <strong>visibility</strong> attribute is a boolean flag (default: true); when the flag is set, the Display cycle functionality will run on the artefact. If the attribute’s value is false, then the Display cycle functionality will ignore the artefact. This has the following effects:</p> <ul> <li>for DOM-based artefacts, the dom element will have its CSS tweaked to hide the element (<code>display: block</code> switches to <code>display: none</code>).</li> <li>for canvas-based entitys, the entity will be ignored during the Display cycle’s <code>compile</code> step.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">visibility</span>: <span class="hljs-literal">true</span>,</pre></div></div> </li> <li id="section-7"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-7">§</a> </div> <p>The <strong>order</strong> pseudo-attribute - an integer Number (default: 0) - determines the order in which an artefact will be processed as part of a Group. Since v8.9.2 this attribute has been broken into two - <strong>calculateOrder</strong> and <strong>stampOrder</strong> so that the processing order of artefacts can be different in the <code>prestamp</code> and <code>stamp</code> parts of the <code>compile</code> step of the Display cycle.</p> <ul> <li>Artefacts with higher <code>calculateOrder</code> values will be processed after those with lower values - this is important for situations where an artefact relies on others for its positioning data (when it pivots, mimics other artefacts, or uses a path-pased artefact for position/rotation data), thus needs to calculate its data after the reference artefact has completed its calculations.</li> <li>Artefacts with higher <code>stampOrder</code> values will display (be stamped) over artefacts with lower <code>stampOrder</code> values.</li> <li>Note that Group objects also have an order attribute: all artefacts in a Group with a lower order value will be processed before those with a higher order value.</li> <li>Cell wrappers (a Canvas wrapper can have more than one Cell) have <code>ccompileOrder</code> and <code>showOrder</code> attributes which do similar work.</li> <li>Finally, Animation objects (generated from <code>makeRender</code>, <code>makeAnimation</code>) can be given <code>order</code> values.</li> <li><em><strong>If the display of an artefact does not appear to be following the order value it has been given</strong></em>, the problem may lie in either the order values assigned to that artefact’s Group, or host (Cell, Canvas, Stack), or even the Animation object that contributes to the Display cycle.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">calculateOrder</span>: <span class="hljs-number">0</span>, <span class="hljs-attr">stampOrder</span>: <span class="hljs-number">0</span>,</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-8">§</a> </div> <p>The <strong>start</strong> attribute represents an artefact’s <em><strong>Rotation-Reflexion point</strong></em>, and is held in an <code>[x, y]</code> Coordinate Array. The default values are <code>[0, 0]</code>, placing the artifact at the container object’s (Cell, Stack) top-left corner.</p> <pre><code><span class="hljs-keyword">let</span> myBlock = scrawl.<span class="hljs-title function_">makeBlock</span>({ <span class="hljs-attr">startX</span>: <span class="hljs-number">20</span>, <span class="hljs-attr">startY</span>: <span class="hljs-string">'center'</span>, }); myBlock.<span class="hljs-title function_">set</span>({ <span class="hljs-attr">start</span>: [-<span class="hljs-number">100</span>, <span class="hljs-string">'-12%'</span>], }); myBlock.<span class="hljs-title function_">set</span>({ <span class="hljs-attr">start</span>: { <span class="hljs-attr">x</span>: <span class="hljs-string">'left'</span>, <span class="hljs-attr">y</span>: <span class="hljs-number">388.5</span>, }, }); <span class="hljs-comment">// Don't use string labels ('top', 'left', etc) when delta setting</span> myBlock.<span class="hljs-title function_">setDelta</span>({ <span class="hljs-attr">startX</span>: <span class="hljs-string">'-0.05%'</span>, }); myBlock.<span class="hljs-title function_">setDelta</span>({ <span class="hljs-attr">start</span>: [<span class="hljs-number">1</span>, <span class="hljs-string">'0.5%'</span>], }); </code></pre> <ul> <li>Start values DO NOT respect the artefact’s <code>scale</code> attribute.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">start</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-9">§</a> </div> <p>The <strong>handle</strong> attribute represents a distance from the artefact’s <em><strong>Rotation-Reflexion</strong></em> point, measured along the <em><strong>artefact’s local axes</strong></em>. It is held in an <code>[x, y]</code> Coordinate Array. The default values are <code>[0, 0]</code>.</p> <ul> <li>Handle values WILL respect the artefact’s <code>scale</code> attribute.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">handle</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-10">§</a> </div> <p>The <strong>offset</strong> attribute represents an offset from the artefact’s <em><strong>Rotation-Reflexion</strong></em> point, measured along the <em><strong>container’s axes</strong></em>. It is held in an <code>[x, y]</code> Coordinate Array. The default values are <code>[0, 0]</code>.</p> <ul> <li>Offset values DO NOT respect the artefact’s <strong>scale</strong> attribute.</li> <li>the <em>pseudo-values</em> <code>top</code>, <code>center</code>, etc have no meaning in the context of offsets.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">offset</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-11">§</a> </div> <p>The <strong>dimensions</strong> attribute represents the artefact’s <strong>width</strong> and <strong>height</strong>. It is held in a <code>[w, h]</code> Coordinate Array. The default values vary between different types of artefact.</p> <ul> <li>Dimensions values WILL respect the artefact’s <code>scale</code> attribute.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">dimensions</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-12">§</a> </div> <p><strong>pivoted</strong> - internal Array holding details of the artefacts using this artefact as their pivot reference.</p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">pivoted</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-13">§</a> </div> <p><strong>mimicked</strong> - internal Array holding details of the artefacts using this artefact as their mimic reference.</p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">mimicked</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-14"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-14">§</a> </div> <p><strong>particle</strong> - attribute to store any particle the artefact mey be using for its position reference</p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">particle</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-15">§</a> </div> <p><strong>lockTo</strong> - <code>[x-lock, y-lock]</code> Array; locks can be set to: <code>start</code> (the default), <code>pivot</code>, <code>path</code>, <code>mimic</code>, <code>particle</code>, or <code>mouse</code>.</p> <ul> <li>The lock values can be set individually using the pseudo-attributes <strong>lockXTo</strong> and <strong>lockYTo</strong>.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">lockTo</span>: <span class="hljs-literal">null</span>,</pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-16">§</a> </div> <p><strong>bringToFrontOnDrag</strong> - flag which, when set (default), will force the artefact currently being dragged to appear on top of other artefacts</p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">bringToFrontOnDrag</span>: <span class="hljs-literal">true</span>,</pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-17">§</a> </div> <p><strong>ignoreDragForX</strong>, <strong>ignoreDragForY</strong> - flag which, when set, will skip the drag effects for that particular direction</p> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">ignoreDragForX</span>: <span class="hljs-literal">false</span>, <span class="hljs-attr">ignoreDragForY</span>: <span class="hljs-literal">false</span>,</pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-18">§</a> </div> <p>All artefacts (except compound entities such as Loom) can be scaled by setting their <strong>scale</strong> attribute to an appropriate float Number value:</p> <ul> <li>A value of <strong>0</strong> effectively makes the artefact disappear from the display (though setting the artefact’s <strong>visibility</strong> flag to false is a more efficient approach).</li> <li>Scale value <strong>less than 1</strong> will shrink the artefact around its rotation-reflection point.</li> <li>Setting the value to <strong>1</strong> (the default) removes all scaling effects on the artefact.</li> <li>Values <strong>greater than 1</strong> will expand the artefact around its rotation-reflection point.</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">scale</span>: <span class="hljs-number">1</span>,</pre></div></div> </li> <li id="section-19"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-19">§</a> </div> <p><strong>roll</strong> - float Number representing the artefact’s rotation around the <code>z-axis</code> of its <em><strong>Rotation-Reflection point</strong></em>.</p> <ul> <li>values represent <em><strong>degrees</strong></em>, not radians.</li> <li>Some effort is made in the code to keep this value within the bounds of <code>-360</code> and <code>+360</code>. Value is measured in degrees (not radians!)</li> </ul> </div> <div class="content"><div class='highlight'><pre> <span class="hljs-attr">roll</span>: <span class="hljs-number">0</span>,</pre></div></div> </li> <li id="section-20"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-20">§</a> </div> <h5 id="animation-speed">Animation speed</h5> <p>Scrawl-canvas assumes that an artefact will be <em>ready for anything</em>. However if we know