**BREAKING** chainable methods to return animation abort fuction

broke a few other to maintain standard
fabricjs · Jan 19, 2022 · 865be3c · 865be3c
1 parent 7a406e8
commit 865be3c
Show file tree

Hide file tree

Showing 6 changed files with 30 additions and 64 deletions.
diff --git a/src/mixins/animation.mixin.js b/src/mixins/animation.mixin.js
@@ -13,8 +13,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
    * @param {Object} [callbacks] Callbacks object with optional "onComplete" and/or "onChange" properties
    * @param {Function} [callbacks.onComplete] Invoked on completion
    * @param {Function} [callbacks.onChange] Invoked on every step of animation
-   * @return {fabric.Canvas} thisArg
-   * @chainable
+   * @return {fabric.AnimationContext} context
    */
   fxCenterObjectH: function (object, callbacks) {
     callbacks = callbacks || { };
@@ -24,7 +23,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onChange = callbacks.onChange || empty,
         _this = this;
 
-    fabric.util.animate({
+    return fabric.util.animate({
       target: this,
       startValue: object.left,
       endValue: this.getCenter().left,
@@ -39,8 +38,6 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onComplete();
       }
     });
-
-    return this;
   },
 
   /**
@@ -49,8 +46,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
    * @param {Object} [callbacks] Callbacks object with optional "onComplete" and/or "onChange" properties
    * @param {Function} [callbacks.onComplete] Invoked on completion
    * @param {Function} [callbacks.onChange] Invoked on every step of animation
-   * @return {fabric.Canvas} thisArg
-   * @chainable
+   * @return {fabric.AnimationContext} context
    */
   fxCenterObjectV: function (object, callbacks) {
     callbacks = callbacks || { };
@@ -60,7 +56,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onChange = callbacks.onChange || empty,
         _this = this;
 
-    fabric.util.animate({
+    return fabric.util.animate({
       target: this,
       startValue: object.top,
       endValue: this.getCenter().top,
@@ -75,8 +71,6 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onComplete();
       }
     });
-
-    return this;
   },
 
   /**
@@ -85,8 +79,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
    * @param {Object} [callbacks] Callbacks object with optional "onComplete" and/or "onChange" properties
    * @param {Function} [callbacks.onComplete] Invoked on completion
    * @param {Function} [callbacks.onChange] Invoked on every step of animation
-   * @return {fabric.Canvas} thisArg
-   * @chainable
+   * @return {fabric.AnimationContext} context
    */
   fxRemove: function (object, callbacks) {
     callbacks = callbacks || { };
@@ -96,7 +89,7 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onChange = callbacks.onChange || empty,
         _this = this;
 
-    fabric.util.animate({
+    return fabric.util.animate({
       target: this,
       startValue: object.opacity,
       endValue: 0,
@@ -111,8 +104,6 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
         onComplete();
       }
     });
-
-    return this;
   }
 });
 
@@ -123,7 +114,7 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
    * @param {Number|Object} value Value to animate property to (if string was given first) or options object
    * @return {fabric.Object} thisArg
    * @tutorial {@link http://fabricjs.com/fabric-intro-part-2#animation}
-   * @chainable
+   * @return {fabric.AnimationContext | fabric.AnimationContext[]} animation context (or an array if passed multiple properties)
    *
    * As object — multiple properties
    *
@@ -136,22 +127,22 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
    * object.animate('left', { duration: ... });
    *
    */
-  animate: function() {
+  animate: function () {
     if (arguments[0] && typeof arguments[0] === 'object') {
-      var propsToAnimate = [], prop, skipCallbacks;
+      var propsToAnimate = [], prop, skipCallbacks, out = [];
       for (prop in arguments[0]) {
         propsToAnimate.push(prop);
       }
       for (var i = 0, len = propsToAnimate.length; i < len; i++) {
         prop = propsToAnimate[i];
         skipCallbacks = i !== len - 1;
-        this._animate(prop, arguments[0][prop], arguments[1], skipCallbacks);
+        out.push(this._animate(prop, arguments[0][prop], arguments[1], skipCallbacks));
       }
+      return out;
     }
     else {
-      this._animate.apply(this, arguments);
+      return this._animate.apply(this, arguments);
     }
-    return this;
   },
 
   /**

diff --git a/src/mixins/object_straightening.mixin.js b/src/mixins/object_straightening.mixin.js
@@ -15,11 +15,9 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
   /**
    * Straightens an object (rotating it from current angle to one of 0, 90, 180, 270, etc. depending on which is closer)
    * @return {fabric.Object} thisArg
-   * @chainable
    */
   straighten: function() {
     this.rotate(this._getAngleValueForStraighten());
-    return this;
   },
 
   /**
@@ -28,7 +26,6 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
    * @param {Function} [callbacks.onComplete] Invoked on completion
    * @param {Function} [callbacks.onChange] Invoked on every step of animation
    * @return {fabric.Object} thisArg
-   * @chainable
    */
   fxStraighten: function(callbacks) {
     callbacks = callbacks || { };
@@ -38,7 +35,7 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
         onChange = callbacks.onChange || empty,
         _this = this;
 
-    fabric.util.animate({
+    return fabric.util.animate({
       target: this,
       startValue: this.get('angle'),
       endValue: this._getAngleValueForStraighten(),
@@ -52,8 +49,6 @@ fabric.util.object.extend(fabric.Object.prototype, /** @lends fabric.Object.prot
         onComplete();
       },
     });
-
-    return this;
   }
 });
 
@@ -63,24 +58,20 @@ fabric.util.object.extend(fabric.StaticCanvas.prototype, /** @lends fabric.Stati
    * Straightens object, then rerenders canvas
    * @param {fabric.Object} object Object to straighten
    * @return {fabric.Canvas} thisArg
-   * @chainable
    */
   straightenObject: function (object) {
     object.straighten();
     this.requestRenderAll();
-    return this;
   },
 
   /**
    * Same as {@link fabric.Canvas.prototype.straightenObject}, but animated
    * @param {fabric.Object} object Object to straighten
    * @return {fabric.Canvas} thisArg
-   * @chainable
    */
   fxStraightenObject: function (object) {
-    object.fxStraighten({
+    return object.fxStraighten({
       onChange: this.requestRenderAllBound
     });
-    return this;
   }
 });
diff --git a/src/static_canvas.class.js b/src/static_canvas.class.js
@@ -1038,7 +1038,6 @@
     /**
      * Centers object horizontally in the canvas
      * @param {fabric.Object} object Object to center horizontally
-     * @return {fabric.Canvas} thisArg
      */
     centerObjectH: function (object) {
       return this._centerObject(object, new fabric.Point(this.getCenter().left, object.getCenterPoint().y));
@@ -1047,8 +1046,6 @@
     /**
      * Centers object vertically in the canvas
      * @param {fabric.Object} object Object to center vertically
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     centerObjectV: function (object) {
       return this._centerObject(object, new fabric.Point(object.getCenterPoint().x, this.getCenter().top));
@@ -1057,8 +1054,6 @@
     /**
      * Centers object vertically and horizontally in the canvas
      * @param {fabric.Object} object Object to center vertically and horizontally
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     centerObject: function(object) {
       var center = this.getCenter();
@@ -1069,8 +1064,6 @@
     /**
      * Centers object vertically and horizontally in the viewport
      * @param {fabric.Object} object Object to center vertically and horizontally
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     viewportCenterObject: function(object) {
       var vpCenter = this.getVpCenter();
@@ -1081,20 +1074,15 @@
     /**
      * Centers object horizontally in the viewport, object.top is unchanged
      * @param {fabric.Object} object Object to center vertically and horizontally
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     viewportCenterObjectH: function(object) {
       var vpCenter = this.getVpCenter();
-      this._centerObject(object, new fabric.Point(vpCenter.x, object.getCenterPoint().y));
-      return this;
+      return this._centerObject(object, new fabric.Point(vpCenter.x, object.getCenterPoint().y));
     },
 
     /**
      * Centers object Vertically in the viewport, object.top is unchanged
      * @param {fabric.Object} object Object to center vertically and horizontally
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     viewportCenterObjectV: function(object) {
       var vpCenter = this.getVpCenter();
@@ -1105,7 +1093,6 @@
     /**
      * Calculate the point in canvas that correspond to the center of actual viewport.
      * @return {fabric.Point} vpCenter, viewport center
-     * @chainable
      */
     getVpCenter: function() {
       var center = this.getCenter(),
@@ -1117,14 +1104,11 @@
      * @private
      * @param {fabric.Object} object Object to center
      * @param {fabric.Point} center Center point
-     * @return {fabric.Canvas} thisArg
-     * @chainable
      */
     _centerObject: function(object, center) {
       object.setPositionByOrigin(center, 'center', 'center');
       object.setCoords();
       this.renderOnAddRemove && this.requestRenderAll();
-      return this;
     },
 
     /**

diff --git a/test/unit/canvas.js b/test/unit/canvas.js
@@ -1275,23 +1275,23 @@
     assert.ok(typeof canvas.centerObjectH === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObjectH(rect), canvas, 'should be chainable');
+    canvas.centerObjectH(rect);
     assert.equal(rect.getCenterPoint().x, upperCanvasEl.width / 2, 'object\'s "left" property should correspond to canvas element\'s center');
   });
 
   QUnit.test('centerObjectV', function(assert) {
     assert.ok(typeof canvas.centerObjectV === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObjectV(rect), canvas, 'should be chainable');
+    canvas.centerObjectV(rect);
     assert.equal(rect.getCenterPoint().y, upperCanvasEl.height / 2, 'object\'s "top" property should correspond to canvas element\'s center');
   });
 
   QUnit.test('centerObject', function(assert) {
     assert.ok(typeof canvas.centerObject === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObject(rect), canvas, 'should be chainable');
+    canvas.centerObject(rect);
 
     assert.equal(rect.getCenterPoint().y, upperCanvasEl.height / 2, 'object\'s "top" property should correspond to canvas element\'s center');
     assert.equal(rect.getCenterPoint().x, upperCanvasEl.width / 2, 'object\'s "left" property should correspond to canvas element\'s center');
@@ -1301,7 +1301,7 @@
     assert.ok(typeof canvas.straightenObject === 'function');
     var rect = makeRect({ angle: 10 });
     canvas.add(rect);
-    assert.equal(canvas.straightenObject(rect), canvas, 'should be chainable');
+    canvas.straightenObject(rect);
     assert.equal(rect.get('angle'), 0, 'angle should be coerced to 0 (from 10)');
 
     rect.rotate('60');
@@ -2343,7 +2343,7 @@
     }
 
     assert.equal(canvas.item(0), rect);
-    assert.equal(canvas.fxRemove(rect, { onComplete: onComplete }), canvas, 'should be chainable');
+    assert.ok(typeof canvas.fxRemove(rect, { onComplete: onComplete }) === 'function', 'should return animation abort function');
 
     setTimeout(function() {
       assert.equal(canvas.item(0), undefined);

diff --git a/test/unit/canvas_static.js b/test/unit/canvas_static.js
@@ -657,7 +657,7 @@
     assert.ok(typeof canvas.centerObjectH === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObjectH(rect), canvas, 'should be chainable');
+    canvas.centerObjectH(rect);
     assert.equal(rect.getCenterPoint().x, canvas.width / 2, 'object\'s "center.y" property should correspond to canvas element\'s center');
     canvas.setZoom(4);
     assert.equal(rect.getCenterPoint().x, canvas.height / 2, 'object\'s "center.x" property should correspond to canvas element\'s center when canvas is transformed');
@@ -668,7 +668,7 @@
     assert.ok(typeof canvas.centerObjectV === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObjectV(rect), canvas, 'should be chainable');
+    canvas.centerObjectV(rect);
     assert.equal(rect.getCenterPoint().y, canvas.height / 2, 'object\'s "center.y" property should correspond to canvas element\'s center');
     canvas.setZoom(2);
     assert.equal(rect.getCenterPoint().y, canvas.height / 2, 'object\'s "center.y" property should correspond to canvas element\'s center when canvas is transformed');
@@ -679,7 +679,7 @@
     assert.ok(typeof canvas.centerObject === 'function');
     var rect = makeRect({ left: 102, top: 202 });
     canvas.add(rect);
-    assert.equal(canvas.centerObject(rect), canvas, 'should be chainable');
+    canvas.centerObject(rect);
 
     assert.equal(rect.getCenterPoint().y, canvas.height / 2, 'object\'s "center.y" property should correspond to canvas element\'s center');
     assert.equal(rect.getCenterPoint().x, canvas.height / 2, 'object\'s "center.x" property should correspond to canvas element\'s center');
@@ -695,7 +695,7 @@
     canvas.viewportTransform = [1, 0, 0, 1, 0, 0];
     canvas.add(rect);
     var oldY = rect.top;
-    assert.equal(canvas.viewportCenterObjectH(rect), canvas, 'should be chainable');
+    canvas.viewportCenterObjectH(rect);
     assert.equal(rect.getCenterPoint().x, canvas.width / 2, 'object\'s "center.x" property should correspond to canvas element\'s center when canvas is not transformed');
     assert.equal(rect.top, oldY, 'object\'s "top" should not change');
     canvas.setZoom(2);
@@ -714,7 +714,7 @@
     canvas.viewportTransform = [1, 0, 0, 1, 0, 0];
     canvas.add(rect);
     var oldX = rect.left;
-    assert.equal(canvas.viewportCenterObjectV(rect), canvas, 'should be chainable');
+    canvas.viewportCenterObjectV(rect);
     assert.equal(rect.getCenterPoint().y, canvas.height / 2, 'object\'s "center.y" property should correspond to canvas element\'s center when canvas is not transformed');
     assert.equal(rect.left, oldX, 'x position did not change');
     canvas.setZoom(2);
@@ -732,7 +732,7 @@
     var rect = makeRect({ left: 102, top: 202 }), pan = 10;
     canvas.viewportTransform = [1, 0, 0, 1, 0, 0];
     canvas.add(rect);
-    assert.equal(canvas.viewportCenterObject(rect), canvas, 'should be chainable');
+    canvas.viewportCenterObject(rect);
     assert.equal(rect.getCenterPoint().y, canvas.height / 2, 'object\'s "center.y" property should correspond to canvas element\'s center when canvas is not transformed');
     assert.equal(rect.getCenterPoint().x, canvas.width / 2, 'object\'s "center.x" property should correspond to canvas element\'s center when canvas is not transformed');
 
@@ -752,7 +752,7 @@
     assert.ok(typeof canvas.straightenObject === 'function');
     var rect = makeRect({ angle: 10 });
     canvas.add(rect);
-    assert.equal(canvas.straightenObject(rect), canvas, 'should be chainable');
+    canvas.straightenObject(rect);
     assert.equal(rect.get('angle'), 0, 'angle should be coerced to 0 (from 10)');
 
     rect.rotate('60');
@@ -1627,7 +1627,7 @@
     }
 
     assert.ok(canvas.item(0) === rect);
-    assert.equal(canvas.fxRemove(rect, { onComplete: onComplete }), canvas, 'should be chainable');
+    assert.ok(typeof canvas.fxRemove(rect, { onComplete: onComplete }) === 'function', 'should return animation abort function');
   });
 
   QUnit.test('options in setBackgroundImage from URL', function(assert) {

diff --git a/test/unit/object.js b/test/unit/object.js
@@ -569,13 +569,13 @@
 
     var callbacks = { onComplete: onComplete, onChange: onChange };
     assert.ok(typeof object.fxStraighten === 'function');
-    assert.equal(object.fxStraighten(callbacks), object, 'should be chainable');
+    assert.ok(typeof object.fxStraighten(callbacks) === 'function', 'should return animation abort function');
     assert.equal(fabric.util.toFixed(object.get('angle'), 0), 43);
     setTimeout(function(){
       assert.ok(onCompleteFired);
       assert.ok(onChangeFired);
       assert.equal(object.get('angle'), 0, 'angle should be set to 0 by the end of animation');
-      assert.equal(object.fxStraighten(), object, 'should work without callbacks');
+      assert.ok(typeof object.fxStraighten() === 'function', 'should work without callbacks');
       done();
     }, 1000);
   });