• Jump To … +
    ./source/core/animationloop.js ./source/core/component.js ./source/core/document.js ./source/core/events.js ./source/core/init.js ./source/core/library.js ./source/core/userInteraction.js ./source/core/utilities.js ./source/factory/action.js ./source/factory/anchor.js ./source/factory/animation.js ./source/factory/bezier.js ./source/factory/block.js ./source/factory/canvas.js ./source/factory/cell.js ./source/factory/cog.js ./source/factory/color.js ./source/factory/coordinate.js ./source/factory/element.js ./source/factory/emitter.js ./source/factory/filter.js ./source/factory/fontAttributes.js ./source/factory/gradient.js ./source/factory/grid.js ./source/factory/group.js ./source/factory/imageAsset.js ./source/factory/line.js ./source/factory/loom.js ./source/factory/mesh.js ./source/factory/net.js ./source/factory/noise.js ./source/factory/oval.js ./source/factory/palette.js ./source/factory/particle.js ./source/factory/particleForce.js ./source/factory/particleHistory.js ./source/factory/particleSpring.js ./source/factory/particleWorld.js ./source/factory/pattern.js ./source/factory/phrase.js ./source/factory/picture.js ./source/factory/polygon.js ./source/factory/polyline.js ./source/factory/quadratic.js ./source/factory/quaternion.js ./source/factory/radialGradient.js ./source/factory/rectangle.js ./source/factory/renderAnimation.js ./source/factory/shape.js ./source/factory/spiral.js ./source/factory/spriteAsset.js ./source/factory/stack.js ./source/factory/star.js ./source/factory/state.js ./source/factory/tetragon.js ./source/factory/ticker.js ./source/factory/tracer.js ./source/factory/tween.js ./source/factory/unstackedElement.js ./source/factory/vector.js ./source/factory/videoAsset.js ./source/factory/wheel.js ./source/mixin/anchor.js ./source/mixin/asset.js ./source/mixin/assetConsumer.js ./source/mixin/base.js ./source/mixin/cascade.js ./source/mixin/delta.js ./source/mixin/displayShape.js ./source/mixin/dom.js ./source/mixin/entity.js ./source/mixin/filter.js ./source/mixin/mimic.js ./source/mixin/path.js ./source/mixin/pattern.js ./source/mixin/pivot.js ./source/mixin/position.js ./source/mixin/shapeBasic.js ./source/mixin/shapeCurve.js ./source/mixin/shapePathCalculation.js ./source/mixin/styles.js ./source/mixin/tween.js ./source/worker/filter-string.js ./source/worker/filter.js
  • ¶

    Animation factory

    Animations lie at the heart of Scrawl-canvas functionality. While static Canvas and Stack displays can be rendered once and then forgotten, any Canvas or Stack that implements any form of user interaction, or movement in the display, needs to implement an Animation object to make that functionality happen.

    There are a number of ways to create an Animation object:

    • scrawl.makeAnimation - as coded by this factory - will supply a very basic Animation object. The factory requires that we supply it with a Promise-based fn function which will be added to the core Scrawl-canvas animation loop.

    Because creating an Animation object from this factory can be quite fiddly, Scrawl-canvas supplies some additional convenience factories to make the process easier:

    • scrawl.makeRender - use this function to create an animation object which will control the Display cycle for a canvas or stack. The function allows users to add a number of hook functions that will trigger at various points in the Display cycle, alongside functions that will trigger whenever the animation object starts running, stops running, or errors.
    • scrawl.makeTween and scrawl.makeTicker - both of these factory functions use animation objects under the hood
    • scrawl.makeComponent - used in component files, the factory function will automatically add an animation object to the component, alongside much of the functionality supplied by makeRender. It will also create an IntersectionObserver on the window object that will automatically run/stop the animation object dependant on its canvas element’s position in the browser/device viewport.

    Animation objects can be controlled through some simple functions: run to start the animation running; halt to stop it; and kill to remove it from the system.

    NOTE that Animation objects do not take part in Scrawl-canvas’s packet save-and-load functionality, as a result of which they cannot be cloned.

  • ¶

    Demos:

    • All the demos run some form of animation - mostly created via scrawl.makeRender - see the RenderAnimation factory for details
    • DOM-001 - Loading the scrawl-canvas library using a script tag in the HTML code
    • DOM-010 - Add and remove (kill) Scrawl-canvas stack elements programmatically
  • ¶

    Imports

    import { animation, constructors } from '../core/library.js';
    import { mergeOver, pushUnique, removeItem, xt, λnull, λpromise, λthis } from '../core/utilities.js';
    import { animate, resortAnimations } from '../core/animationloop.js';
    
    import baseMix from '../mixin/base.js';
  • ¶

    Animation constructor

    const Animation = function (items = {}) {
    
        this.makeName(items.name);
        this.order = (xt(items.order)) ? items.order : this.defs.order;
        this.fn = items.fn || λpromise;
        this.onRun = items.onRun || λnull;
        this.onHalt = items.onHalt || λnull;
        this.onKill = items.onKill || λnull;
    
        this.register();
    
        if(!items.delay) this.run();
    
        return this;
    };
  • ¶

    Animation prototype

    let P = Animation.prototype = Object.create(Object.prototype);
    
    P.type = 'Animation';
    P.lib = 'animation';
    P.isArtefact = false;
    P.isAsset = false;
  • ¶

    Mixins

    P = baseMix(P);
  • ¶

    Animation attributes

    • Attributes defined in the base mixin: name.
    let defaultAttributes = {
  • ¶

    order - positive integer Number - determines the order in which each Animation object will be actioned before the Display cycle starts.

    • Higher order Animations will be processed after lower order Animations.
    • Animations with the same order value will be processed in the order in which they were defined in code.
        order: 1,
  • ¶

    fn - the main function that the Animation object will run on each RequestAnimationFrame tick. This function must return a Promise.

        fn: null,
  • ¶

    The Animation object supports some animation hook functions:

    • onRun - triggers each time the Animation object’s run function is invoked
    • onHalt - triggers each time the Animation object’s halt function is invoked
    • onKill - triggers each time the Animation object’s kill function is invoked
        onRun: null,
        onHalt: null,
        onKill: null,
  • ¶

    delay - by default, Animation objects will start running as soon as they are created. To prevent this happening the constructor argument can take a non-retained delay Boolean flag which, when set to true, will prevent the Animation object from adding itself to the Scrawl-canvas animation loop. The animation can be started at any subsequent time by invoking its run function.

    };
    P.defs = mergeOver(P.defs, defaultAttributes);
  • ¶

    Packet management

    This functionality is disabled for Animation objects

    P.stringifyFunction = λnull;
    P.processPacketOut = λnull;
    P.finalizePacketOut = λnull;
    P.saveAsPacket = function () {
    
        return `[${this.name}, ${this.type}, ${this.lib}, {}]`
    };
  • ¶

    Clone management

    This functionality is disabled for Animation objects

    P.clone = λthis;
  • ¶

    Kill management

    Kill functionality is managed as one of the Animation object’s hook functions - see below

  • ¶

    Get, Set, deltaSet

    No additional getter or setter functionality required

  • ¶

    Prototype functions

  • ¶

    run - start the animation, if it is not already running

    P.run = function () {
    
        this.onRun();
        pushUnique(animate, this.name);
        resortAnimations();
        return this;
    };
  • ¶

    isRunning - returns true if animation is running; false otherwise

    P.isRunning = function () {
    
        return (animate.indexOf(this.name) >= 0) ? true : false;
    };
  • ¶

    halt - stop the animation, if it is already running

    P.halt = function () {
    
        this.onHalt();
        removeItem(animate, this.name);
        resortAnimations();
        return this;
    };
  • ¶

    kill - stop the animation if it is already running, and remove it from the Scrawl-canvas library

    P.kill = function () {
    
        this.onKill();
        removeItem(animate, this.name);
        resortAnimations();
    
        this.deregister();
        
        return true;
    };
  • ¶

    Factory

    scrawl.makeAnimation({
    
        name: 'demo-animation',
    
        // Function MUST return a Promise object, and that promise must ALWAYS resolve (not reject)
        fn: function () {
    
            return new Promise((resolve) => {
    
                // Renders all stack and canvas elements in the document
                scrawl.render()
                .then(() => resolve(true))
                .catch(err => resolve(false));
            });
        }
    });
    const makeAnimation = function (items) {
        
        return new Animation(items);
    };
    
    constructors.Animation = Animation;
  • ¶

    Exports

    export {
        makeAnimation,
    };