Improve new Raster(size[, position]) constructor

Closes #1621

CHANGELOG.md

@@ -1,12 +1,18 @@
 # Change Log
 
-## 0.12.1
+# `prebuilt`
+
+### Added
+
+- Improve `new Raster(size[, position])` constructor (#1621).
+
+# `0.12.1`
 
 ### Added
 
 - Add TypesScript definition, automatically generated from JSDoc comments
   (#1612).
-- Support `new Raster(size)` constructor.
+- Support `new Raster(size[, position])` constructor.
 - Expose `Raster#context` accessor.
 - Implement `Raster#clear()` method to clear associated canvas context.
 - Node.js: Add support for Node.js v11 and v12.

src/item/Raster.js

@@ -40,10 +40,11 @@ var Raster = Item.extend(/** @lends Raster# */{
     // TODO: Have SymbolItem & Raster inherit from a shared class?
     /**
      * Creates a new raster item from the passed argument, and places it in the
-     * active layer. `object` can either be a DOM Image, a Canvas, or a string
+     * active layer. `source` can either be a DOM Image, a Canvas, or a string
      * describing the URL to load the image from, or the ID of a DOM element to
      * get the image from (either a DOM Image or a Canvas).
      *
+     * @name Raster#initialize
      * @param {HTMLImageElement|HTMLCanvasElement|String} [source] the source of
      *     the raster
      * @param {Point} [position] the center position at which the raster item is
@@ -81,14 +82,41 @@ var Raster = Item.extend(/** @lends Raster# */{
      * raster.scale(0.5);
      * raster.rotate(10);
      */
+    /**
+     * Creates a new empty raster of the given size, and places it in the
+     * active layer.
+     *
+     * @name Raster#initialize
+     * @param {Size} size the size of the raster
+     * @param {Point} [position] the center position at which the raster item is
+     *     placed
+     *
+     * @example {@paperscript height=150}
+     * // Creating an empty raster and fill it with random pixels:
+     * var width = 100;
+     * var height = 100;
+     *
+     * // Create an empty raster placed at view center.
+     * var raster = new Raster(new Size(width, height), view.center);
+     *
+     * // For all of its pixels...
+     * for (var i = 0; i < width; i++) {
+     *     for (var j = 0; j < height; j++) {
+     *         // ...set a random color.
+     *         raster.setPixel(i, j, Color.random());
+     *     }
+     * }
+     */
     initialize: function Raster(source, position) {
-        // Support two forms of item initialization: Passing one object literal
-        // describing all the different properties to be set, or an image
-        // (object) and a point where it should be placed (point).
+        // Support three forms of item initialization:
+        // - One object literal describing all the different properties.
+        // - An image (Image|Canvas|String) and an optional position (Point).
+        // - A size (Size) describing the canvas that will be  created and an
+        //   optional position (Point).
         // If _initialize can set properties through object literal, we're done.
-        // Otherwise we need to check the type of object:
-
-        // source can be an image, canvas, source URL or DOM-ID:
+        // Otherwise we need to check the type of object:       var image,
+        if (!this._initialize(source,
+                position !== undefined && Point.read(arguments))) {
             var image,
                 type = typeof source,
                 object = type === 'string'
@@ -97,7 +125,6 @@ var Raster = Item.extend(/** @lends Raster# */{
                         ? source
                         : null;
             if (object && object !== Item.NO_INSERT) {
-            // #setImage() handles both canvas and image types.
                 if (object.getContent || object.naturalHeight != null) {
                     image = object;
                 } else if (object) {
@@ -108,10 +135,8 @@ var Raster = Item.extend(/** @lends Raster# */{
                     }
                 }
             }
-
-        if (!this._initialize(source,
-                position !== undefined && Point.read(arguments))) {
             if (image) {
+                // #setImage() handles both canvas and image types.
                 this.setImage(image);
             } else {
                 this.setSource(source);
@@ -641,7 +666,8 @@ var Raster = Item.extend(/** @lends Raster# */{
      *
      * @name Raster#getPixel
      * @function
-     * @param {Point} point the offset of the pixel as a point in pixel coordinates
+     * @param {Point} point the offset of the pixel as a point in pixel
+     *     coordinates
      * @return {Color} the color of the pixel
      */
     getPixel: function(/* point */) {
@@ -666,7 +692,8 @@ var Raster = Item.extend(/** @lends Raster# */{
      *
      * @name Raster#setPixel
      * @function
-     * @param {Point} point the offset of the pixel as a point in pixel coordinates
+     * @param {Point} point the offset of the pixel as a point in pixel
+     *     coordinates
      * @param {Color} color the color that the pixel will be set to
      */
     setPixel: function(/* point, color */) {

test/tests/Raster.js

@@ -206,3 +206,31 @@ test('Raster#setSmoothing setting does not impact canvas context', function(asse
         done();
     };
 });
+
+test('new Raster(size[, position])', function() {
+    // Size only.
+    var raster = new Raster(new Size(100, 100));
+    equals(raster.position, new Point(0, 0));
+    equals(raster.bounds, new Rectangle(-50, -50, 100, 100));
+
+    var raster = new Raster({size:new Size(100, 100)});
+    equals(raster.position, new Point(0, 0));
+    equals(raster.bounds, new Rectangle(-50, -50, 100, 100));
+
+    var raster = new Raster({width:100, height:100});
+    equals(raster.position, new Point(0, 0));
+    equals(raster.bounds, new Rectangle(-50, -50, 100, 100));
+
+    // Size and position.
+    var raster = new Raster(new Size(100, 100), new Point(100, 100));
+    equals(raster.position, new Point(100, 100));
+    equals(raster.bounds, new Rectangle(50, 50, 100, 100));
+
+    var raster = new Raster({size:new Size(100, 100), position:new Point(100, 100)});
+    equals(raster.position, new Point(100, 100));
+    equals(raster.bounds, new Rectangle(50, 50, 100, 100));
+
+    var raster = new Raster({width:100, height:100, position:new Point(100, 100)});
+    equals(raster.position, new Point(100, 100));
+    equals(raster.bounds, new Rectangle(50, 50, 100, 100));
+});