Source: timeline/Animation.js

  1. /**
  2.  * @module meteoJS/timeline/animation
  3.  */
  4. import $ from 'jquery';
  5. import addEventFunctions from '../Events.js';
  6. import Timeline from '../Timeline.js';
  8. /**
  9.  * Options for animation constructor.
  10.  * 
  11.  * @typedef {Object} module:meteoJS/timeline/animation~options
  12.  * @param {module:meteoJS/timeline.Timeline} timeline - Timeline to animate.
  13.  * @param {number} [restartPause=1.8]
  14.  *   Time in seconds to pause before the animation restart.
  15.  * @param {number} [imagePeriod=0.2]
  16.  *   Time in seconds between animation of two images.
  17.  *   Ignored, if imageFrequency is specified.
  18.  * @param {number|undefined} [imageFrequency]
  19.  *   Time of images during one second.
  20.  * @param {boolean} [enabledStepsOnly=true] - Use only enabled times.
  21.  * @param {boolean} [allEnabledStepsOnly=false]
  22.  *   Use only times that are enabled by all sets of time.
  23.  */
  25. /**
  26.  * Event on animation start.
  27.  * 
  28.  * @event module:meteoJS/timeline/animation#start:animation
  29.  */
  31. /**
  32.  * Event on animation stop.
  33.  * 
  34.  * @event module:meteoJS/timeline/animation#stop:animation
  35.  */
  37. /**
  38.  * Event on reaching last timestamp.
  39.  * 
  40.  * @event module:meteoJS/timeline/animation#end:animation
  41.  */
  43. /**
  44.  * Event triggered immediatly before restart of animation.
  45.  * 
  46.  * @event module:meteoJS/timeline/animation#restart:animation
  47.  */
  49. /**
  50.  * Event triggered when imageFrequency/imagePeriod is changed.
  51.  * 
  52.  * @event module:meteoJS/timeline/animation#change:imageFrequency
  53.  */
  55. /**
  56.  * Event triggered when restartPause is changed.
  57.  * 
  58.  * @event module:meteoJS/timeline/animation#change:restartPause
  59.  */
  61. /**
  62.  * Object to animate {@link module:meteoJS/timeline.Timeline}.
  63.  * 
  64.  * <pre><code>import Animation from 'meteojs/timeline/Animation';</code></pre>
  65.  */
  66. export class Animation {
  67.   
  68.   /**
  69.    * @param {module:meteoJS/timeline/animation~options} options - Options.
  70.    */
  71.   constructor({ timeline,
  72.     restartPause = 1.8,
  73.     imagePeriod = 0.2,
  74.     imageFrequency = undefined,
  75.     enabledStepsOnly = true,
  76.     allEnabledStepsOnly = false } = {}) {
  77.     /**
  78.      * @type module:meteoJS/timeline/animation~options
  79.      * @private
  80.      */
  81.     this.options = {
  82.       timeline,
  83.       restartPause,
  84.       imagePeriod,
  85.       imageFrequency,
  86.       enabledStepsOnly,
  87.       allEnabledStepsOnly
  88.     };
  89.     // Normalize options
  90.     if (this.options.timeline === undefined)
  91.       this.options.timeline = new Timeline();
  92.     if (this.options.imageFrequency !== undefined &&
  93.         this.options.imageFrequency != 0)
  94.       this.options.imagePeriod = 1/this.options.imageFrequency;
  95.     /**
  96.      * ID to window.setInterval() of the animation.
  97.      * If undefined, there is no started animation.
  98.      * @type undefined|number
  99.      * @private
  100.      */
  101.     this.animationIntervalID = undefined;
  102.     
  103.     /**
  104.      * ID to window.setTimeout() ot the animation (used for restart-pause).
  105.      * If undefined, there is no started setTimeout (i.e. no restart-pause).
  106.      * @type undefined|number
  107.      * @private
  108.      */
  109.     this.animationTimeoutID = undefined;
  110.     
  111.     /**
  112.      * Current position in this.times in the animation.
  113.      * @type integer
  114.      * @private
  115.      */
  116.     this.animationStep = 0;
  117.     
  118.     /**
  119.      * Hash with timestamps-valueOf's as keys and index in this.times as values.
  120.      * @type Object
  121.      * @private
  122.      */
  123.     this.timesHash = {};
  124.     
  125.     /**
  126.      * List of timestamps. Current list of times of the timeline to animate over.
  127.      * @type Date[]
  128.      * @private
  129.      */
  130.     this.times = [];
  131.     
  132.     // Timeline initialisieren
  133.     let onChangeTimes = () => {
  134.       this.times = this.options.timeline[this._getTimelineTimesMethod()]();
  135.       this.timesHash = {};
  136.       this.times.forEach((time, i) => this.timesHash[time.valueOf()] = i);
  137.     };
  138.     this.options.timeline.on(this._getTimelineChangeTimesEvent(), onChangeTimes);
  139.     onChangeTimes();
  140.   }
  141.   
  142.   /**
  143.    * Returns time period between two animation steps (in s).
  144.    * 
  145.    * @returns {number} Time period.
  146.    */
  147.   getImagePeriod() {
  148.     return this.options.imagePeriod;
  149.   }
  150.   
  151.   /**
  152.    * Sets time period between to animation steps (in s)
  153.    * 
  154.    * @param {number} imagePeriod - Time period.
  155.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  156.    */
  157.   setImagePeriod(imagePeriod) {
  158.     this.options.imagePeriod = imagePeriod;
  159.     if (this.isStarted())
  160.       this._updateAnimation();
  161.     this.trigger('change:imageFrequency');
  162.     return this;
  163.   }
  164.   
  165.   /**
  166.    * Returns time frequency of animation steps (in 1/s).
  167.    * 
  168.    * @returns {number} Time frequency.
  169.    */
  170.   getImageFrequency() {
  171.     return 1/this.options.imagePeriod;
  172.   }
  173.   
  174.   /**
  175.    * Sets time frequency of animation steps (in 1/s).
  176.    * 
  177.    * @param {number} imageFrequency - Time frequency.
  178.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  179.    */
  180.   setImageFrequency(imageFrequency) {
  181.     if (imageFrequency != 0)
  182.       this.setImagePeriod(1/imageFrequency);
  183.     return this;
  184.   }
  185.   
  186.   /**
  187.    * Returns time duration before a restart (jump from end to beginning, in s).
  188.    * 
  189.    * @returns {number} Time duration.
  190.    */
  191.   getRestartPause() {
  192.     return this.options.restartPause;
  193.   }
  194.   
  195.   /**
  196.    * Sets time duration before a restart (in s).
  197.    * 
  198.    * @param {number} restartPause - Time duration.
  199.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  200.    */
  201.   setRestartPause(restartPause) {
  202.     this.options.restartPause = Number(restartPause); // Convert string to number
  203.     this.trigger('change:restartPause');
  204.     return this;
  205.   }
  206.   
  207.   /**
  208.    * Is animation started.
  209.    * 
  210.    * @returns {boolean}
  211.    */
  212.   isStarted() {
  213.     return this.animationIntervalID !== undefined ||
  214.            this.animationTimeoutID !== undefined;
  215.   }
  216.   
  217.   /**
  218.    * Starts the animation.
  219.    * 
  220.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  221.    * @fires module:meteoJS/timeline/animation#start:animation
  222.    */
  223.   start() {
  224.     if (this.options.timeline.getSelectedTime().valueOf() in this.timesHash)
  225.       this._setStep(this.timesHash[this.options.timeline.getSelectedTime().valueOf()]);
  226.     if (!this.isStarted())
  227.       this._updateAnimation();
  228.     this.trigger('start:animation');
  229.   }
  230.   
  231.   /**
  232.    * Stops the animation.
  233.    * 
  234.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  235.    * @fires module:meteoJS/timeline/animation#stop:animation
  236.    */
  237.   stop() {
  238.     this._clearAnimation();
  239.     this.trigger('stop:animation');
  240.   }
  241.   
  242.   /**
  243.    * Toggles the animation.
  244.    * 
  245.    * @returns {module:meteoJS/timeline/animation.Animation} This.
  246.    */
  247.   toggle() {
  248.     if (this.isStarted())
  249.       this.stop();
  250.     else
  251.       this.start();
  252.   }
  253.   
  254.   /**
  255.    * Setzt Schritt der Animation
  256.    * @private
  257.    * @param {number} step
  258.    */
  259.   _setStep(step) {
  260.     if (0 <= step && step < this._getCount())
  261.       this.animationStep = step;
  262.   }
  263.   
  264.   /**
  265.    * Gibt timeline-Event Name zum abhören von Änderungen der Zeitschritte zurück.
  266.    * @private
  267.    * @returns {string}
  268.    */
  269.   _getTimelineChangeTimesEvent() {
  270.     return (this.options.enabledStepsOnly || this.options.allEnabledStepsOnly)
  271.       ? 'change:enabledTimes' : 'change:times';
  272.   }
  273.   
  274.   /**
  275.    * Gibt timeline-Methode aller Zeitschritte zurück.
  276.    * @private
  277.    * @returns {string}
  278.    */
  279.   _getTimelineTimesMethod() {
  280.     return this.options.allEnabledStepsOnly ? 'getAllEnabledTimes' :
  281.       this.options.enabledStepsOnly ? 'getEnabledTimes' : 'getTimes';
  282.   }
  283.   
  284.   /**
  285.    * Gibt Anzahl Animationsschritte zurück
  286.    * @private
  287.    * @returns {number}
  288.    */
  289.   _getCount() {
  290.     return this.options.timeline[this._getTimelineTimesMethod()]().length;
  291.   }
  292.   
  293.   /**
  294.    * Handelt die Animation
  295.    * @private
  296.    * @fires module:meteoJS/timeline/animation#end:animation
  297.    * @fires module:meteoJS/timeline/animation#restart:animation
  298.    */
  299.   _updateAnimation() {
  300.     this._clearAnimation();
  301.     if (this.animationStep < this._getCount()-1)
  302.       this._initAnimation();
  303.     else
  304.       this._initRestartPause();
  305.   }
  306.   
  307.   /**
  308.    * Startet Animation
  309.    * @private
  310.    */
  311.   _initAnimation() {
  312.     if (this.animationIntervalID === undefined)
  313.       this.animationIntervalID = window.setInterval(() => {
  314.         this.animationStep++;
  315.         if (this.animationStep < this.times.length)
  316.           this.options.timeline.setSelectedTime(this.times[this.animationStep]);
  317.         if (this.animationStep >= this._getCount()-1) {
  318.           this.trigger('end:animation');
  319.           this._clearAnimation();
  320.           this._initRestartPause();
  321.         }
  322.       }, this.options.imagePeriod * 1000);
  323.   }
  324.   
  325.   /**
  326.    * Startet den Timer für die Restart-Pause
  327.    * Verwende als Zeitspanne imagePeriod+restartPause. Sonst wird bei restartPause
  328.    * 0s der letzte Zeitschritt gar nie angezeigt.
  329.    * @private
  330.    */
  331.   _initRestartPause() {
  332.     if (this.animationTimeoutID === undefined)
  333.       this.animationTimeoutID = window.setTimeout(() => {
  334.         this.animationStep = 0;
  335.         this.trigger('restart:animation');
  336.         if (this.animationStep < this.times.length)
  337.           this.options.timeline.setSelectedTime(this.times[this.animationStep]);
  338.         this._clearAnimation();
  339.         this._initAnimation();
  340.       }, (this.options.imagePeriod + this.options.restartPause) * 1000);
  341.   }
  342.   
  343.   /**
  344.    * Löscht window.interval, falls vorhanden
  345.    * @private
  346.    */
  347.   _clearAnimation() {
  348.     if (this.animationIntervalID !== undefined) {
  349.       window.clearInterval(this.animationIntervalID);
  350.       this.animationIntervalID = undefined;
  351.     }
  352.     if (this.animationTimeoutID !== undefined) {
  353.       window.clearTimeout(this.animationTimeoutID);
  354.       this.animationTimeoutID = undefined;
  355.     }
  356.   }
  357.   
  358. }
  359. addEventFunctions(Animation.prototype);
  360. export default Animation;
  362. /**
  363.  * Insert an input-group to change frequency.
  364.  * 
  365.  * <pre><code>import { insertFrequencyInput } from 'meteojs/timeline/Animation';</code></pre>
  366.  * 
  367.  * @param {external:jQuery} node - Node to insert input-group.
  368.  * @param {Object} options - Options for input-group.
  369.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  370.  *   Animation object.
  371.  * @param {string} [options.suffix='fps'] - Suffix text for input-group.
  372.  * @returns {external:jQuery} Input-group node.
  373.  */
  374. export function insertFrequencyInput(node, { animation, suffix = 'fps' }) {
  375.   const number = $('<input>')
  376.     .addClass('form-control')
  377.     .attr('type', 'number')
  378.     .attr('min', 1)
  379.     .attr('step', 1);
  380.   const inputGroupNumber = $('<div>')
  381.     .addClass('input-group')
  382.     .append(number)
  383.     .append($('<span>').addClass('input-group-text').text(suffix));
  384.   number.on('change', () => animation.setImageFrequency(number.val()));
  385.   const onChangeImageFrequency = () => number.val(animation.getImageFrequency());
  386.   animation.on('change:imageFrequency', onChangeImageFrequency);
  387.   onChangeImageFrequency();
  388.   node.append(inputGroupNumber);
  389.   return inputGroupNumber;
  390. }
  392. /**
  393.  * Insert an input-range to change frequency.
  394.  * 
  395.  * <pre><code>import { insertFrequencyRange } from 'meteojs/timeline/Animation';</code></pre>
  396.  * 
  397.  * @param {external:jQuery} node - Node to insert input-range.
  398.  * @param {Object} options - Options for input-range.
  399.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  400.  *   Animation object.
  401.  * @param {number[]} options.frequencies - Frequencies to select.
  402.  * @returns {external:jQuery} Input-range node.
  403.  */
  404. export function insertFrequencyRange(node, { animation, frequencies }) {
  405.   frequencies = frequencies ? frequencies : [1];
  406.   let range = $('<input>')
  407.     .addClass('form-range')
  408.     .attr('type', 'range')
  409.     .attr('min', 0)
  410.     .attr('max', frequencies.length-1);
  411.   range.on('change input', () => {
  412.     let i = range.val();
  413.     if (i < frequencies.length)
  414.       animation.setImageFrequency(frequencies[i]);
  415.   });
  416.   let onChangeImageFrequency = () => {
  417.     let i = frequencies.indexOf(animation.getImageFrequency());
  418.     if (i > -1)
  419.       range.val(i);
  420.   };
  421.   animation.on('change:imageFrequency', onChangeImageFrequency);
  422.   onChangeImageFrequency();
  423.   node.append(range);
  424.   return range;
  425. }
  427. /**
  428.  * Insert an button-group to change frequency.
  429.  * 
  430.  * <pre><code>import { insertFrequencyButtonGroup } from 'meteojs/timeline/Animation';</code></pre>
  431.  * 
  432.  * @param {external:jQuery} node - Node to insert the button-group.
  433.  * @param {Object} options - Options for the button-group.
  434.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  435.  *   Animation object.
  436.  * @param {number[]} options.frequencies - Frequencies to select.
  437.  * @param {string|undefined} [options.btnGroupClass='btn-group']
  438.  *   Class added to the button-group node.
  439.  * @param {string|undefined} [options.btnClass='btn btn-primary']
  440.  *   Class added to each button.
  441.  * @param {string} [options.suffix='fps']
  442.  *   Suffix text for each button after frequency.
  443.  * @returns {external:jQuery} Button-group node.
  444.  */
  445. export function insertFrequencyButtonGroup(node, {
  446.   animation,
  447.   frequencies,
  448.   btnGroupClass = 'btn-group',
  449.   btnClass = 'btn btn-primary',
  450.   suffix = 'fps'
  451. }) {
  452.   let btnGroup = $('<div>').addClass(btnGroupClass);
  453.   frequencies = frequencies ? frequencies : [];
  454.   frequencies.forEach(freq => {
  455.     btnGroup.append($('<button>')
  456.       .addClass(btnClass)
  457.       .data('frequency', freq)
  458.       .text(freq + ' ' + suffix)
  459.       .click(() => animation.setImageFrequency(freq)));
  460.   });
  461.   let onChange = () => {
  462.     btnGroup.children('button').removeClass('active').each(function () {
  463.       if ($(this).data('frequency') == animation.getImageFrequency())
  464.         $(this).addClass('active');
  465.     });
  466.   };
  467.   animation.on('change:imageFrequency', onChange);
  468.   onChange();
  469.   node.append(btnGroup);
  470.   return btnGroup;
  471. }
  473. /**
  474.  * Insert an input-group to change restart pause.
  475.  * 
  476.  * <pre><code>import { insertRestartPauseInput } from 'meteojs/timeline/Animation';</code></pre>
  477.  * 
  478.  * @param {external:jQuery} node - Node to insert input-group.
  479.  * @param {Object} options - Options for input-group.
  480.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  481.  *   Animation object.
  482.  * @param {string} [options.suffix='s'] - Suffix text for input-group.
  483.  * @returns {external:jQuery} Input-group node.
  484.  */
  485. export function insertRestartPauseInput(node, { animation, suffix = 's' }) {
  486.   const input = $('<input>')
  487.     .addClass('form-control')
  488.     .attr('type', 'number')
  489.     .attr('min', 0)
  490.     .attr('step', 0.1);
  491.   const inputGroupNumber = $('<div>')
  492.     .addClass('input-group')
  493.     .append(input)
  494.     .append($('<span>').addClass('input-group-text').text(suffix));
  495.   input.on('change', () => animation.setRestartPause(input.val()));
  496.   const onChange = () => input.val(animation.getRestartPause());
  497.   animation.on('change:restartPause', onChange);
  498.   onChange();
  499.   node.append(inputGroupNumber);
  500.   return inputGroupNumber;
  501. }
  503. /**
  504.  * Insert an input-range to change restart pause.
  505.  * 
  506.  * <pre><code>import { insertRestartPauseRange } from 'meteojs/timeline/Animation';</code></pre>
  507.  * 
  508.  * @param {external:jQuery} node - Node to insert input-range.
  509.  * @param {Object} options - Options for input-range.
  510.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  511.  *   Animation object.
  512.  * @param {number[]} options.pauses - Restart pauses to select.
  513.  * @returns {external:jQuery} Input-range node.
  514.  */
  515. export function insertRestartPauseRange(node, { animation, pauses }) {
  516.   pauses = pauses ? pauses : [1];
  517.   pauses = pauses.map(p => Math.round(p * 1000));
  518.   let range = $('<input>')
  519.     .addClass('form-range')
  520.     .attr('type', 'range')
  521.     .attr('min', 0)
  522.     .attr('max', pauses.length-1);
  523.   range.on('change input', () => {
  524.     let i = range.val();
  525.     if (i < pauses.length)
  526.       animation.setRestartPause(pauses[i] / 1000);
  527.   });
  528.   let onChangeImageFrequency = () => {
  529.     let i =
  530.       pauses.indexOf(Math.round(animation.getRestartPause() * 1000));
  531.     if (i > -1)
  532.       range.val(i);
  533.   };
  534.   animation.on('change:imageFrequency', onChangeImageFrequency);
  535.   onChangeImageFrequency();
  536.   node.append(range);
  537.   return range;
  538. }
  540. /**
  541.  * Insert an button-group to change restart pause.
  542.  * 
  543.  * <pre><code>import { insertRestartPauseButtonGroup } from 'meteojs/timeline/Animation';</code></pre>
  544.  * 
  545.  * @param {external:jQuery} node - Node to insert the button-group.
  546.  * @param {Object} options - Options for the button-group.
  547.  * @param {module:meteoJS/timeline/animation.Animation} options.animation
  548.  *   Animation object.
  549.  * @param {number[]} options.pauses - Restart pauses to select.
  550.  * @param {string|undefined} [options.btnGroupClass='btn-group']
  551.  *   Class added to the button-group node.
  552.  * @param {string|undefined} [options.btnClass='btn btn-primary']
  553.  *   Class added to each button.
  554.  * @param {string} [options.suffix='s']
  555.  *   Suffix in each button after duration text.
  556.  * @returns {external:jQuery} Button-group node.
  557.  */
  558. export function insertRestartPauseButtonGroup(node, {
  559.   animation,
  560.   pauses,
  561.   btnGroupClass = 'btn-group',
  562.   btnClass = 'btn btn-primary',
  563.   suffix = 's'
  564. }) {
  565.   let btnGroup = $('<div>').addClass(btnGroupClass);
  566.   pauses = pauses ? pauses : [];
  567.   pauses.forEach(pause => {
  568.     btnGroup.append($('<button>')
  569.       .addClass(btnClass)
  570.       .data('pause', pause)
  571.       .text(pause + ' ' + suffix)
  572.       .click(() => animation.setRestartPause(pause)));
  573.   });
  574.   let onChange = () => {
  575.     btnGroup.children('button').removeClass('active').each(function () {
  576.       if ($(this).data('pause') == animation.getRestartPause())
  577.         $(this).addClass('active');
  578.     });
  579.   };
  580.   animation.on('change:restartPause', onChange);
  581.   onChange();
  582.   node.append(btnGroup);
  583.   return btnGroup;
  584. }