@vpmedia/phaser 1.15.0 → 1.16.0

package/src/phaser/display/text.js

@@ -1,15 +1,9 @@
-/**
- * @module display/text
- * @copyright    Copyright (c) 2018-present Richard Davey, Photon Storm Ltd., Andras Csizmadia <andras@vpmedia.hu> (www.vpmedia.hu)
- * @author       Andras Csizmadia <andras@vpmedia.hu>
- * @author       Richard Davey <rich@photonstorm.com>
- */
 import { Point } from '../geom/point';
-import { Rectangle } from  '../geom/rectangle';
+import { Rectangle } from '../geom/rectangle';
 import { Image } from './image';
 import { create, remove } from './canvas/pool';
 import { textureFromCanvas } from './webgl/texture_util';
-import { Game } from  '../core/game';
+import { Game } from '../core/game';
 import { TEXT } from '../core/const';
 import { snapToCeil } from '../util/math';
 import { renderCanvas, renderWebGL, getBounds } from './sprite_util';
@@ -52,6 +46,9 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   */
   destroy() {
     this.texture.destroy(true);
     remove(this);
@@ -69,14 +66,16 @@ export class Text extends Image {
     super.destroy();
   }
 
-  setShadow(
-    x = 0,
-    y = 0,
-    color = 'rgba(0, 0, 0, 1)',
-    blur = 0,
-    shadowStroke = true,
-    shadowFill = true
-  ) {
+  /**
+   * TBD.
+   * @param {number} x - TBD.
+   * @param {number} y - TBD.
+   * @param color - TBD.
+   * @param blur
+   * @param shadowStroke
+   * @param shadowFill
+   */
+  setShadow(x = 0, y = 0, color = 'rgba(0, 0, 0, 1)', blur = 0, shadowStroke = true, shadowFill = true) {
     this.style.shadowOffsetX = x;
     this.style.shadowOffsetY = y;
     this.style.shadowColor = color;
@@ -87,6 +86,11 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param style
+   * @param update
+   */
   setStyle(style = null, update = false) {
     style = JSON.parse(JSON.stringify(style)) || {};
     style.font = style.font || 'bold 20pt Arial';
@@ -131,6 +135,9 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   */
   updateText() {
     this.texture.baseTexture.resolution = this._res;
     this.context.font = this.style.font;
@@ -288,6 +295,13 @@ export class Text extends Image {
     this.dirty = false;
   }
 
+  /**
+   * TBD.
+   * @param line
+   * @param {number} x - TBD.
+   * @param {number} y - TBD.
+   * @param fill
+   */
   renderTabLine(line, x, y, fill) {
     const text = line.split(/(?:\t)/);
     const tabs = this.style.tabs;
@@ -320,6 +334,10 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @param state
+   */
   updateShadow(state) {
     if (state) {
       this.context.shadowOffsetX = this.style.shadowOffsetX;
@@ -334,6 +352,10 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @param line
+   */
   measureLine(line) {
     let lineLength = 0;
     for (let i = 0; i < line.length; i += 1) {
@@ -366,6 +388,12 @@ export class Text extends Image {
     return Math.ceil(lineLength);
   }
 
+  /**
+   * TBD.
+   * @param line
+   * @param {number} x - TBD.
+   * @param {number} y - TBD.
+   */
   updateLine(line, x, y) {
     for (let i = 0; i < line.length; i += 1) {
       const letter = line[i];
@@ -398,6 +426,9 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   */
   clearColors() {
     this.colors = [];
     this.strokeColors = [];
@@ -405,6 +436,9 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   */
   clearFontValues() {
     this.fontStyles = [];
     this.fontWeights = [];
@@ -412,30 +446,54 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param color - TBD.
+   * @param position - TBD.
+   */
   addColor(color, position) {
     this.colors[position] = color;
     this.dirty = true;
     return this;
   }
 
+  /**
+   * TBD.
+   * @param color - TBD.
+   * @param position - TBD.
+   */
   addStrokeColor(color, position) {
     this.strokeColors[position] = color;
     this.dirty = true;
     return this;
   }
 
+  /**
+   * TBD.
+   * @param style
+   * @param position - TBD.
+   */
   addFontStyle(style, position) {
     this.fontStyles[position] = style;
     this.dirty = true;
     return this;
   }
 
+  /**
+   * TBD.
+   * @param weight
+   * @param position - TBD.
+   */
   addFontWeight(weight, position) {
     this.fontWeights[position] = weight;
     this.dirty = true;
     return this;
   }
 
+  /**
+   * TBD.
+   * @param text - TBD.
+   */
   precalculateWordWrap(text) {
     this.texture.baseTexture.resolution = this._res;
     this.context.font = this.style.font;
@@ -443,6 +501,10 @@ export class Text extends Image {
     return wrappedLines.split(/(?:\r\n|\r|\n)/);
   }
 
+  /**
+   * TBD.
+   * @param text - TBD.
+   */
   runWordWrap(text) {
     if (this.useAdvancedWrap) {
       return this.advancedWordWrap(text);
@@ -450,6 +512,10 @@ export class Text extends Image {
     return this.basicWordWrap(text);
   }
 
+  /**
+   * TBD.
+   * @param text - TBD.
+   */
   advancedWordWrap(text) {
     const context = this.context;
     const wordWrapWidth = this.style.wordWrapWidth;
@@ -492,9 +558,7 @@ export class Text extends Image {
               // if wordWrapWidth is too small for even a single
               // letter, shame user failure with a fatal error
               if (!newWord.length) {
-                throw new Error(
-                  "This text's wordWrapWidth setting is less than a single character!"
-                );
+                throw new Error("This text's wordWrapWidth setting is less than a single character!");
               }
               // replace current word in array with remainder
               const secondPart = word.substr(newWord.length);
@@ -529,6 +593,10 @@ export class Text extends Image {
     return output;
   }
 
+  /**
+   * TBD.
+   * @param text - TBD.
+   */
   basicWordWrap(text) {
     let result = '';
     const lines = text.split('\n');
@@ -557,6 +625,10 @@ export class Text extends Image {
     return result;
   }
 
+  /**
+   * TBD.
+   * @param components
+   */
   updateFont(components) {
     const font = this.componentsToFont(components);
     if (this.style.font !== font) {
@@ -568,6 +640,10 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @param font - TBD.
+   */
   fontToComponents(font) {
     // The format is specified in http://www.w3.org/TR/CSS2/fonts.html#font-shorthand:
     // style - normal | italic | oblique | inherit
@@ -583,10 +659,7 @@ export class Text extends Image {
     if (m) {
       let family = m[5].trim();
       // If it looks like the value should be quoted, but isn't, then quote it.
-      if (
-        !/^(?:inherit|serif|sans-serif|cursive|fantasy|monospace)$/.exec(family) &&
-        !/['",]/.exec(family)
-      ) {
+      if (!/^(?:inherit|serif|sans-serif|cursive|fantasy|monospace)$/.exec(family) && !/['",]/.exec(family)) {
         family = "'" + family + "'";
       }
       return {
@@ -602,6 +675,10 @@ export class Text extends Image {
     return { font };
   }
 
+  /**
+   * TBD.
+   * @param components
+   */
   componentsToFont(components) {
     const parts = [];
     let v;
@@ -632,6 +709,11 @@ export class Text extends Image {
     return parts.join(' ');
   }
 
+  /**
+   * TBD.
+   * @param text - TBD.
+   * @param immediate
+   */
   setText(text, immediate = false) {
     this.text = text.toString() || '';
     if (immediate) {
@@ -642,6 +724,10 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param list
+   */
   parseList(list) {
     if (!Array.isArray(list)) {
       return this;
@@ -665,6 +751,13 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   * @param {number} x - TBD.
+   * @param {number} y - TBD.
+   * @param {number} width - TBD.
+   * @param {number} height - TBD.
+   */
   setTextBounds(x, y, width, height) {
     if (x === undefined) {
       this.textBounds = null;
@@ -682,6 +775,9 @@ export class Text extends Image {
     return this;
   }
 
+  /**
+   * TBD.
+   */
   updateTexture() {
     const base = this.texture.baseTexture;
     const crop = this.texture.crop;
@@ -721,6 +817,10 @@ export class Text extends Image {
     this.texture.baseTexture.dirty();
   }
 
+  /**
+   * TBD.
+   * @param renderSession - TBD.
+   */
   renderWebGL(renderSession) {
     if (this.dirty) {
       this.updateText();
@@ -729,6 +829,10 @@ export class Text extends Image {
     renderWebGL(this, renderSession);
   }
 
+  /**
+   * TBD.
+   * @param renderSession - TBD.
+   */
   renderCanvas(renderSession) {
     if (this.dirty) {
       this.updateText();
@@ -737,6 +841,9 @@ export class Text extends Image {
     renderCanvas(this, renderSession);
   }
 
+  /**
+   * TBD.
+   */
   getFontPropertiesCache() {
     if (!window.PhaserRegistry.fontPropertiesCache) {
       window.PhaserRegistry.fontPropertiesCache = {};
@@ -744,6 +851,9 @@ export class Text extends Image {
     return window.PhaserRegistry.fontPropertiesCache;
   }
 
+  /**
+   * TBD.
+   */
   getFontPropertiesCanvas() {
     if (!window.PhaserRegistry.fontPropertiesCanvas) {
       window.PhaserRegistry.fontPropertiesCanvas = document.createElement('canvas');
@@ -751,16 +861,22 @@ export class Text extends Image {
     return window.PhaserRegistry.fontPropertiesCanvas;
   }
 
+  /**
+   * TBD.
+   */
   getFontPropertiesContext() {
     if (!window.PhaserRegistry.fontPropertiesContext) {
-      window.PhaserRegistry.fontPropertiesContext = this.getFontPropertiesCanvas().getContext(
-        '2d',
-        { willReadFrequently: true }
-      );
+      window.PhaserRegistry.fontPropertiesContext = this.getFontPropertiesCanvas().getContext('2d', {
+        willReadFrequently: true,
+      });
     }
     return window.PhaserRegistry.fontPropertiesContext;
   }
 
+  /**
+   * TBD.
+   * @param fontStyle
+   */
   determineFontProperties(fontStyle) {
     const fontPropertiesCache = this.getFontPropertiesCache();
     let properties = fontPropertiesCache[fontStyle];
@@ -835,6 +951,11 @@ export class Text extends Image {
     return properties;
   }
 
+  /**
+   * TBD.
+   * @param matrix - TBD.
+   * @returns {Rectangle} TBD.
+   */
   getBounds(matrix = null) {
     if (this.dirty) {
       this.updateText();
@@ -843,10 +964,17 @@ export class Text extends Image {
     return getBounds(this, matrix);
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get text() {
     return this._text;
   }
 
+  /**
+   * TBD.
+   */
   set text(value) {
     if (value !== this._text) {
       this._text = value.toString() || '';
@@ -857,27 +985,38 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get cssFont() {
     return this.componentsToFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   */
   set cssFont(value) {
     this._fontComponents = this.fontToComponents(value || 'bold 20pt Arial');
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get font() {
     return this._fontComponents.fontFamily;
   }
 
+  /**
+   * TBD.
+   */
   set font(value) {
     let mutatedValue = value || 'Arial';
     mutatedValue = mutatedValue.trim();
     // If it looks like the value should be quoted, but isn't, then quote it.
-    if (
-      !/^(?:inherit|serif|sans-serif|cursive|fantasy|monospace)$/.exec(mutatedValue) &&
-      !/['",]/.exec(mutatedValue)
-    ) {
+    if (!/^(?:inherit|serif|sans-serif|cursive|fantasy|monospace)$/.exec(mutatedValue) && !/['",]/.exec(mutatedValue)) {
       mutatedValue = "'" + mutatedValue + "'";
     }
 
@@ -885,6 +1024,10 @@ export class Text extends Image {
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get fontSize() {
     const size = this._fontComponents.fontSize;
     if (size && /(?:^0$|px$)/.exec(size)) {
@@ -893,6 +1036,9 @@ export class Text extends Image {
     return size;
   }
 
+  /**
+   * TBD.
+   */
   set fontSize(value) {
     let mutatedValue = value || '0';
     if (typeof mutatedValue === 'number') {
@@ -902,37 +1048,65 @@ export class Text extends Image {
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get fontWeight() {
     return this._fontComponents.fontWeight || 'normal';
   }
 
+  /**
+   * TBD.
+   */
   set fontWeight(value) {
     this._fontComponents.fontWeight = value || 'normal';
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get fontStyle() {
     return this._fontComponents.fontStyle || 'normal';
   }
 
+  /**
+   * TBD.
+   */
   set fontStyle(value) {
     this._fontComponents.fontStyle = value || 'normal';
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get fontVariant() {
     return this._fontComponents.fontVariant || 'normal';
   }
 
+  /**
+   * TBD.
+   */
   set fontVariant(value) {
     this._fontComponents.fontVariant = value || 'normal';
     this.updateFont(this._fontComponents);
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get fill() {
     return this.style.fill;
   }
 
+  /**
+   * TBD.
+   */
   set fill(value) {
     if (value !== this.style.fill) {
       this.style.fill = value;
@@ -940,10 +1114,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {string} TBD.
+   */
   get align() {
     return this.style.align;
   }
 
+  /**
+   * TBD.
+   */
   set align(value) {
     if (value !== this.style.align) {
       this.style.align = value;
@@ -951,10 +1132,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get resolution() {
     return this._res;
   }
 
+  /**
+   * TBD.
+   */
   set resolution(value) {
     if (value !== this._res) {
       this._res = value;
@@ -962,10 +1150,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get tabs() {
     return this.style.tabs;
   }
 
+  /**
+   * TBD.
+   */
   set tabs(value) {
     if (value !== this.style.tabs) {
       this.style.tabs = value;
@@ -973,10 +1168,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get boundsAlignH() {
     return this.style.boundsAlignH;
   }
 
+  /**
+   * TBD.
+   */
   set boundsAlignH(value) {
     if (value !== this.style.boundsAlignH) {
       this.style.boundsAlignH = value;
@@ -984,10 +1186,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get boundsAlignV() {
     return this.style.boundsAlignV;
   }
 
+  /**
+   * TBD.
+   */
   set boundsAlignV(value) {
     if (value !== this.style.boundsAlignV) {
       this.style.boundsAlignV = value;
@@ -995,10 +1204,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get stroke() {
     return this.style.stroke;
   }
 
+  /**
+   * TBD.
+   */
   set stroke(value) {
     if (value !== this.style.stroke) {
       this.style.stroke = value;
@@ -1006,10 +1222,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get strokeThickness() {
     return this.style.strokeThickness;
   }
 
+  /**
+   * TBD.
+   */
   set strokeThickness(value) {
     if (value !== this.style.strokeThickness) {
       this.style.strokeThickness = value;
@@ -1017,10 +1240,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get wordWrap() {
     return this.style.wordWrap;
   }
 
+  /**
+   * TBD.
+   */
   set wordWrap(value) {
     if (value !== this.style.wordWrap) {
       this.style.wordWrap = value;
@@ -1028,10 +1258,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get wordWrapWidth() {
     return this.style.wordWrapWidth;
   }
 
+  /**
+   * TBD.
+   */
   set wordWrapWidth(value) {
     if (value !== this.style.wordWrapWidth) {
       this.style.wordWrapWidth = value;
@@ -1039,10 +1276,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get lineSpacing() {
     return this._lineSpacing;
   }
 
+  /**
+   * TBD.
+   */
   set lineSpacing(value) {
     if (value !== this._lineSpacing) {
       this._lineSpacing = parseFloat(value);
@@ -1053,10 +1297,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowOffsetX() {
     return this.style.shadowOffsetX;
   }
 
+  /**
+   * TBD.
+   */
   set shadowOffsetX(value) {
     if (value !== this.style.shadowOffsetX) {
       this.style.shadowOffsetX = value;
@@ -1064,10 +1315,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowOffsetY() {
     return this.style.shadowOffsetY;
   }
 
+  /**
+   * TBD.
+   */
   set shadowOffsetY(value) {
     if (value !== this.style.shadowOffsetY) {
       this.style.shadowOffsetY = value;
@@ -1075,10 +1333,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowColor() {
     return this.style.shadowColor;
   }
 
+  /**
+   * TBD.
+   */
   set shadowColor(value) {
     if (value !== this.style.shadowColor) {
       this.style.shadowColor = value;
@@ -1086,10 +1351,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowBlur() {
     return this.style.shadowBlur;
   }
 
+  /**
+   * TBD.
+   */
   set shadowBlur(value) {
     if (value !== this.style.shadowBlur) {
       this.style.shadowBlur = value;
@@ -1097,10 +1369,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowStroke() {
     return this.style.shadowStroke;
   }
 
+  /**
+   * TBD.
+   */
   set shadowStroke(value) {
     if (value !== this.style.shadowStroke) {
       this.style.shadowStroke = value;
@@ -1108,10 +1387,17 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get shadowFill() {
     return this.style.shadowFill;
   }
 
+  /**
+   * TBD.
+   */
   set shadowFill(value) {
     if (value !== this.style.shadowFill) {
       this.style.shadowFill = value;
@@ -1119,6 +1405,10 @@ export class Text extends Image {
     }
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get width() {
     if (this.dirty) {
       this.updateText();
@@ -1127,11 +1417,18 @@ export class Text extends Image {
     return this.scale.x * this.texture.frame.width;
   }
 
+  /**
+   * TBD.
+   */
   set width(value) {
     this.scale.x = value / this.texture.frame.width;
     this._width = value;
   }
 
+  /**
+   * TBD.
+   * @returns {number} TBD.
+   */
   get height() {
     if (this.dirty) {
       this.updateText();
@@ -1140,6 +1437,9 @@ export class Text extends Image {
     return this.scale.y * this.texture.frame.height;
   }
 
+  /**
+   * TBD.
+   */
   set height(value) {
     this.scale.y = value / this.texture.frame.height;
     this._height = value;