scrawl-canvas

<!DOCTYPE html> <html> <head> <title>DOM event listeners</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="animationloop.html"> ./source/core/animationloop.js </a> <a class="source" href="document.html"> ./source/core/document.js </a> <a class="source" href="events.html"> ./source/core/events.js </a> <a class="source" href="init.html"> ./source/core/init.js </a> <a class="source" href="library.html"> ./source/core/library.js </a> <a class="source" href="random-seed.html"> ./source/core/random-seed.js </a> <a class="source" href="snippets.html"> ./source/core/snippets.js </a> <a class="source" href="userInteraction.html"> ./source/core/userInteraction.js </a> <a class="source" href="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="../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="dom-event-listeners">DOM event listeners</h1> Each scrawl-canvas stack and canvas can have bespoke Scrawl-canvas listeners attached to them, to track user mouse and touch interactions with that element. Scrawl-canvas defines five bespoke listeners: <ul> <li>move - track mouse cursor and touch movements across the DOM element</li> <li>down - register a new touch interaction, or user pressing the left mouse button</li> <li>up - register the end of a touch interaction, or user releasing the left mouse button</li> <li>enter - trigger an event when the mouse cursor or touch event enters into the DOM element</li> <li>leave - trigger an event when the mouse cursor or touch event exits from the DOM element</li> </ul> The functions all takes the following arguments: <ul> <li>evt - String name of the event (‘move’, ‘down’, ‘up’, ‘enter’, ‘leave’), or an array of such strings</li> <li>fn - the function to be called when the event listener(s) trigger</li> <li>targ - either the DOM element object, or an array of DOM element objects, or a query selector String; these elements need to be registered in the Scrawl-canvas library beforehend (done automatically for stack and canvas elements)</li> </ul> </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>import { isa_fn, isa_dom, λnull, Ωempty, detectBrowser } from "./utilities.js"; import { canvas, cell, entity } from "./library.js";</pre></div></div> </li> <li id="section-3"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-3">§</a> </div> <code>Exported function</code> (to modules and scrawl object) - scrawl.makeAnimationObserver - function to create and start a <a href="https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API">DOM IntersectionObserver</a> object. The function expects 3 arguments, in the following order: <ul> <li>a Scrawl-canvas animation object (required) - either <a href="../factory/Animation.html">Animation</a> or <a href="../factory/RenderAnimation.html">RenderAnimation</a></li> <li>A Scrawl-canvas element wrapper object (required) - either <a href="../factory/Canvas.html">Canvas</a>, <a href="../factory/Stack.html">Stack</a> or <a href="../factory/Element.html">Element</a></li> <li>A Javascript object (optional) containing options to be applied to the observer - <code>root</code>, <code>rootMargin</code>, <code>threshold</code></li> </ul> The function returns a function which, when invoked, will disconnect the observer from the DOM. </div> <div class="content"><div class='highlight'><pre>const makeAnimationObserver = function (anim, wrapper, specs = Ωempty) { if (typeof window.IntersectionObserver === 'function' && anim && anim.run) { let observer = new IntersectionObserver((entries, observer) => { let i, iz, entry; for (i = 0, iz = entries.length; i < iz; i++) { entry = entries[i]; if (entry.isIntersecting) !anim.isRunning() && anim.run(); else if (!entry.isIntersecting) anim.isRunning() && anim.halt(); } }, specs); if (wrapper && wrapper.domElement) { observer.observe(wrapper.domElement); } return function () { observer.disconnect(); } } else return λnull; }</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-4">§</a> </div> <code>Exported function</code> (to modules and scrawl object) - scrawl.addListener. Returns a kill function which, when invoked (no arguments required), will remove the event listener(s) from all DOM elements to which they have been attached. </div> <div class="content"><div class='highlight'><pre>const addListener = function (evt, fn, targ) { if (!isa_fn(fn)) throw new Error(`core/document addListener() error - no function supplied: ${evt}, ${targ}`); actionListener(evt, fn, targ, 'removeEventListener'); actionListener(evt, fn, targ, 'addEventListener'); return function () { removeListener(evt, fn, targ); }; };</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-5">§</a> </div> <code>Exported function</code> (to modules and scrawl object) - scrawl.removeListener. The counterpart to ‘addListener’ is removeListener which removes Scrawl-canvas event listeners from DOM elements in a similar way </div> <div class="content"><div class='highlight'><pre>const removeListener = function (evt, fn, targ) { if (!isa_fn(fn)) throw new Error(`core/document removeListener() error - no function supplied: ${evt}, ${targ}`); actionListener(evt, fn, targ, 'removeEventListener'); };</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-6">§</a> </div> Because devices and browsers differ in their approach to user interaction (mouse vs pointer vs touch), the actual functionality for adding and removing the event listeners associated with each approach is handled by dedicated actionXXXListener functions </div> </li> <li id="section-7"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-7">§</a> </div> TODO: code up the functionality to manage touch events </div> <div class="content"><div class='highlight'><pre>const actionListener = function (evt, fn, targ, action) { let events = [].concat(evt), targets; if (targ.substring) targets = document.body.querySelectorAll(targ); else if (Array.isArray(targ)) targets = targ; else targets = [targ]; if (navigator.pointerEnabled || navigator.msPointerEnabled) actionPointerListener(events, fn, targets, action); else actionMouseListener(events, fn, targets, action); }; const actionMouseListener = function (events, fn, targets, action) { let i, iz, j, jz, myevent, target; for (i = 0, iz = events.length; i < iz; i++) { myevent = events[i]; for (j = 0, jz = targets.length; j < jz; j++) { target = targets[j]; if (isa_dom(target) || target.document || target.characterSet) { switch (myevent) { case 'move': target[action]('mousemove', fn, false); target[action]('touchmove', fn, {passive: false}); target[action]('touchfollow', fn, {passive: false}); break; case 'up': target[action]('mouseup', fn, false); target[action]('touchend', fn, {passive: false}); break; case 'down': target[action]('mousedown', fn, false); target[action]('touchstart', fn, {passive: false}); break; case 'leave': target[action]('mouseleave', fn, false); target[action]('touchleave', fn, {passive: false}); break; case 'enter': target[action]('mouseenter', fn, false); target[action]('touchenter', fn, {passive: false}); break; } } else throw new Error(`core/document actionMouseListener() error - bad target: ${myevent}, ${target}`); } } }; const actionPointerListener = function (events, fn, targets, action) { let i, iz, j, jz, myevent, target; for (i = 0, iz = events.length; i < iz; i++) { myevent = events[i]; for (j = 0, jz = targets.length; j < jz; j++) { target = targets[j]; if (isa_dom(target) || target.document || target.characterSet) { switch (myevent) { case 'move': target[action]('pointermove', fn, false); break; case 'up': target[action]('pointerup', fn, false); break; case 'down': target[action]('pointerdown', fn, false); break; case 'leave': target[action]('pointerleave', fn, false); break; case 'enter': target[action]('pointerenter', fn, false); break; } } } } };</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-8">§</a> </div> Any event listener can be added to a Scrawl-canvas stack or canvas DOM element. The scrawl.addNativeListener function makes adding and removing these ‘native’ listeners a little easier: multiple event listeners (which all trigger the same function) can be added to multiple DOM elements (that have been registered in the Scrawl-canvas library) in a single function call. The function requires three arguments: <ul> <li>evt - String name of the event (‘click’, ‘input’, ‘change’, etc), or an array of such strings</li> <li>fn - the function to be called when the event listener(s) trigger</li> <li>targ - either the DOM element object, or an array of DOM element objects, or a query selector String. Note that <code>window</code> and ``</li> </ul> </div> </li> <li id="section-9"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-9">§</a> </div> <code>Exported function</code> (to modules and scrawl object). Returns a kill function which, when invoked (no arguments required), will remove the event listener(s) from all DOM elements to which they have been attached. </div> <div class="content"><div class='highlight'><pre>const addNativeListener = function (evt, fn, targ) { if (!isa_fn(fn)) throw new Error(`core/document addNativeListener() error - no function supplied: ${evt}, ${targ}`); actionNativeListener(evt, fn, targ, 'removeEventListener'); actionNativeListener(evt, fn, targ, 'addEventListener'); return function () { removeNativeListener(evt, fn, targ); }; };</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-10">§</a> </div> <code>Exported function</code> (to modules and scrawl object). The counterpart to ‘addNativeListener’ is scrawl.removeNativeListener which removes event listeners from DOM elements in a similar way </div> <div class="content"><div class='highlight'><pre>const removeNativeListener = function (evt, fn, targ) { if (!isa_fn(fn)) throw new Error(`core/document removeNativeListener() error - no function supplied: ${evt}, ${targ}`); actionNativeListener(evt, fn, targ, 'removeEventListener'); }; const actionNativeListener = function (evt, fn, targ, action) { let events = [].concat(evt), targets, i, iz, j, jz, myevent, target; if (targ.substring) targets = document.body.querySelectorAll(targ); else if (Array.isArray(targ)) targets = targ; else targets = [targ]; for (i = 0, iz = events.length; i < iz; i++) { myevent = events[i]; for (j = 0, jz = targets.length; j < jz; j++) { target = targets[j]; if (isa_dom(target) || target.document || target.characterSet) target[action](myevent, fn, false); else throw new Error(`core/document actionNativeListener() error - bad target: ${myevent}, ${target}`); } } };</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-11">§</a> </div> <h2 id="monitoring-the-device-pixel-ratio">Monitoring the device pixel ratio</h2> DPR is detected here, but mainly handled in the <code>factory/cell.js</code> file <ul> <li>We scale the cell by DPR - this should be the only time we touch native scale functionality!</li> <li>All the other scaling functionality in SC is handled by computiation - applying the scaling factor to dimensions, start, handle, offset etc values which then get saved in the <code>current</code> equivalent attributes</li> </ul> </div> <div class="content"><div class='highlight'><pre>let dpr_changeAction = λnull; const setPixelRatioChangeAction = (func) => dpr_changeAction = func; const browserIs = detectBrowser(); window.scrawlEnvironmentBrowserDetection = browserIs; let dpr = 0; const getPixelRatio = () => dpr; let ignorePixelRatio = false; const getIgnorePixelRatio = () => ignorePixelRatio; const setIgnorePixelRatio = (val) => ignorePixelRatio = val; const updatePixelRatio = () => { dpr = window.devicePixelRatio; for (const [name, wrapper] of Object.entries(canvas)) { wrapper.dirtyDimensions = true; } for (const [name, wrapper] of Object.entries(cell)) { wrapper.dirtyDimensions = true; } for (const [name, ent] of Object.entries(entity)) { ent.dirtyHost = true; } if (!ignorePixelRatio) dpr_changeAction();</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-12">§</a> </div> Note: I have no idea what Safari is doing - maybe device pixel ratio stuff is handled internally? <ul> <li>Whatever. Safari does not like, or respond to, this matchmedia query</li> <li>As long as the demos display as expected in Safari on both 1dppx and 2dppx (Retina) screens, and dragging the Safari browser between screens with different dppx values doesn’t break the display or freeze the page, then I think we’re okay</li> </ul> </div> <div class="content"><div class='highlight'><pre> if (browserIs.indexOf('safari') < 0) { matchMedia(`(resolution: ${dpr}dppx)`).addEventListener("change", updatePixelRatio, { once: true }); } }; updatePixelRatio();</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-13">§</a> </div> <h4 id="exports">Exports</h4> </div> <div class="content"><div class='highlight'><pre>export { addListener, removeListener, addNativeListener, removeNativeListener, makeAnimationObserver, getPixelRatio, setPixelRatioChangeAction, getIgnorePixelRatio, setIgnorePixelRatio, };</pre></div></div> </li> </ul> </div> </body> </html>