scrawl-canvas

<!DOCTYPE html> <html> <head> <title>Core utility functions</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="core-utility-functions">Core utility functions</h1> A ragtag collection of helper functions which other modules can import and use </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 * as library 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> <h4 id="functions">Functions</h4> </div> </li> <li id="section-4"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-4">§</a> </div> addStrings adds the two arguments together and returns a percentage string value if either of the values was a string; or a sum of the two numbers. Examples: <pre><code>addStrings(20, 40); -> 60 addStrings('20%', 40); -> '60%' addStrings(20, '40%'); -> '60%' addStrings('20%', '40%'); -> '60%' addStrings('center', 3); -> '53%' </code></pre> </div> <div class="content"><div class='highlight'><pre> const addStrings = (current, delta) => { if (!xt(delta)) throw new Error(`core/utilities addStrings() error - no delta argument supplied ${current}, ${delta}`); if ((delta != null)) {</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-5">§</a> </div> Correct for labels </div> <div class="content"><div class='highlight'><pre> if ('left' === current || 'top' === current) current = '0%'; else if ('right' === current || 'bottom' === current) current = '100%'; else if ('center' === current) current = '50%'; let stringFlag = (current.substring || delta.substring) ? true : false; if (isa_number(current)) current += (isa_number(delta) ? delta : parseFloat(delta)); else current = parseFloat(current) + (isa_number(delta) ? delta : parseFloat(delta)); return (stringFlag) ? current + '%' : current; } return current; };</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-6">§</a> </div> convertTime converts a time value into its component string suffix and (millisecond) number value properties; returns an array Examples: <pre><code>convertTime(5000); -> ['ms', 5000] convertTime('50%'); -> ['%', 50] convertTime('5000ms'); -> ['ms', 5000] convertTime('5s'); -> ['ms', 5000] </code></pre> </div> <div class="content"><div class='highlight'><pre>const convertTime = (item) => { let a, timeUnit, timeValue; if (!xt(item)) throw new Error(`core/utilities convertTime() error - no argument supplied`); if (isa_number(item)) return ['ms', item]; if (!item.substring) throw new Error(`core/utilities convertTime() error - invalid argument: ${item}`); a = item.match(/^\d+\.?\d*(\D*)/); timeUnit = (a[1].toLowerCase) ? a[1].toLowerCase() : 'ms'; timeValue = parseFloat(item); if (!isa_number(timeValue)) throw new Error(`core/base error - convertTime() argument converts to NaN: ${item}`); switch (timeUnit) { case 's': timeValue *= 1000; break; case '%': break; default: timeUnit = 'ms'; } return [timeUnit, timeValue]; };</pre></div></div> </li> <li id="section-7"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-7">§</a> </div> correctAngle makes sure any degree-based angle is in the range <code>0-360</code> </div> <div class="content"><div class='highlight'><pre>const correctAngle = (item) => { if (!item.toFixed || isNaN(item)) { console.log(`${item} is not a valid number`); return item; } item = item % 360; if (item < 0) { item += 360; } return item; };</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-8">§</a> </div> correctForZero checks and corrects for minor deviations from zero (eNumbers) </div> <div class="content"><div class='highlight'><pre>const correctForZero = (item) => { if (!item.toFixed) return item; if (item == 0) return item; if (isNaN(item)) return 0; if (item < -0.000001) return item; if (item > 0.000001) return item; return 0; };</pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-9">§</a> </div> λ functions helps us avoid errors when invoking a function attribute settable by the coder </div> <div class="content"><div class='highlight'><pre>const λnull = () => {}; const λfirstArg = function (a) { return a; }; const λthis = function () { return this; }; const λpromise = () => Promise.resolve(true); const Ωempty = {};</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-10">§</a> </div> generateUuid is a simple (crude) uuid generator <a href="http://stackoverflow.com/questions/105034/create-guid-uuid-in-javascript">http://stackoverflow.com/questions/105034/create-guid-uuid-in-javascript</a> (imported 2017-07-08) </div> <div class="content"><div class='highlight'><pre>const generateUuid = () => { function s4() { return Math.floor((1 + Math.random()) * 0x10000).toString(16).substring(1); } return `${s4()}${s4()}-${s4()}-${s4()}-${s4()}-${s4()}${s4()}${s4()}`; };</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-11">§</a> </div> generateUniqueString is a simple random String generator <a href="https://gist.github.com/SimonHoiberg/ad2710c8626c5a74cddd8f6385795cc0">https://gist.github.com/SimonHoiberg/ad2710c8626c5a74cddd8f6385795cc0</a> (imported 2020-11-22) </div> <div class="content"><div class='highlight'><pre>const generateUniqueString = () => { return performance.now().toString(36) + Math.random().toString(36).substr(2); };</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-12">§</a> </div> interpolate clamp a value between a maximum and minimum value </div> <div class="content"><div class='highlight'><pre>const interpolate = function (val, min, max) { return min + val * (max - min); };</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-13">§</a> </div> isa_boolean checks to make sure the argument is a boolean </div> <div class="content"><div class='highlight'><pre>const isa_boolean = item => (typeof item === 'boolean') ? true : false;</pre></div></div> </li> <li id="section-14"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-14">§</a> </div> isa_canvas checks to make sure the argument is a DOM <canvas> element </div> <div class="content"><div class='highlight'><pre>const isa_canvas = item => (Object.prototype.toString.call(item) === '[object HTMLCanvasElement]') ? true : false;</pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-15">§</a> </div> isa_dom checks to make sure the argument is a DOM element of some sort </div> <div class="content"><div class='highlight'><pre>const isa_dom = item => (item && item.querySelector && item.dispatchEvent) ? true : false;</pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-16">§</a> </div> isa_fn checks to make sure the argument is a JavaScript function object </div> <div class="content"><div class='highlight'><pre>const isa_fn = item => (typeof item === 'function') ? true : false;</pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-17">§</a> </div> isa_number checks to make sure the argument is true number (excluding NaN) </div> <div class="content"><div class='highlight'><pre>const isa_number = item => (item != null && item.toFixed && !Number.isNaN(item)) ? true : false;</pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-18">§</a> </div> isa_obj checks to make sure the argument is a JavaScript Object </div> <div class="content"><div class='highlight'><pre>const isa_obj = item => (Object.prototype.toString.call(item) === '[object Object]') ? true : false;</pre></div></div> </li> <li id="section-19"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-19">§</a> </div> isa_quaternion checks to make sure the argument is a Scrawl-canvas Quaternion object </div> <div class="content"><div class='highlight'><pre>const isa_quaternion = item => (item && item.type && item.type === 'Quaternion') ? true : false;</pre></div></div> </li> <li id="section-20"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-20">§</a> </div> mergeInto takes two objects and merges the attributes of one into the other. This function mutates the ‘original’ object rather than generating a third, new onject Example: <pre><code>var original = { name: 'Peter', age: 42, job: 'lawyer' }; var additional = { age: 32, job: 'coder', pet: 'cat' }; scrawl.utils.mergeInto(original, additional); -> { name: 'Peter', age: 42, job: 'lawyer', pet: 'cat' } </code></pre> </div> <div class="content"><div class='highlight'><pre>const mergeInto = (original, additional) => { if (!isa_obj(original) || !isa_obj(additional)) throw new Error(`core/utilities mergeInto() error - insufficient arguments supplied ${original}, ${additional}`); for (let key in additional) { if (additional.hasOwnProperty(key) && typeof original[key] == 'undefined') original[key] = additional[key]; } return original; };</pre></div></div> </li> <li id="section-21"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-21">§</a> </div> mergeOver takes two objects and writes the attributes of one over the other. This function mutates the ‘original’ object rather than generating a third, new onject Example: <pre><code>var original = { name: 'Peter', age: 42, job: 'lawyer' }; var additional = { age: 32, job: 'coder', pet: 'cat' }; scrawl.utils.mergeOver(original, additional); -> { name: 'Peter', age: 32, job: 'coder', pet: 'cat' } </code></pre> </div> <div class="content"><div class='highlight'><pre>const mergeOver = (original, additional) => { if (!isa_obj(original) || !isa_obj(additional)) throw new Error(`core/utilities mergeOver() error - insufficient arguments supplied ${original}, ${additional}`); for (let key in additional) { if (additional.hasOwnProperty(key)) original[key] = additional[key]; } return original; };</pre></div></div> </li> <li id="section-22"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-22">§</a> </div> mergeDiscard iterates over the additional object to perform a mergeOver operation, and also removing attributes from the original object where they have been set to null in the additional object Example: <pre><code>var original = { name: 'Peter', age: 42, job: 'lawyer' }; var additional = { age: 32, job: null, pet: 'cat' }; scrawl.utils.mergeOver(original, additional); -> { name: 'Peter', age: 32, pet: 'cat' } </code></pre> </div> <div class="content"><div class='highlight'><pre>const mergeDiscard = (original, additional) => { if (!isa_obj(original) || !isa_obj(additional)) throw new Error(`core/utilities mergeDiscard() error - insufficient arguments supplied ${original}, ${additional}`); Object.entries(additional).forEach(([key, val]) => { if (val === null) delete original[key]; else original[key] = additional[key]; }); return original; };</pre></div></div> </li> <li id="section-23"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-23">§</a> </div> pushUnique adds a value to the end of an array, if that value is not already present in the array. This function mutates the array Example: <pre><code>var myarray = ['apple', 'orange']; scrawl.utils.pushUnique(myarray, 'apple'); -> ['apple', 'orange'] scrawl.utils.pushUnique(myarray, 'banana'); -> ['apple', 'orange', 'banana'] </code></pre> </div> <div class="content"><div class='highlight'><pre>const pushUnique = (myArray, potentialMember) => { if (!xta(myArray, potentialMember)) throw new Error(`core/utilities pushUnique() error - insufficient arguments supplied ${myArray}, ${potentialMember}`); if (!Array.isArray(myArray)) throw new Error(`core/utilities pushUnique() error - argument not an array ${myArray}`); if (Array.isArray(potentialMember)) { potentialMember.forEach(item => pushUnique(myArray, item)); } <span class