diff --git a/packages/graphics/src/Graphics.js b/packages/graphics/src/Graphics.js index 9c6f491..7c11c8f 100644 --- a/packages/graphics/src/Graphics.js +++ b/packages/graphics/src/Graphics.js @@ -8,7 +8,7 @@ RoundedRectangle, Matrix, } from '@pixi/math'; -import { hex2rgb } from '@pixi/utils'; +import { hex2rgb, deprecation } from '@pixi/utils'; import { Texture, Shader, @@ -244,41 +244,91 @@ * Specifies the line style used for subsequent calls to Graphics methods such as the lineTo() * method or the drawCircle() method. * + * @method PIXI.Graphics#lineStyle * @param {number} [width=0] - width of the line to draw, will update the objects stored style - * @param {number} [color=0] - color of the line to draw, will update the objects stored style + * @param {number} [color=0x0] - color of the line to draw, will update the objects stored style * @param {number} [alpha=1] - alpha of the line to draw, will update the objects stored style * @param {number} [alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) * @param {boolean} [native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - lineStyle(width = 0, color = 0, alpha = 1, alignment = 0.5, native = false) + /** + * Specifies the line style used for subsequent calls to Graphics methods such as the lineTo() + * method or the drawCircle() method. + * + * @param {object} [options] - Line style options + * @param {number} [options.width=0] - width of the line to draw, will update the objects stored style + * @param {number} [options.color=0x0] - color of the line to draw, will update the objects stored style + * @param {number} [options.alpha=1] - alpha of the line to draw, will update the objects stored style + * @param {number} [options.alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) + * @param {boolean} [options.native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP + * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls + */ + lineStyle(options) { - this.lineTextureStyle(width, Texture.WHITE, color, alpha, null, alignment, native); + // Support non-object params: (width, color, alpha, alignment, native) + if (typeof options === 'number') + { + const args = arguments; - return this; + options = { + width: args[0] || 0, + color: args[1] || 0x0, + alpha: args[2] !== undefined ? args[2] : 1, + alignment: args[3] !== undefined ? args[3] : 0.5, + native: !!args[4], + }; + } + + return this.lineTextureStyle(options); } /** * Like line style but support texture for line fill. * - * @param {number} [width=0] - width of the line to draw, will update the objects stored style - * @param {PIXI.Texture} [texture=PIXI.Texture.WHITE] - Texture to use - * @param {number} [color=0] - color of the line to draw, will update the objects stored style - * @param {number} [alpha=1] - alpha of the line to draw, will update the objects stored style - * @param {PIXI.Matrix} [matrix=null] Texture matrix to transform texture - * @param {number} [alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) - * @param {boolean} [native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP + * @param {object} [options] - Collection of options for setting line style. + * @param {number} [options.width=0] - width of the line to draw, will update the objects stored style + * @param {PIXI.Texture} [options.texture=PIXI.Texture.WHITE] - Texture to use + * @param {number} [options.color=0x0] - color of the line to draw, will update the objects stored style + * @param {number} [options.alpha=1] - alpha of the line to draw, will update the objects stored style + * @param {PIXI.Matrix} [options.matrix=null] Texture matrix to transform texture + * @param {number} [options.alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) + * @param {boolean} [options.native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - lineTextureStyle(width = 0, texture = Texture.WHITE, color = 0xFFFFFF, alpha = 1, - matrix = null, alignment = 0.5, native = false) + lineTextureStyle(options) { + // backward compatibility with params: (width, texture, + // color, alpha, matrix, alignment, native) + if (typeof options === 'number') + { + deprecation('v5.2.0', 'Please use object-based options for Graphics#lineTextureStyle'); + + const [width, texture, color, alpha, matrix, alignment, native] = arguments; + + options = { width, texture, color, alpha, matrix, alignment, native }; + + // Remove undefined keys + Object.keys(options).forEach((key) => options[key] === undefined && delete options[key]); + } + + // Apply defaults + options = Object.assign({ + width: 0, + texture: Texture.WHITE, + color: 0x0, + alpha: 1, + matrix: null, + alignment: 0.5, + native: false, + }, options); + if (this.currentPath) { this.startPoly(); } - const visible = width > 0 && alpha > 0; + const visible = options.width > 0 && options.alpha > 0; if (!visible) { @@ -286,22 +336,13 @@ } else { - if (matrix) + if (options.matrix) { - matrix = matrix.clone(); - matrix.invert(); + options.matrix = options.matrix.clone(); + options.matrix.invert(); } - Object.assign(this._lineStyle, { - color, - width, - alpha, - matrix, - texture, - alignment, - native, - visible, - }); + Object.assign(this._lineStyle, { visible }, options); } return this; @@ -578,26 +619,48 @@ */ beginFill(color = 0, alpha = 1) { - return this.beginTextureFill(Texture.WHITE, color, alpha); + return this.beginTextureFill({ texture: Texture.WHITE, color, alpha }); } /** * Begin the texture fill * - * @param {PIXI.Texture} [texture=PIXI.Texture.WHITE] - Texture to fill - * @param {number} [color=0xffffff] - Background to fill behind texture - * @param {number} [alpha=1] - Alpha of fill - * @param {PIXI.Matrix} [matrix=null] - Transform matrix + * @param {object} [options] - Object object. + * @param {PIXI.Texture} [options.texture=PIXI.Texture.WHITE] - Texture to fill + * @param {number} [options.color=0xffffff] - Background to fill behind texture + * @param {number} [options.alpha=1] - Alpha of fill + * @param {PIXI.Matrix} [options.matrix=null] - Transform matrix * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - beginTextureFill(texture = Texture.WHITE, color = 0xFFFFFF, alpha = 1, matrix = null) + beginTextureFill(options) { + // backward compatibility with params: (texture, color, alpha, matrix) + if (typeof options === 'number') + { + deprecation('v5.2.0', 'Please use object-based options for Graphics#beginTextureFill'); + + const [texture, color, alpha, matrix] = arguments; + + options = { texture, color, alpha, matrix }; + + // Remove undefined keys + Object.keys(options).forEach((key) => options[key] === undefined && delete options[key]); + } + + // Apply defaults + options = Object.assign({ + texture: Texture.WHITE, + color: 0xFFFFFF, + alpha: 1, + matrix: null, + }, options); + if (this.currentPath) { this.startPoly(); } - const visible = alpha > 0; + const visible = options.alpha > 0; if (!visible) { @@ -605,19 +668,13 @@ } else { - if (matrix) + if (options.matrix) { - matrix = matrix.clone(); - matrix.invert(); + options.matrix = options.matrix.clone(); + options.matrix.invert(); } - Object.assign(this._fillStyle, { - color, - alpha, - texture, - matrix, - visible, - }); + Object.assign(this._fillStyle, { visible }, options); } return this; diff --git a/packages/graphics/src/Graphics.js b/packages/graphics/src/Graphics.js index 9c6f491..7c11c8f 100644 --- a/packages/graphics/src/Graphics.js +++ b/packages/graphics/src/Graphics.js @@ -8,7 +8,7 @@ RoundedRectangle, Matrix, } from '@pixi/math'; -import { hex2rgb } from '@pixi/utils'; +import { hex2rgb, deprecation } from '@pixi/utils'; import { Texture, Shader, @@ -244,41 +244,91 @@ * Specifies the line style used for subsequent calls to Graphics methods such as the lineTo() * method or the drawCircle() method. * + * @method PIXI.Graphics#lineStyle * @param {number} [width=0] - width of the line to draw, will update the objects stored style - * @param {number} [color=0] - color of the line to draw, will update the objects stored style + * @param {number} [color=0x0] - color of the line to draw, will update the objects stored style * @param {number} [alpha=1] - alpha of the line to draw, will update the objects stored style * @param {number} [alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) * @param {boolean} [native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - lineStyle(width = 0, color = 0, alpha = 1, alignment = 0.5, native = false) + /** + * Specifies the line style used for subsequent calls to Graphics methods such as the lineTo() + * method or the drawCircle() method. + * + * @param {object} [options] - Line style options + * @param {number} [options.width=0] - width of the line to draw, will update the objects stored style + * @param {number} [options.color=0x0] - color of the line to draw, will update the objects stored style + * @param {number} [options.alpha=1] - alpha of the line to draw, will update the objects stored style + * @param {number} [options.alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) + * @param {boolean} [options.native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP + * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls + */ + lineStyle(options) { - this.lineTextureStyle(width, Texture.WHITE, color, alpha, null, alignment, native); + // Support non-object params: (width, color, alpha, alignment, native) + if (typeof options === 'number') + { + const args = arguments; - return this; + options = { + width: args[0] || 0, + color: args[1] || 0x0, + alpha: args[2] !== undefined ? args[2] : 1, + alignment: args[3] !== undefined ? args[3] : 0.5, + native: !!args[4], + }; + } + + return this.lineTextureStyle(options); } /** * Like line style but support texture for line fill. * - * @param {number} [width=0] - width of the line to draw, will update the objects stored style - * @param {PIXI.Texture} [texture=PIXI.Texture.WHITE] - Texture to use - * @param {number} [color=0] - color of the line to draw, will update the objects stored style - * @param {number} [alpha=1] - alpha of the line to draw, will update the objects stored style - * @param {PIXI.Matrix} [matrix=null] Texture matrix to transform texture - * @param {number} [alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) - * @param {boolean} [native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP + * @param {object} [options] - Collection of options for setting line style. + * @param {number} [options.width=0] - width of the line to draw, will update the objects stored style + * @param {PIXI.Texture} [options.texture=PIXI.Texture.WHITE] - Texture to use + * @param {number} [options.color=0x0] - color of the line to draw, will update the objects stored style + * @param {number} [options.alpha=1] - alpha of the line to draw, will update the objects stored style + * @param {PIXI.Matrix} [options.matrix=null] Texture matrix to transform texture + * @param {number} [options.alignment=0.5] - alignment of the line to draw, (0 = inner, 0.5 = middle, 1 = outter) + * @param {boolean} [options.native=false] - If true the lines will be draw using LINES instead of TRIANGLE_STRIP * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - lineTextureStyle(width = 0, texture = Texture.WHITE, color = 0xFFFFFF, alpha = 1, - matrix = null, alignment = 0.5, native = false) + lineTextureStyle(options) { + // backward compatibility with params: (width, texture, + // color, alpha, matrix, alignment, native) + if (typeof options === 'number') + { + deprecation('v5.2.0', 'Please use object-based options for Graphics#lineTextureStyle'); + + const [width, texture, color, alpha, matrix, alignment, native] = arguments; + + options = { width, texture, color, alpha, matrix, alignment, native }; + + // Remove undefined keys + Object.keys(options).forEach((key) => options[key] === undefined && delete options[key]); + } + + // Apply defaults + options = Object.assign({ + width: 0, + texture: Texture.WHITE, + color: 0x0, + alpha: 1, + matrix: null, + alignment: 0.5, + native: false, + }, options); + if (this.currentPath) { this.startPoly(); } - const visible = width > 0 && alpha > 0; + const visible = options.width > 0 && options.alpha > 0; if (!visible) { @@ -286,22 +336,13 @@ } else { - if (matrix) + if (options.matrix) { - matrix = matrix.clone(); - matrix.invert(); + options.matrix = options.matrix.clone(); + options.matrix.invert(); } - Object.assign(this._lineStyle, { - color, - width, - alpha, - matrix, - texture, - alignment, - native, - visible, - }); + Object.assign(this._lineStyle, { visible }, options); } return this; @@ -578,26 +619,48 @@ */ beginFill(color = 0, alpha = 1) { - return this.beginTextureFill(Texture.WHITE, color, alpha); + return this.beginTextureFill({ texture: Texture.WHITE, color, alpha }); } /** * Begin the texture fill * - * @param {PIXI.Texture} [texture=PIXI.Texture.WHITE] - Texture to fill - * @param {number} [color=0xffffff] - Background to fill behind texture - * @param {number} [alpha=1] - Alpha of fill - * @param {PIXI.Matrix} [matrix=null] - Transform matrix + * @param {object} [options] - Object object. + * @param {PIXI.Texture} [options.texture=PIXI.Texture.WHITE] - Texture to fill + * @param {number} [options.color=0xffffff] - Background to fill behind texture + * @param {number} [options.alpha=1] - Alpha of fill + * @param {PIXI.Matrix} [options.matrix=null] - Transform matrix * @return {PIXI.Graphics} This Graphics object. Good for chaining method calls */ - beginTextureFill(texture = Texture.WHITE, color = 0xFFFFFF, alpha = 1, matrix = null) + beginTextureFill(options) { + // backward compatibility with params: (texture, color, alpha, matrix) + if (typeof options === 'number') + { + deprecation('v5.2.0', 'Please use object-based options for Graphics#beginTextureFill'); + + const [texture, color, alpha, matrix] = arguments; + + options = { texture, color, alpha, matrix }; + + // Remove undefined keys + Object.keys(options).forEach((key) => options[key] === undefined && delete options[key]); + } + + // Apply defaults + options = Object.assign({ + texture: Texture.WHITE, + color: 0xFFFFFF, + alpha: 1, + matrix: null, + }, options); + if (this.currentPath) { this.startPoly(); } - const visible = alpha > 0; + const visible = options.alpha > 0; if (!visible) { @@ -605,19 +668,13 @@ } else { - if (matrix) + if (options.matrix) { - matrix = matrix.clone(); - matrix.invert(); + options.matrix = options.matrix.clone(); + options.matrix.invert(); } - Object.assign(this._fillStyle, { - color, - alpha, - texture, - matrix, - visible, - }); + Object.assign(this._fillStyle, { visible }, options); } return this; diff --git a/packages/graphics/test/index.js b/packages/graphics/test/index.js index a2ccc35..fb74b25 100644 --- a/packages/graphics/test/index.js +++ b/packages/graphics/test/index.js @@ -1,5 +1,5 @@ // const MockPointer = require('../interaction/MockPointer'); -const { Renderer, BatchRenderer } = require('@pixi/core'); +const { Renderer, BatchRenderer, Texture } = require('@pixi/core'); const { Graphics, GRAPHICS_CURVES } = require('../'); const { BLEND_MODES } = require('@pixi/constants'); const { Point, Matrix } = require('@pixi/math'); @@ -26,6 +26,97 @@ }); }); + describe('lineStyle', function () + { + it('should support a list of parameters', function () + { + const graphics = new Graphics(); + + graphics.lineStyle(1, 0xff0000, 0.5, 1, true); + + expect(graphics.line.width).to.equal(1); + expect(graphics.line.color).to.equal(0xff0000); + expect(graphics.line.alignment).to.equal(1); + expect(graphics.line.alpha).to.equal(0.5); + expect(graphics.line.native).to.equal(true); + + graphics.destroy(); + }); + + it('should support object parameter', function () + { + const graphics = new Graphics(); + + graphics.lineStyle({ + width: 1, + alpha: 0.5, + color: 0xff0000, + alignment: 1, + native: true, + }); + + expect(graphics.line.width).to.equal(1); + expect(graphics.line.color).to.equal(0xff0000); + expect(graphics.line.alignment).to.equal(1); + expect(graphics.line.alpha).to.equal(0.5); + expect(graphics.line.native).to.equal(true); + expect(graphics.line.visible).to.equal(true); + + graphics.lineStyle(); + + expect(graphics.line.width).to.equal(0); + expect(graphics.line.color).to.equal(0); + expect(graphics.line.alignment).to.equal(0.5); + expect(graphics.line.alpha).to.equal(1); + expect(graphics.line.native).to.equal(false); + expect(graphics.line.visible).to.equal(false); + + graphics.destroy(); + }); + }); + + describe('lineTextureStyle', function () + { + it('should support object parameter', function () + { + const graphics = new Graphics(); + const matrix = new Matrix(); + const texture = Texture.BLACK; + + graphics.lineTextureStyle({ + width: 1, + alpha: 0.5, + color: 0xff0000, + matrix, + texture, + alignment: 1, + native: true, + }); + + expect(graphics.line.width).to.equal(1); + expect(graphics.line.texture).to.equal(texture); + expect(graphics.line.matrix).to.be.okay; + expect(graphics.line.color).to.equal(0xff0000); + expect(graphics.line.alignment).to.equal(1); + expect(graphics.line.alpha).to.equal(0.5); + expect(graphics.line.native).to.equal(true); + expect(graphics.line.visible).to.equal(true); + + graphics.lineTextureStyle(); + + expect(graphics.line.width).to.equal(0); + expect(graphics.line.texture).to.equal(Texture.WHITE); + expect(graphics.line.matrix).to.equal(null); + expect(graphics.line.color).to.equal(0); + expect(graphics.line.alignment).to.equal(0.5); + expect(graphics.line.alpha).to.equal(1); + expect(graphics.line.native).to.equal(false); + expect(graphics.line.visible).to.equal(false); + + graphics.destroy(); + }); + }); + describe('lineTo', function () { it('should return correct bounds - north', function ()