Implement fabric.StaticCanvas#moveTo to move object to specified level in stack of drawn objects

You can also move fabric.Group objects in the grub objects stack to a specified level.

Add unit tests for moveTo.

src/object.class.js

@@ -1117,6 +1117,23 @@
         this.canvas.bringForward(this);
       }
       return this;
+    },
+
+    /**
+     * Moves an object to specified level in stack of drawn objects
+     * @method moveTo
+     * @param {Number} index New position of object
+     * @return {fabric.Object} thisArg
+     * @chainable
+     */
+    moveTo: function(index) {
+      if (this.group) {
+        fabric.StaticCanvas.prototype.moveTo.call(this.group, this, index);
+      }
+      else {
+        this.canvas.moveTo(this, index);
+      }
+      return this;
     }
   });
 

src/static_canvas.class.js

@@ -1100,6 +1100,20 @@
       return this.renderAll && this.renderAll();
     },
 
+    /**
+     * Moves an object to specified level in stack of drawn objects
+     * @method moveTo
+     * @param object {fabric.Object} Object to send
+     * @param {Number} index Position to move to
+     * @return {fabric.Canvas} thisArg
+     * @chainable
+     */
+    moveTo: function (object, index) {
+      removeFromArray(this._objects, object);
+      this._objects.splice(index, 0, object);
+      return this.renderAll && this.renderAll();
+    },
+
     /**
      * Clears a canvas element and removes all event handlers.
      * @method dispose

test/unit/canvas_static.js

@@ -491,6 +491,63 @@
     equal(canvas.item(2), rect3);
   });
 
+  test('moveTo', function() {
+    ok(typeof canvas.moveTo == 'function');
+
+    var rect1 = makeRect(),
+        rect2 = makeRect(),
+        rect3 = makeRect();
+
+    canvas.add(rect1, rect2, rect3);
+
+    // [ 1, 2, 3 ]
+    equal(canvas.item(0), rect1);
+    equal(canvas.item(1), rect2);
+    equal(canvas.item(2), rect3);
+
+    canvas.moveTo(rect3, 0);
+
+    // moved 3 to level 0 — [3, 1, 2]
+    equal(canvas.item(1), rect1);
+    equal(canvas.item(2), rect2);
+    equal(canvas.item(0), rect3);
+
+    canvas.moveTo(rect3, 1);
+
+    // moved 3 to level 1 — [1, 3, 2]
+    equal(canvas.item(0), rect1);
+    equal(canvas.item(2), rect2);
+    equal(canvas.item(1), rect3);
+
+    canvas.moveTo(rect3, 2);
+
+    // moved 3 to level 2 — [1, 2, 3]
+    equal(canvas.item(0), rect1);
+    equal(canvas.item(1), rect2);
+    equal(canvas.item(2), rect3);
+
+    canvas.moveTo(rect3, 2);
+
+    // moved 3 to same level 2 and so doesn't change position — [1, 2, 3]
+    equal(canvas.item(0), rect1);
+    equal(canvas.item(1), rect2);
+    equal(canvas.item(2), rect3);
+
+    canvas.moveTo(rect2, 0);
+
+    // moved 2 to level 0 — [2, 1, 3]
+    equal(canvas.item(1), rect1);
+    equal(canvas.item(0), rect2);
+    equal(canvas.item(2), rect3);
+
+    canvas.moveTo(rect2, 2);
+
+    // moved 2 to level 2 — [1, 3, 2]
+    equal(canvas.item(0), rect1);
+    equal(canvas.item(2), rect2);
+    equal(canvas.item(1), rect3);
+  });
+
   test('item', function() {
     ok(typeof canvas.item == 'function');
 

test/unit/group.js

@@ -13,6 +13,15 @@
     return new fabric.Group([ rect1, rect2 ]);
   }
 
+  function makeGroupWith4Objects() {
+    var rect1 = new fabric.Rect({ top: 100, left: 100, width: 30, height: 10 }),
+        rect2 = new fabric.Rect({ top: 120, left: 50, width: 10, height: 40 }),
+        rect3 = new fabric.Rect({ top: 40, left: 0, width: 20, height: 40 }),
+        rect4 = new fabric.Rect({ top: 75, left: 75, width: 40, height: 40 });
+
+    return new fabric.Group([ rect1, rect2, rect3, rect4 ]);
+  }
+
   QUnit.module('fabric.Group', {
     teardown: function() {
       canvas.clear();
@@ -174,6 +183,41 @@
     equal(group.item(9999), undefined);
   });
 
+  test('moveTo', function() {
+    var group = makeGroupWith4Objects(),
+        groupEl1 = group.getObjects()[0],
+        groupEl2 = group.getObjects()[1],
+        groupEl3 = group.getObjects()[2],
+        groupEl4 = group.getObjects()[3];
+
+    ok(typeof group.item(0).moveTo == 'function');
+
+    // [ 1, 2, 3, 4 ]
+    equal(group.item(0), groupEl1);
+    equal(group.item(1), groupEl2);
+    equal(group.item(2), groupEl3);
+    equal(group.item(3), groupEl4);
+    equal(group.item(9999), undefined);
+
+    group.item(0).moveTo(3);
+
+    // moved 1 to level 3 — [2, 3, 4, 1]
+    equal(group.item(3), groupEl1);
+    equal(group.item(0), groupEl2);
+    equal(group.item(1), groupEl3);
+    equal(group.item(2), groupEl4);
+    equal(group.item(9999), undefined);
+
+    group.item(0).moveTo(2);
+
+    // moved 2 to level 2 — [3, 4, 2, 1]
+    equal(group.item(3), groupEl1);
+    equal(group.item(2), groupEl2);
+    equal(group.item(0), groupEl3);
+    equal(group.item(1), groupEl4);
+    equal(group.item(9999), undefined);
+  });
+
   test('complexity', function() {
     var group = makeGroupWith2Objects();
 

test/unit/object.js

@@ -791,6 +791,12 @@
     ok(typeof object.bringToFront == 'function');
   });
 
+  test('moveTo', function() {
+    var object = new fabric.Object();
+
+    ok(typeof object.moveTo == 'function');
+  });
+
   test('gradient serialization', function() {
     var object = new fabric.Object();