Renamed option `animate` to `animation`, and changed it to be either a boolean or an object `{duration: number, easingFunction: string}`

HISTORY.md

@@ -24,6 +24,8 @@ http://visjs.org
   `4-8h` to `h4-h8`.
 - Deprecated option `showCustomTime`. Use method `addCustomTime()` instead.
 - Deprecated event `finishedRedraw` as it's redundant.
+- Renamed option `animate` to `animation`, and changed it to be either a boolean
+  or an object `{duration: number, easingFunction: string}`.
 
 ### Network
 

docs/timeline.html

@@ -880,7 +880,8 @@ var options = {
     <td>Adjust the visible window such that it fits all items. See also function <code>focus(id)</code>.
       Available options:
       <ul>
-        <li><code>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>
+        <li><code>animation: boolean | {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.
+          </li>
       </ul>
     </td>
   </tr>
@@ -890,7 +891,7 @@ var options = {
     <td>none</td>
     <td>Adjust the visible window such that the selected item (or multiple items) are centered on screen. See also function <code>fit()</code>. Available options:
       <ul>
-        <li><code>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>
+        <li><code>animation: boolean | {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
       </ul>
     </td>
   </tr>
@@ -952,7 +953,7 @@ var options = {
     <td>none</td>
     <td>Move the window such that given time is centered on screen. Parameter <code>time</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. Available options:
       <ul>
-        <li><code>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>
+        <li><code>animation: boolean | {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
       </ul>
     </td>
   </tr>
@@ -1047,7 +1048,7 @@ var options = {
     <td>Select one or multiple items by their id. The currently selected items will be unselected. To unselect all selected items, call `setSelection([])`. Available options:
       <ul>
         <li><code>focus: boolean</code><br>If true, focus will be set to the selected item(s)</li>
-        <li><code>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms. Only applicable when option focus is true.</li>
+        <li><code>animation: boolean | {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Only applicable when option focus is true. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
       </ul>
     </td>
   </tr>
@@ -1057,7 +1058,7 @@ var options = {
     <td>none</td>
     <td>Set the current visible window. The parameters <code>start</code> and <code>end</code> can be a <code>Date</code>, <code>Number</code>, or <code>String</code>. If the parameter value of <code>start</code> or <code>end</code> is null, the parameter will be left unchanged. Available options:
       <ul>
-        <li><code>animate: boolean | number</code><br>If true (default), the range is animated smoothly to the new window. If a number, the number is taken as duration for the animation. Default duration is 500 ms.</li>
+        <li><code>animation: boolean | {duration: number, easingFunction: string}</code><br>If true (default) or an Object, the range is animated smoothly to the new window. An object can be provided to specify duration and easing function. Default duration is 500 ms, and default easing function is <code>'easeInOutQuad'</code>. Available easing functions: <code>"linear"</code>, <code>"easeInQuad"</code>, <code>"easeOutQuad"</code>, <code>"easeInOutQuad"</code>, <code>"easeInCubic"</code>, <code>"easeOutCubic"</code>, <code>"easeInOutCubic"</code>, <code>"easeInQuart"</code>, <code>"easeOutQuart"</code>, <code>"easeInOutQuart"</code>, <code>"easeInQuint"</code>, <code>"easeOutQuint"</code>, <code>"easeInOutQuint"</code>.</li>
       </ul>
     </td>
   </tr>
@@ -1065,6 +1066,7 @@ var options = {
 </table>
 
 
+
 <h2 id="Events">Events</h2>
 <p>
   Timeline fires events when changing the visible window by dragging, when

examples/timeline/13_past_and_future.html

@@ -81,7 +81,7 @@
   // set a custom range from -2 minute to +3 minutes current time
   var start = new Date((new Date()).getTime() - 2 * 60 * 1000);
   var end   = new Date((new Date()).getTime() + 3 * 60 * 1000);
-  timeline.setWindow(start, end, {animate: false});
+  timeline.setWindow(start, end, {animation: false});
 
 </script>
 

examples/timeline/22_window_adjustment.html

@@ -8,6 +8,9 @@
       font-family: arial, sans-serif;
       font-size: 11pt;
     }
+    input {
+      margin: 2px 0;
+    }
   </style>
 
   <script src="../../dist/vis.js"></script>
@@ -17,14 +20,16 @@
 
 <p>This example demonstrates functions to adjust the visible window of the Timeline.</p>
 
-<input type="button" id="window1" value="Set window from 2014-01-01 to 2014-04-01"><br>
-<input type="button" id="window2" value="Set window from 2014-01-01 to 2014-04-01 without animation"><br>
-<input type="button" id="fit" value="Fit all items"><br>
-<input type="button" id="select" value="Select & focus items 5 and 6"><br>
-<input type="button" id="focus1" value="Focus item 2"><br>
-<input type="button" id="focus2" value="Focus items 5 and 6 (slow animation)"><br>
-<input type="button" id="focus3" value="Focus current selection"><br>
-<input type="button" id="moveTo" value="Move to 2014-02-01"><br>
+<p>
+  <input type="button" id="window1" value="Set window from 2014-01-01 to 2014-04-01"><br>
+  <input type="button" id="window2" value="Set window from 2014-01-01 to 2014-04-01 without animation"><br>
+  <input type="button" id="moveTo" value="Move to 2014-02-01"><br>
+  <input type="button" id="fit" value="Fit all items"><br>
+  <input type="button" id="select" value="Select & focus items 5 and 6"><br>
+  <input type="button" id="focus1" value="Focus item 2"><br>
+  <input type="button" id="focus2" value="Focus items 5 and 6 (slow and linear animation)"><br>
+  <input type="button" id="focus3" value="Focus current selection"><br>
+</p>
 
 <div id="visualization"></div>
 
@@ -61,9 +66,7 @@
     timeline.setWindow('2014-01-01', '2014-04-01');
   };
   document.getElementById('window2').onclick = function() {
-    timeline.setWindow('2014-01-01', '2014-04-01', {
-      animate: false
-    });
+    timeline.setWindow('2014-01-01', '2014-04-01', {animation: false});
   };
   document.getElementById('fit').onclick = function() {
     timeline.fit();
@@ -77,9 +80,7 @@
     timeline.focus(2);
   };
   document.getElementById('focus2').onclick = function() {
-    timeline.focus([5, 6], {
-      animate: 3000 // ms
-    });
+    timeline.focus([5, 6], {animation: {duration: 3000, easingFunction: 'linear'}}); // ms
   };
   document.getElementById('focus3').onclick = function() {
     var selection = timeline.getSelection();

lib/timeline/Core.js

@@ -432,11 +432,12 @@ Core.prototype.getVisibleItems = function() {
 /**
  * Set Core window such that it fits all items
  * @param {Object} [options]  Available options:
- *                            `animate: boolean | number`
- *                                 If true (default), the range is animated
- *                                 smoothly to the new window.
- *                                 If a number, the number is taken as duration
- *                                 for the animation. Default duration is 500 ms.
+ *                                `animation: boolean | {duration: number, easingFunction: string}`
+ *                                    If true (default), the range is animated
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  */
 Core.prototype.fit = function(options) {
   var range = this._getDataRange();
@@ -446,8 +447,8 @@ Core.prototype.fit = function(options) {
     return;
   }
 
-  var animate = (options && options.animate !== undefined) ? options.animate : true;
-  this.range.setRange(range.start, range.end, animate);
+  var animation = (options && options.animation !== undefined) ? options.animation : true;
+  this.range.setRange(range.start, range.end, animation);
 };
 
 /**
@@ -492,22 +493,23 @@ Core.prototype._getDataRange = function() {
  * @param {Date | Number | String | Object} [start] Start date of visible window
  * @param {Date | Number | String} [end]            End date of visible window
  * @param {Object} [options]  Available options:
- *                            `animate: boolean | number`
- *                                 If true (default), the range is animated
- *                                 smoothly to the new window.
- *                                 If a number, the number is taken as duration
- *                                 for the animation. Default duration is 500 ms.
+ *                                `animation: boolean | {duration: number, easingFunction: string}`
+ *                                    If true (default), the range is animated
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  */
 Core.prototype.setWindow = function(start, end, options) {
-  var animate;
+  var animation;
   if (arguments.length == 1) {
     var range = arguments[0];
-    animate = (range.animate !== undefined) ? range.animate : true;
-    this.range.setRange(range.start, range.end, animate);
+    animation = (range.animation !== undefined) ? range.animation : true;
+    this.range.setRange(range.start, range.end, animation);
   }
   else {
-    animate = (options && options.animate !== undefined) ? options.animate : true;
-    this.range.setRange(start, end, animate);
+    animation = (options && options.animation !== undefined) ? options.animation : true;
+    this.range.setRange(start, end, animation);
   }
 };
 
@@ -515,11 +517,12 @@ Core.prototype.setWindow = function(start, end, options) {
  * Move the window such that given time is centered on screen.
  * @param {Date | Number | String} time
  * @param {Object} [options]  Available options:
- *                            `animate: boolean | number`
- *                                 If true (default), the range is animated
- *                                 smoothly to the new window.
- *                                 If a number, the number is taken as duration
- *                                 for the animation. Default duration is 500 ms.
+ *                                `animation: boolean | {duration: number, easingFunction: string}`
+ *                                    If true (default), the range is animated
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  */
 Core.prototype.moveTo = function(time, options) {
   var interval = this.range.end - this.range.start;
@@ -527,9 +530,9 @@ Core.prototype.moveTo = function(time, options) {
 
   var start = t - interval / 2;
   var end = t + interval / 2;
-  var animate = (options && options.animate !== undefined) ? options.animate : true;
+  var animation = (options && options.animation !== undefined) ? options.animation : true;
 
-  this.range.setRange(start, end, animate);
+  this.range.setRange(start, end, animation);
 };
 
 /**

lib/timeline/Graph2d.js

@@ -151,10 +151,10 @@ Graph2d.prototype.setItems = function(items) {
       var start = this.options.start != undefined ? this.options.start : null;
       var end   = this.options.end != undefined   ? this.options.end : null;
 
-      this.setWindow(start, end, {animate: false});
+      this.setWindow(start, end, {animation: false});
     }
     else {
-      this.fit({animate: false});
+      this.fit({animation: false});
     }
   }
 };

lib/timeline/Range.js

@@ -40,7 +40,7 @@ function Range(body, options) {
   this.props = {
     touch: {}
   };
-  this.animateTimer = null;
+  this.animationTimer = null;
 
   // drag listeners for dragging
   this.body.emitter.on('panstart', this._onDragStart.bind(this));
@@ -103,27 +103,35 @@ function validateDirection (direction) {
  * Set a new start and end range
  * @param {Date | Number | String} [start]
  * @param {Date | Number | String} [end]
- * @param {boolean | number} [animate=false]     If true, the range is animated
- *                                               smoothly to the new window.
- *                                               If animate is a number, the
- *                                               number is taken as duration
- *                                               Default duration is 500 ms.
+ * @param {boolean | {duration: number, easingFunction: string}} [animation=false]
+ *                                    If true (default), the range is animated
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  * @param {Boolean} [byUser=false]
  *
  */
-Range.prototype.setRange = function(start, end, animate, byUser) {
+Range.prototype.setRange = function(start, end, animation, byUser) {
   if (byUser !== true) {
     byUser = false;
   }
-  var _start = start != undefined ? util.convert(start, 'Date').valueOf() : null;
-  var _end   = end != undefined   ? util.convert(end, 'Date').valueOf()   : null;
+  var finalStart = start != undefined ? util.convert(start, 'Date').valueOf() : null;
+  var finalEnd   = end != undefined   ? util.convert(end, 'Date').valueOf()   : null;
   this._cancelAnimation();
 
-  if (animate) {
+  if (animation) { // true or an Object
     var me = this;
     var initStart = this.start;
     var initEnd = this.end;
-    var duration = typeof animate === 'number' ? animate : 500;
+    var duration = (typeof animation === 'object' && 'duration' in animation) ? animation.duration : 500;
+    var easingName = (typeof animation === 'object' && 'easingFunction' in animation) ? animation.easingFunction : 'easeInOutQuad';
+    var easingFunction = util.easingFunctions[easingName];
+    if (!easingFunction) {
+      throw new Error('Unknown easing function ' + JSON.stringify(easingName) + '. ' +
+          'Choose from: ' + Object.keys(util.easingFunctions).join(', '));
+    }
+
     var initTime = new Date().valueOf();
     var anyChanged = false;
 
@@ -131,9 +139,10 @@ Range.prototype.setRange = function(start, end, animate, byUser) {
       if (!me.props.touch.dragging) {
         var now = new Date().valueOf();
         var time = now - initTime;
+        var ease = easingFunction(time / duration);
         var done = time > duration;
-        var s = (done || _start === null) ? _start : util.easeInOutQuad(time, initStart, _start, duration);
-        var e = (done || _end === null)   ? _end   : util.easeInOutQuad(time, initEnd, _end, duration);
+        var s = (done || finalStart === null) ? finalStart : initStart + (finalStart - initStart) * ease;
+        var e = (done || finalEnd   === null) ? finalEnd   : initEnd   + (finalEnd   - initEnd)   * ease;
 
         changed = me._applyRange(s, e);
         DateUtil.updateHiddenDates(me.body, me.options.hiddenDates);
@@ -150,7 +159,7 @@ Range.prototype.setRange = function(start, end, animate, byUser) {
         else {
           // animate with as high as possible frame rate, leave 20 ms in between
           // each to prevent the browser from blocking
-          me.animateTimer = setTimeout(next, 20);
+          me.animationTimer = setTimeout(next, 20);
         }
       }
     };
@@ -158,7 +167,7 @@ Range.prototype.setRange = function(start, end, animate, byUser) {
     return next();
   }
   else {
-    var changed = this._applyRange(_start, _end);
+    var changed = this._applyRange(finalStart, finalEnd);
     DateUtil.updateHiddenDates(this.body, this.options.hiddenDates);
     if (changed) {
       var params = {start: new Date(this.start), end: new Date(this.end), byUser:byUser};
@@ -173,9 +182,9 @@ Range.prototype.setRange = function(start, end, animate, byUser) {
  * @private
  */
 Range.prototype._cancelAnimation = function () {
-  if (this.animateTimer) {
-    clearTimeout(this.animateTimer);
-    this.animateTimer = null;
+  if (this.animationTimer) {
+    clearTimeout(this.animationTimer);
+    this.animationTimer = null;
   }
 };
 

lib/timeline/Timeline.js

@@ -177,10 +177,10 @@ Timeline.prototype.setItems = function(items) {
       var start = this.options.start != undefined ? this.options.start : dataRange.start;
       var end   = this.options.end != undefined   ? this.options.end   : dataRange.end;
 
-      this.setWindow(start, end, {animate: false});
+      this.setWindow(start, end, {animation: false});
     }
     else {
-      this.fit({animate: false});
+      this.fit({animation: false});
     }
   }
 };
@@ -230,11 +230,12 @@ Timeline.prototype.setData = function (data) {
  * @param {Object} [options]      Available options:
  *                                `focus: boolean`
  *                                    If true, focus will be set to the selected item(s)
- *                                `animate: boolean | number`
+ *                                `animation: boolean | {duration: number, easingFunction: string}`
  *                                    If true (default), the range is animated
- *                                    smoothly to the new window.
- *                                    If a number, the number is taken as duration
- *                                    for the animation. Default duration is 500 ms.
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  *                                    Only applicable when option focus is true.
  */
 Timeline.prototype.setSelection = function(ids, options) {
@@ -258,12 +259,12 @@ Timeline.prototype.getSelection = function() {
  * are centered on screen.
  * @param {String | String[]} id     An item id or array with item ids
  * @param {Object} [options]      Available options:
- *                                `animate: boolean | number`
+ *                                `animation: boolean | {duration: number, easingFunction: string}`
  *                                    If true (default), the range is animated
- *                                    smoothly to the new window.
- *                                    If a number, the number is taken as duration
- *                                    for the animation. Default duration is 500 ms.
- *                                    Only applicable when option focus is true
+ *                                    smoothly to the new window. An object can be
+ *                                    provided to specify duration and easing function.
+ *                                    Default duration is 500 ms, and default easing
+ *                                    function is 'easeInOutQuad'.
  */
 Timeline.prototype.focus = function(id, options) {
   if (!this.itemsData || id == undefined) return;
@@ -299,8 +300,8 @@ Timeline.prototype.focus = function(id, options) {
     var middle = (start + end) / 2;
     var interval = Math.max((this.range.end - this.range.start), (end - start) * 1.1);
 
-    var animate = (options && options.animate !== undefined) ? options.animate : true;
-    this.range.setRange(middle - interval / 2, middle + interval / 2, animate);
+    var animation = (options && options.animation !== undefined) ? options.animation : true;
+    this.range.setRange(middle - interval / 2, middle + interval / 2, animation);
   }
 };
 

lib/util.js

@@ -1319,25 +1319,6 @@ exports.binarySearchValue = function(orderedItems, target, field, sidePreference
   return -1;
 };
 
-/**
- * Quadratic ease-in-out
- * http://gizma.com/easing/
- * @param {number} t        Current time
- * @param {number} start    Start value
- * @param {number} end      End value
- * @param {number} duration Duration
- * @returns {number} Value corresponding with current time
- */
-exports.easeInOutQuad = function (t, start, end, duration) {
-  var change = end - start;
-  t /= duration/2;
-  if (t < 1) return change/2*t*t + start;
-  t--;
-  return -change/2 * (t*(t-2) - 1) + start;
-};
-
-
-
 /*
  * Easing Functions - inspired from http://gizma.com/easing/
  * only considering the t value for the range [0, 1] => [0, 1]