From 2a4cce941f13223ca5f7fb3bf774bc26738d6fb7 Mon Sep 17 00:00:00 2001 From: Flavio Silva <55815265+201flaviosilva@users.noreply.github.com> Date: Mon, 9 May 2022 18:31:35 +0100 Subject: [PATCH] [Engine]: Documenting the Text GameObejct (JS Doc) #65 --- package.json | 14 +- src/GameObjects/Text/Options.js | 3 + src/GameObjects/Text/Text.js | 364 +++++++++++++++++++++++++++++++- 3 files changed, 366 insertions(+), 15 deletions(-) diff --git a/package.json b/package.json index b28a376..5277f79 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,8 @@ "description": "A modular javascript canvas render", "homepage": "https://201flaviosilva.github.io/Impacto/", "main": "dist/Impacto.js", + "author": "Flávio Silva", + "license": "MIT", "scripts": { "clear": "rm -rf dist", "build": "npm run clear && webpack --mode production", @@ -27,19 +29,17 @@ }, "files": [ "dist", - "src" + "types" ], - "repository": { - "type": "git", - "url": "git+https://github.com/201flaviosilva/Impacto.git" - }, "keywords": [ "canvas", "game-engine", "rendering-engine" ], - "author": "Flávio Silva", - "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/201flaviosilva/Impacto.git" + }, "bugs": { "url": "https://github.com/201flaviosilva/Impacto/issues" } diff --git a/src/GameObjects/Text/Options.js b/src/GameObjects/Text/Options.js index e5a2eb6..09769cb 100644 --- a/src/GameObjects/Text/Options.js +++ b/src/GameObjects/Text/Options.js @@ -1,3 +1,6 @@ +/** + * All the options for the text object + */ const TextOptions = { font: { style: { diff --git a/src/GameObjects/Text/Text.js b/src/GameObjects/Text/Text.js index cad0408..80ff1c0 100644 --- a/src/GameObjects/Text/Text.js +++ b/src/GameObjects/Text/Text.js @@ -2,6 +2,24 @@ import GameObject2D from "../GameObject2D.js"; import { CanvasStateInstance } from "../../State/CanvasState.js"; import Types from "../Types.js"; +/** + * @param {number} x - The horizontal position of this Text in the world. + * @param {number} y - The vertical position of this Text in the world. + * @param {number} Text - The text will be drawn on the canvas. + * @param {number | string} [fillColor=0xffffff] - The color the Text will be filled with, i.e. 0xff0000 for red. + * @param {number | string} [strokeColor=0x000000] - The color of the border of the Text, i.e. 0x00ff00 for green. + * + * @classdesc + * This class will draw a text on the canvas. + * + * @example + * const myText = new Impacto.GameObjects.Text(400, 300, "Hello World", "#ff0000", 0x00ff00); + * + * @class Text + * @extends Impacto.GameObjects.GameObject2D + * @memberof Impacto.GameObjects + * @constructors + */ export default class Text extends GameObject2D { constructor(x, y, text = "", fillColor = "#000000", strokeColor = "#ffffff") { super(x, y, fillColor, strokeColor); @@ -23,75 +41,366 @@ export default class Text extends GameObject2D { this._type = Types.text; } + /** + * Returns the width of the text. + * + * @returns {number} The width of the text. + * @memberof Impacto.GameObjects.Text + */ get width() { if (this.text === "") return 0; return CanvasStateInstance.context.measureText(this.text, this.font).width; } + /** + * Returns the height of the text. + * + * @returns {number} The height of the text. + * @memberof Impacto.GameObjects.Text + */ get height() { if (this.text === "") return 0; return this.fontSize; } + /** + * Sets the horizontal position of the text. + * + * @param {string} align - The horizontal position of the text. + * @memberof Impacto.GameObjects.Text + */ set x(x) { this.setX(x); } + + /** + * Sets the vertical position of the text. + * + * @param {string} align - The vertical position of the text. + * @memberof Impacto.GameObjects.Text + */ set y(y) { this.setY(y); } - get x() { return this._x - this.width * this.origin.x * this.scale.x; } // Get the position X relative to the origin - get y() { return this._y - this.height * this.origin.y * this.scale.y; } // Get the position Y relative to the origin - // Get positions based on the origin + /** + * Returns the horizontal position of the text. + * + * @returns {number} The horizontal position of the text. + * @memberof Impacto.GameObjects.Text + */ + get x() { return this._x - this.width * this.origin.x * this.scale.x; } + + /** + * Returns the vertical position of the text. + * + * @returns {number} The vertical position of the text. + * @memberof Impacto.GameObjects.Text + */ + get y() { return this._y - this.height * this.origin.y * this.scale.y; } + + /** + * @description + * Returns the top side position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getTop(); // 300 + * + * @returns {number} The top side position of the text. + * @memberof Impacto.GameObjects.Text + */ getTop() { return this.y; } + + /** + * @description + * Returns the bottom side position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getBottom(); // 300 + * + * @returns {number} The bottom side position of the text. + * @memberof Impacto.GameObjects.Text + */ getBottom() { return this.y + this.height; } + + /** + * @description + * Returns the left side position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getLeft(); // 400 + * + * @returns {number} The left side position of the text. + * @memberof Impacto.GameObjects.Text + */ getLeft() { return this.x; } + + /** + * @description + * Returns the right side position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRight(); // 400 + * + * @returns {number} The right side position of the text. + * @memberof Impacto.GameObjects.Text + */ getRight() { return this.x + this.width; } + + /** + * @description + * Returns the horizontal center position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getCenterX(); // 400 + * + * @returns {number} The horizontal center position of the text. + * @memberof Impacto.GameObjects.Text + */ getCenterX() { return this.x + this.width / 2; } + + /** + * @description + * Returns the vertical center position of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getCenterY(); // 300 + * + * @returns {number} The vertical center position of the text. + * @memberof Impacto.GameObjects.Text + */ getCenterY() { return this.y + this.height / 2; } - // Get Real Positions + /** + * @description + * Returns the real top side position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealTop(); // 300 + * + * @returns {number} The real top side position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealTop() { return this._y; } + + /** + * @description + * Returns the real bottom side position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealBottom(); // 300 + * + * @returns {number} The real bottom side position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealBottom() { return this._y + this.height; } + + /** + * @description + * Returns the real left side position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealLeft(); // 400 + * + * @returns {number} The real left side position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealLeft() { return this._x; } + + /** + * @description + * Returns the real right side position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealRight(); // 400 + * + * @returns {number} The real right side position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealRight() { return this._x + this.width; } + + /** + * @description + * Returns the real horizontal center position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealCenterX(); // 400 + * + * @returns {number} The real horizontal center position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealCenterX() { return this._x + this.width / 2; } + + /** + * @description + * Returns the real vertical center position of the text. (The position of the text without the offset) + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getRealCenterY(); // 300 + * + * @returns {number} The real vertical center position of the text. + * @memberof Impacto.GameObjects.Text + */ getRealCenterY() { return this._y + this.height / 2; } + /** + * @description + * Returns all words of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getWords(); // ["Hello", "World"] + * + * @returns {string[]} All words of the text. + * @memberof Impacto.GameObjects.Text + */ getWords() { return this.text.split(" "); } + + /** + * @description + * Returns the number of words of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getWordsCount(); // 2 + * + * @returns {number} The number of words of the text. + * @memberof Impacto.GameObjects.Text + */ getWordsNumber() { return this.getWords().length; } + + /** + * @description + * Returns all characters of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getCharacters(); // ["H", "e", "l", "l", "o", " ", "W", "o", "r", "l", "d"] + * + * @returns {string[]} All characters of the text. + * @memberof Impacto.GameObjects.Text + */ getCharacters() { return this.text.split(""); } + + /** + * @description + * Returns the number of characters of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").getCharactersCount(); // 11 + * + * @returns {number} The number of characters of the text. + * @memberof Impacto.GameObjects.Text + */ getCharactersNumber() { return this.getCharacters().length; } - // Text + /** + * @description + * Change the display text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setText("MyText"); + * + * @param {string} text The new text. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setText(text) { this.text = text; return this; } - // Font + /** + * @description + * Change the font size. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFontSize(20); + * + * @param {number} size The new font size. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFontSize(size) { this.setFont({ size }); return this; } + /** + * @description + * Change the font family. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFontFamily("Arial"); + * + * @param {string} family The new font family. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFontFamily(family) { this.setFont({ family }); return this; } + /** + * @description + * Change the font style. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFontStyle("italic"); + * + * @param {string} style The new font style. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFontStyle(style) { this.setFont({ style }); return this; } + /** + * @description + * Change the font variant. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFontVariant("small-caps"); + * + * @param {string} variant The new font variant. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFontVariant(variant) { this.setFont({ variant }); return this; } + /** + * @description + * Change the font weight. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFontWeight("bold"); + * + * @param {string} weight The new font weight. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFontWeight(weight) { this.setFont({ weight }); return this; } + /** + * @description + * Change the font. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setFont({ + * size: 20, + * family: "Arial", + * style: "italic", + * variant: "small-caps", + * weight: "bold" + * }); + * + * @param {object} font The new properties of the font. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setFont(options) { // { size, family, style, variant, weight } this.fontSize = options.size || this.fontSize; this.fontFamily = options.family || this.fontFamily; @@ -102,23 +411,62 @@ export default class Text extends GameObject2D { return this; } - // Align + /** + * @description + * Change the vertical text alignment. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setVerticalAlignment("top"); + * + * @param {string} align The new text alignment. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setAlignVertical(align) { this.alignVertical = align; return this; } + /** + * @description + * Change the horizontal text alignment. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setHorizontalAlignment("left"); + * + * @param {string} align The new text alignment. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setAlignHorizontal(align) { this.alignHorizontal = align; return this; } + /** + * @description + * Change the direction of the text. + * + * @example + * new Impacto.GameObjects.Text(400, 300, "Hello World").setDirection("rtl"); + * + * @param {string} direction The new text direction. + * @returns {Impacto.GameObjects.Text} The text object. + * @memberof Impacto.GameObjects.Text + */ setDirection(direction) { this.direction = direction; return this; } - // Private + /** + * @description + * Private (Core) function to render the position of the text. + * + * @private + * @readonly + * @memberof Impacto.GameObjects.Text + */ _renderType() { CanvasStateInstance.context.textBaseline = this.alignVertical; CanvasStateInstance.context.textAlign = this.alignHorizontal;