scrawl-canvas

<!DOCTYPE html> <html> <head> <title>Canvas factory</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="action.html"> ./source/factory/action.js </a> <a class="source" href="anchor.html"> ./source/factory/anchor.js </a> <a class="source" href="animation.html"> ./source/factory/animation.js </a> <a class="source" href="bezier.html"> ./source/factory/bezier.js </a> <a class="source" href="block.html"> ./source/factory/block.js </a> <a class="source" href="canvas.html"> ./source/factory/canvas.js </a> <a class="source" href="cell.html"> ./source/factory/cell.js </a> <a class="source" href="cog.html"> ./source/factory/cog.js </a> <a class="source" href="color.html"> ./source/factory/color.js </a> <a class="source" href="conicGradient.html"> ./source/factory/conicGradient.js </a> <a class="source" href="coordinate.html"> ./source/factory/coordinate.js </a> <a class="source" href="crescent.html"> ./source/factory/crescent.js </a> <a class="source" href="element.html"> ./source/factory/element.js </a> <a class="source" href="emitter.html"> ./source/factory/emitter.js </a> <a class="source" href="filter.html"> ./source/factory/filter.js </a> <a class="source" href="filterEngine-bluenoiseData.html"> ./source/factory/filterEngine-bluenoiseData.js </a> <a class="source" href="filterEngine.html"> ./source/factory/filterEngine.js </a> <a class="source" href="fontAttributes.html"> ./source/factory/fontAttributes.js </a> <a class="source" href="gradient.html"> ./source/factory/gradient.js </a> <a class="source" href="grid.html"> ./source/factory/grid.js </a> <a class="source" href="group.html"> ./source/factory/group.js </a> <a class="source" href="imageAsset.html"> ./source/factory/imageAsset.js </a> <a class="source" href="line.html"> ./source/factory/line.js </a> <a class="source" href="lineSpiral.html"> ./source/factory/lineSpiral.js </a> <a class="source" href="loom.html"> ./source/factory/loom.js </a> <a class="source" href="mesh.html"> ./source/factory/mesh.js </a> <a class="source" href="net.html"> ./source/factory/net.js </a> <a class="source" href="noiseAsset.html"> ./source/factory/noiseAsset.js </a> <a class="source" href="oval.html"> ./source/factory/oval.js </a> <a class="source" href="palette.html"> ./source/factory/palette.js </a> <a class="source" href="particle.html"> ./source/factory/particle.js </a> <a class="source" href="particleForce.html"> ./source/factory/particleForce.js </a> <a class="source" href="particleHistory.html"> ./source/factory/particleHistory.js </a> <a class="source" href="particleSpring.html"> ./source/factory/particleSpring.js </a> <a class="source" href="particleWorld.html"> ./source/factory/particleWorld.js </a> <a class="source" href="pattern.html"> ./source/factory/pattern.js </a> <a class="source" href="phrase.html"> ./source/factory/phrase.js </a> <a class="source" href="picture.html"> ./source/factory/picture.js </a> <a class="source" href="polygon.html"> ./source/factory/polygon.js </a> <a class="source" href="polyline.html"> ./source/factory/polyline.js </a> <a class="source" href="quadratic.html"> ./source/factory/quadratic.js </a> <a class="source" href="quaternion.html"> ./source/factory/quaternion.js </a> <a class="source" href="radialGradient.html"> ./source/factory/radialGradient.js </a> <a class="source" href="rawAsset.html"> ./source/factory/rawAsset.js </a> <a class="source" href="rdAsset.html"> ./source/factory/rdAsset.js </a> <a class="source" href="rectangle.html"> ./source/factory/rectangle.js </a> <a class="source" href="renderAnimation.html"> ./source/factory/renderAnimation.js </a> <a class="source" href="shape.html"> ./source/factory/shape.js </a> <a class="source" href="spiral.html"> ./source/factory/spiral.js </a> <a class="source" href="spriteAsset.html"> ./source/factory/spriteAsset.js </a> <a class="source" href="stack.html"> ./source/factory/stack.js </a> <a class="source" href="star.html"> ./source/factory/star.js </a> <a class="source" href="state.html"> ./source/factory/state.js </a> <a class="source" href="tetragon.html"> ./source/factory/tetragon.js </a> <a class="source" href="ticker.html"> ./source/factory/ticker.js </a> <a class="source" href="tracer.html"> ./source/factory/tracer.js </a> <a class="source" href="tween.html"> ./source/factory/tween.js </a> <a class="source" href="unstackedElement.html"> ./source/factory/unstackedElement.js </a> <a class="source" href="vector.html"> ./source/factory/vector.js </a> <a class="source" href="videoAsset.html"> ./source/factory/videoAsset.js </a> <a class="source" href="wheel.html"> ./source/factory/wheel.js </a> <a class="source" href="../mixin/anchor.html"> ./source/mixin/anchor.js </a> <a class="source" href="../mixin/asset.html"> ./source/mixin/asset.js </a> <a class="source" href="../mixin/assetAdvancedFunctionality.html"> ./source/mixin/assetAdvancedFunctionality.js </a> <a class="source" href="../mixin/assetConsumer.html"> ./source/mixin/assetConsumer.js </a> <a class="source" href="../mixin/base.html"> ./source/mixin/base.js </a> <a class="source" href="../mixin/cascade.html"> ./source/mixin/cascade.js </a> <a class="source" href="../mixin/delta.html"> ./source/mixin/delta.js </a> <a class="source" href="../mixin/displayShape.html"> ./source/mixin/displayShape.js </a> <a class="source" href="../mixin/dom.html"> ./source/mixin/dom.js </a> <a class="source" href="../mixin/entity.html"> ./source/mixin/entity.js </a> <a class="source" href="../mixin/filter.html"> ./source/mixin/filter.js </a> <a class="source" href="../mixin/mimic.html"> ./source/mixin/mimic.js </a> <a class="source" href="../mixin/path.html"> ./source/mixin/path.js </a> <a class="source" href="../mixin/pattern.html"> ./source/mixin/pattern.js </a> <a class="source" href="../mixin/pivot.html"> ./source/mixin/pivot.js </a> <a class="source" href="../mixin/position.html"> ./source/mixin/position.js </a> <a class="source" href="../mixin/shapeBasic.html"> ./source/mixin/shapeBasic.js </a> <a class="source" href="../mixin/shapeCurve.html"> ./source/mixin/shapeCurve.js </a> <a class="source" href="../mixin/shapePathCalculation.html"> ./source/mixin/shapePathCalculation.js </a> <a class="source" href="../mixin/styles.html"> ./source/mixin/styles.js </a> <a class="source" href="../mixin/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="canvas-factory">Canvas factory</h1> Scrawl-canvas mediates between its system and <canvas> elements in the DOM using Canvas wrapper objects. The wrapper includes a handle to the visible element, but most work is done on a second <canvas> element - the base Cell - which is not part of the DOM, thus excluded from a browser’s Document interface (including events). The Canvas factory is not used directly; the factory is not exported as part of the <a href="../scrawl.html">scrawl object</a> during Scrawl-canvas initialization. Instead, wrappers can be created for DOM-based <canvas> elements using the following scrawl functions: <ul> <li><code>scrawl.getCanvas</code> - locates a <canvas> element in the DOM and creates a wrapper for it.</li> <li><code>scrawl.addCanvas</code> - generates a new <canvas> element, creates a wrapper for it, then adds it to the DOM.</li> </ul> During initialization Scrawl-canvas will search the DOM tree and automatically create Canvas wrappers for all the <canvas> elements it discovers. The first <canvas> element discovered becomes the current canvas; all entitys created without a specified <code>group</code> attribute will be assigned to that element’s wrapper’s base Cell’s Group object. We can change the current canvas by invoking the <code>scrawl.setCurrentCanvas</code> function. A canvas wrapper can include more than one Cell object. It will always include a base Cell object; additional Cells can be treated as cell layers and/or normal artefacts contributing to the final display. During their creation, Canvas wrappers will directly modify the DOM, adding <div> and <nav> elements to it. These new elements are used as holds where the Canvas will store data and text, mainly to expose <a> links and blocks which expose scene details to assistive technologies (accessibility). These additional elements have zero dimensions and should not affect the layout or painting of the rest of the web page. Canvas wrapper objects use the base, position, dom and anchor mixins. Thus Canvas wrappers are also artefact objects: if a <canvas> element is a direct child of a Stack wrapper’s element then it can be positioned, dimensioned and rotated like any other artefact. By default, all Canvas wrappers will track mouse/touch movements across their <canvas> elements, supplying this data to constituent Cell objects and artefacts as-and-when-required. Canvas wrappers are used by Scrawl-canvas to invoke the Display cycle cascade. As such, they include <code>clear</code>, <code>compile</code>, <code>show</code> and <code>render</code> functions to manage the Display cycle. These functions are asynchronous, returning Promises. Canvas wrappers are excluded from the Scrawl-canvas packet system; they cannot be saved or cloned. Killing a Canvas wrapper will remove its <canvas> element from the DOM, alongside the additional elements added to the DOM during Canvas creation. </div> </li> <li id="section-2"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-2">§</a> </div> <h4 id="demos">Demos:</h4> <ul> <li>All canvas and packets demos, and a few of the stack demos, include Canvas wrapper functionality - most of which happens behind the scenes and does not need to be directly coded. </li> <li><a href="../../demo/canvas-009.html">Canvas-009</a> - Pattern styles; Entity web link anchors; Dynamic accessibility</li> <li><a href="../../demo/dom-011.html">DOM-011</a> - Canvas controller <code>fit</code> attribute; Cell positioning (mouse)</li> <li><a href="../../demo/dom-012.html">DOM-012</a> - Add and remove (kill) Scrawl-canvas canvas elements programmatically</li> </ul> </div> </li> <li id="section-3"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-3">§</a> </div> <h4 id="imports">Imports</h4> </div> <div class="content"><div class='highlight'><pre>import { cell, constructors, artefact, group } from '../core/library.js'; import { rootElements, setRootElementsSort, setCurrentCanvas, domShow, scrawlCanvasHold } from '../core/document.js'; import { mergeOver, pushUnique, removeItem, xt, λthis, λnull, Ωempty } from '../core/utilities.js'; import { uiSubscribedElements } from '../core/userInteraction.js'; import { makeState } from './state.js'; import { makeCell } from './cell.js'; import { makeCoordinate } from './coordinate.js'; import baseMix from '../mixin/base.js'; import domMix from '../mixin/dom.js'; import displayMix from '../mixin/displayShape.js';</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-4">§</a> </div> <h4 id="canvas-constructor">Canvas constructor</h4> </div> <div class="content"><div class='highlight'><pre>const Canvas = function (items = Ωempty) { let g, el; this.makeName(items.name); this.register(); this.initializePositions(); this.dimensions[0] = 300; this.dimensions[1] = 150; this.pathCorners = []; this.css = {}; this.here = {}; this.perspective = { x: '50%', y: '50%', z: 0 }; this.dirtyPerspective = true; this.initializeDomLayout(items); this.set(this.defs); if (!items.label) items.label = `${this.name} canvas element`; this.initializeDisplayShapeActions(); this.initializeAccessibility(); this.set(items); this.cleanDimensions(); el = this.domElement; if (!el) this.cleanDimensions(); else { this.engine = this.domElement.getContext('2d'); this.state = makeState({ engine: this.engine });</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-5">§</a> </div> set up additional cells array </div> <div class="content"><div class='highlight'><pre> this.cells = []; this.cellBatchesClear = []; this.cellBatchesCompile = []; this.cellBatchesShow = []; let baseWidth = this.currentDimensions[0], baseHeight = this.currentDimensions[1]; const ds = el.dataset; if (ds.isResponsive) { el.style.width = '100%'; el.style.height = '100%'; let baseMatches = true; if (ds.baseWidth && ds.baseHeight) { baseMatches = false; baseWidth = parseFloat(ds.baseWidth); baseHeight = parseFloat(ds.baseHeight); } this.set({ checkForResize: true, baseMatchesCanvasDimensions: baseMatches, ignoreCanvasCssDimensions: true, fit: ds.fit || this.fit, }); this.cleanDimensions(); }</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-6">§</a> </div> setup base cell </div> <div class="content"><div class='highlight'><pre> const cellArgs = { name: `${this.name}_base`, element: false, width: baseWidth, height: baseHeight, cleared: true, compiled: true, shown: false, isBase: true, host: this.name, controller: this, order: 10, }; if (ds.baseClearAlpha) cellArgs.clearAlpha = parseFloat(ds.baseClearAlpha); if (ds.baseBackgroundColor) cellArgs.backgroundColor = ds.baseBackgroundColor; this.base = this.buildCell(cellArgs);</pre></div></div> </li> <li id="section-7"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-7">§</a> </div> even if it is a child of a stack element, it needs to be recorded as a ‘rootElement’ </div> <div class="content"><div class='highlight'><pre> pushUnique(rootElements, this.name); setRootElementsSort();</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-8">§</a> </div> <h5 id="accessibility">Accessibility</h5> if (!el.getAttribute(‘role’)) el.setAttribute(‘role’, ‘img’); </div> <div class="content"><div class='highlight'><pre> const navigation = document.createElement('nav'); navigation.id = `${this.name}-navigation`; navigation.style.width = '0px'; navigation.style.height = '0px'; navigation.style.maxWidth = '0px'; navigation.style.maxHeight = '0px'; navigation.style.border = '0px'; navigation.style.padding = '0px'; navigation.style.margin = '0px'; navigation.style.overflow = 'hidden'; this.navigation = navigation; el.appendChild(navigation); const textHold = document.createElement('div'); textHold.id = `${this.name}-text-hold`; textHold.style.width = '0px'; textHold.style.height = '0px'; textHold.style.maxWidth = '0px'; textHold.style.maxHeight = '0px'; textHold.style.border = '0px'; textHold.style.padding = '0px'; textHold.style.margin = '0px'; textHold.style.overflow = 'hidden'; this.textHold = textHold; el.appendChild(textHold); const ariaLabel = document.createElement('div'); ariaLabel.id = `${this.name}-ARIA-label`; ariaLabel.textContent = this.label; this.ariaLabelElement = ariaLabel; scrawlCanvasHold.appendChild(ariaLabel); el.setAttribute('aria-labelledby', ariaLabel.id); el.setAttribute('aria-live', 'polite'); const ariaDescription = document.createElement('div'); ariaDescription.id = `${this.name}-ARIA-description`; ariaDescription.textContent = this.description; this.ariaDescriptionElement = ariaDescription; scrawlCanvasHold.appendChild(ariaDescription); el.setAttribute('aria-describedby', ariaDescription.id); el.setAttribute('aria-live', 'polite'); this.cleanAria(); } this.dirtyCells = true; this.apply(); this.dirtyDomDimensions = true; if (items.setAsCurrentCanvas) this.setAsCurrentCanvas(); return this; };</pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-9">§</a> </div> <h4 id="canvas-prototype">Canvas prototype</h4> </div> <div class="content"><div class='highlight'><pre>let P = Canvas.prototype = Object.create(Object.prototype); P.type = 'Canvas'; P.lib = 'canvas'; P.isArtefact = true; P.isAsset = false;</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-10">§</a> </div> <h4 id="mixins">Mixins</h4> <ul> <li><a href="../mixin/base.html">base</a></li> <li><a href="../mixin/dom.html">dom</a></li> <li><a href="../mixin/displayShape.html">display</a></li> </ul> </div> <div class="content"><div class='highlight'><pre>P = baseMix(P); P = domMix(P); P = displayMix(P);</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-11">§</a> </div> <h4 id="canvas-attributes">Canvas attributes</h4> <ul> <li>Attributes defined in the <a href="../mixin/base.html">base mixin</a>: name.</li> <li>Attributes defined in the <a href="../mixin/position.html">position mixin</a>: group, visibility, order, start, startX, startY, handle, handleX, handleY, offset, offsetX, offsetY, dimensions, width, height, pivoted, mimicked, lockTo, lockXTo, lockYTo, scale, roll, noUserInteraction, noPositionDependencies, noCanvasEngineUpdates, noFilters, noPathUpdates, purge, bringToFrontOnDrag.</li> <li>Attributes defined in the <a href="../mixin/delta.html">delta mixin</a>: delta, noDeltaUpdates.</li> <li>Attributes defined in the <a href="../mixin/pivot.html">pivot mixin</a>: pivot, pivotCorner, addPivotHandle, addPivotOffset, addPivotRotation.</li> <li>Attributes defined in the <a href="../mixin/mimic.html">mimic mixin</a>: mimic, useMimicDimensions, useMimicScale, useMimicStart, useMimicHandle, useMimicOffset, useMimicRotation, useMimicFlip, addOwnDimensionsToMimic, addOwnScaleToMimic, addOwnStartToMimic, addOwnHandleToMimic, addOwnOffsetToMimic, addOwnRotationToMimic.</li> <li>Attributes defined in the <a href="../mixin/path.html">path mixin</a>: path, pathPosition, addPathHandle, addPathOffset, addPathRotation, constantPathSpeed.</li> <li>Attributes defined in the <a href="../mixin/anchor.html">anchor mixin</a>: anchor.</li> <li>Attributes defined in the <a href="../mixin/dom.html">dom mixin</a>: domElement, pitch, yaw, offsetZ, css, classes, position, actionResize, trackHere, domAttributes.</li> <li>Attributes defined in the <a href="../mixin/displayShape.html">display mixin</a>: breakToBanner, breakToLandscape, breakToPortrait, breakToSkyscraper, actionBannerShape, actionLandscapeShape, actionRectangleShape, actionPortraitShape, actionSkyscraperShape.</li> </ul> </div> <div class="content"><div class='highlight'><pre>let defaultAttributes = {</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-12">§</a> </div> position - the CSS position value for the <canvas> element. This value will be set to <code>absolute</code> when the element is an artefact associated with a Stack; <code>relative</code> in other cases. </div> <div class="content"><div class='highlight'><pre> position: 'relative',</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-13">§</a> </div> trackHere </div> <div class="content"><div class='highlight'><pre> trackHere: 'subscribe',</pre></div></div> </li> <li id="section-14"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-14">§</a> </div> fit - String indicating how the base Cell should copy its contents over to the <canvas> element as the final step in the Display cycle. Accepted values are: <code>fill</code>, <code>contain</code>, <code>cover</code>, <code>none</code> (but not <code>scale-down</code>). The aim of this functionality is to replicate the CSS <code>object-fit</code> property - <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit">detailed here</a> - for <canvas> elements. We apply the fit attribute to the Canvas wrapper, not the element itself or its parent element. </div> <div class="content"><div class='highlight'><pre> fit: 'none',</pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-15">§</a> </div> DEPRECATED (because it is a really bad name) isComponent replaced by baseMatchesCanvasDimensions - set to true if, for example, canvas is being used as part of a Scrawl-canvas snippet. </div> <div class="content"><div class='highlight'><pre> isComponent: false, baseMatchesCanvasDimensions: false,</pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-16">§</a> </div> renderOnResize - perform an additional render of the scene following a change in the canvas’s dimensions </div> <div class="content"><div class='highlight'><pre> renderOnResize: true,</pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-17">§</a> </div> For Device Pixel Ratio, we need to tell the canvas whether it should ignore resetting the canvas dimensions - if, for instance, we set them to ‘100%’ in CSS - and whether we have set the base to static dimensions (via <code>setBase</code>) <ul> <li>We only need to worry about this after we invoke <code>scrawl.setIgnorePixelRatio(false)</code> in the demo code</li> </ul> ignoreCanvasCssDimensions - skip setting the <canvas> element’s CSS width and height when dimensions change. When the flag is set to <code>false</code> (default), we need to set the CSS values to a valuepx String which will then allow us to set the canvas drawing dimensions to take into account the display’s device pixel ratio value. Set the flag to <code>true</code> if the canvas has been initialized as responsive by setting its CSS dimensions values to a value% String. <ul> <li>Note that Scrawl-canvas ignores any attempt to set CSS dimension (width, height) values in the <code>css</code> attribute of the <code>set({})</code> function.</li> </ul> </div> <div class="content"><div class='highlight'><pre> ignoreCanvasCssDimensions: false,</pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-18">§</a> </div> <h5 id="accessibility-attributes">Accessibility attributes</h5> <canvas> elements are raster images - they contain no information within their content (beyond pixel data) which can be analyzed or passed on to the browser or other device. The element can include <code>title</code> and various <code>item</code> attributes (alongside custom <code>data-</code> attributes) but inclusion of these depends entirely on the developer remembering to include them when coding up a web page. Scrawl-canvas attempts to automate some (but not all) accessibility work through inclusion of the following Canvas att