diff --git a/CHANGELOG.md b/CHANGELOG.md index b4d47d00..56819915 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/src/item/Raster.js b/src/item/Raster.js index 6d784a58..ee279d96 100644 --- a/src/item/Raster.js +++ b/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,37 +82,61 @@ 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: - var image, - type = typeof source, - object = type === 'string' - ? document.getElementById(source) - : type === 'object' - ? 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) { - // See if the arguments describe the raster size: - var size = Size.read(arguments); - if (!size.isZero()) { - image = CanvasProvider.getCanvas(size); - } - } - } - + // 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' + ? document.getElementById(source) + : type === 'object' + ? source + : null; + if (object && object !== Item.NO_INSERT) { + if (object.getContent || object.naturalHeight != null) { + image = object; + } else if (object) { + // See if the arguments describe the raster size: + var size = Size.read(arguments); + if (!size.isZero()) { + image = CanvasProvider.getCanvas(size); + } + } + } 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 */) { diff --git a/test/tests/Raster.js b/test/tests/Raster.js index eb13e11a..32f56fbf 100644 --- a/test/tests/Raster.js +++ b/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)); +});