- Jump To … +
  ./source/core/animation-loop.js ./source/core/display-cycle.js ./source/core/document-root-elements.js ./source/core/document.js ./source/core/events.js ./source/core/init.js ./source/core/library.js ./source/core/random-seed.js ./source/core/shared-vars.js ./source/core/snippets.js ./source/core/system-flags.js ./source/core/user-interaction.js ./source/core/utilities.js ./source/factory/action.js ./source/factory/anchor.js ./source/factory/animation.js ./source/factory/array-pool.js ./source/factory/bezier.js ./source/factory/block.js ./source/factory/canvas.js ./source/factory/cell-fragment.js ./source/factory/cell.js ./source/factory/cog.js ./source/factory/color.js ./source/factory/conic-gradient.js ./source/factory/coordinate.js ./source/factory/crescent.js ./source/factory/drag-zone.js ./source/factory/element.js ./source/factory/emitter.js ./source/factory/filter-engine-bluenoise-data.js ./source/factory/filter-engine.js ./source/factory/filter.js ./source/factory/font-attributes.js ./source/factory/gradient.js ./source/factory/grid.js ./source/factory/group.js ./source/factory/image-asset.js ./source/factory/keyboard-zone.js ./source/factory/line-spiral.js ./source/factory/line.js ./source/factory/loom.js ./source/factory/mesh.js ./source/factory/net.js ./source/factory/noise-asset.js ./source/factory/observe-update.js ./source/factory/oval.js ./source/factory/palette.js ./source/factory/particle-force.js ./source/factory/particle-history.js ./source/factory/particle-spring.js ./source/factory/particle-world.js ./source/factory/particle.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/radial-gradient.js ./source/factory/raw-asset.js ./source/factory/reaction-diffusion-asset.js ./source/factory/rectangle.js ./source/factory/render-animation.js ./source/factory/shape.js ./source/factory/spiral.js ./source/factory/sprite-asset.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/unstacked-element.js ./source/factory/vector.js ./source/factory/video-asset.js ./source/factory/wheel.js ./source/mixin/anchor.js ./source/mixin/asset-advanced-functionality.js ./source/mixin/asset-consumer.js ./source/mixin/asset.js ./source/mixin/base.js ./source/mixin/cascade.js ./source/mixin/cell-key-functions.js ./source/mixin/delta.js ./source/mixin/display-shape.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/shape-basic.js ./source/mixin/shape-curve.js ./source/mixin/shape-path-calculation.js ./source/mixin/styles.js ./source/mixin/tween.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.makeSnippet` - used in snippet files, the factory function will automatically add an animation object to the snippet, 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 { constructors } from '../core/library.js';

      import { doCreate, mergeOver, xt, λnull, λpromise, λthis, Ωempty } from '../core/utilities.js';

      import { forceUpdate } from '../core/system-flags.js';

      import { animateAdd, animateIncludes, animateRemove } from '../core/animation-loop.js';

      import baseMix from '../mixin/base.js';

      import { ANIMATION, T_ANIMATION } from '../core/shared-vars.js';

- §

  #### Animation constructor

      const Animation = function (items = Ωempty) {

          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

      const P = Animation.prototype = doCreate();

      P.type = T_ANIMATION;
      P.lib = ANIMATION;
      P.isArtefact = false;
      P.isAsset = false;

- §

  #### Mixins

      baseMix(P);

- §

  #### Animation attributes

  - Attributes defined in the base mixin: name.

      const 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();
          animateAdd(this.name);

          setTimeout(() => forceUpdate(), 20);

          return this;
      };

- §

  `isRunning` - returns true if animation is running; false otherwise

      P.isRunning = function () {

          return animateIncludes(this.name);
      };

- §

  `halt` - stop the animation, if it is already running

      P.halt = function () {

          this.onHalt();
          animateRemove(this.name);
          return this;
      };

- §

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

      P.kill = function () {

          this.onKill();
          animateRemove(this.name);

          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));
              });
          }
      });

      export const makeAnimation = function (items) {

          if (!items) return false;
          return new Animation(items);
      };

      constructors.Animation = Animation;