Added jsdocs and updated change log

Author: photonstorm

CHANGELOG.md

@@ -80,6 +80,20 @@ There is a new Game Object Component called `TextureCrop`. It replaces the Textu
 * You can toggle the crop on a Game Object by changing the `isCropped` boolean at any point.
 * The crop is automatically re-applied when the texture or frame of a Game Object is changed. If you wish to disable this, turn off the crop before changing the frame.
 
+### BitmapText New Features, Updates and Bug Fixes
+
+* Multi-line BitmapText objects can now be aligned. The constructor has a new argument `align` which can accept either left-aligned (the default), center aligned, or right-aligned. Alignment works by calculating the longest line of text in the object and then offsetting the other lines to match it.
+* `BitmapText.setCenterAlign` is a new chainable method to center-align the text.
+* `BitmapText.setLeftAlign` is a new chainable method to left-align the text.
+* `BitmapText.setRightAlign` is a new chainable method to right-align the text.
+* `BitmapText.align` is a new property that holds the alignment of the text.
+* `BitmapText.setFont` is a new method that allows you to change the font it is rendering with.
+* Internally all of the BitmapText properties have been renamed with an underscore (i.e. `letterSpacing` is now `_letterSpacing`), so as to not change the API, getters and setters for them all have been added.
+* Internally there is a new `dirty` flag that tracks if any part of the BitmapText has changed. This is used when getting the BitmapText's bounds object, as used in the renderer for line alignment, and in properties like `width` and `height`. The dirty flag ensures the bounds are only recalculated if something has changed, cutting down on un-necessary calculations.
+* `GetBitmapTextSize`, which is used internally in the BitmapText Game Objects, will now produce different bounds from the previous version. Previously, the bounds were tight against the letters in the text. However, this meant the bounds were not properly aligned with the origin of the BitmapText, and consequently you'd get different bounds if the text consisted of different characters. The bounds are now calculated purely based on the glyph data and letter spacing values. This will give a far more consistent overall experience, but it does mean if you were using the bounds to position text previously, you'll need to revisit that code again. See issue #3799 for more details (and to discuss this further if you wish) (thanks @SBCGames)
+* `GetBitmapTextSize` and its exposed method `BitmapText.getTextBounds` now factor in the display origin of the BitmapText into the `global` position returned.
+* The `BitmapText` WebGL Renderer incorrectly calculated the font scale at very small sizes, causing characters to overlap when they shouldn't. Scale is now applied to the correct component parts in the render code.
+
 ### New Features
 
 * `Graphics.fillRoundedRect` will draw a stroked rounded rectangle to a Graphics object. The radius of the corners can be either a number, or an object, allowing you to specify different radius per corner (thanks @TadejZupancic)
@@ -101,7 +115,7 @@ There is a new Game Object Component called `TextureCrop`. It replaces the Textu
 * The docs for the Loader `filecomplete` event said that you could listen for a specific file using its type and key, i.e.: `filecomplete-image-monster`, however, the code used an underscore instead of a hyphen. We feel the hyphen looks cleaner, so the Loader code has been updated, meaning you can now use the hyphen version of the event properly (thanks @NokFrt)
 * If a Game Object is already being dragged, it cannot be dragged by another pointer (in multi-touch mode) until the original pointer has released it (thanks @rexrainbow)
 * Calling `Tween.play` on a tween created via `TweenManager.create` wouldn't actually start playback until the tween was first added to the Tween Manager. Now, calling `play` will have it automatically add itself to the Tween Manager if it's not already in there. Fix #3763 (thanks @pantoninho)
-* If the Blitter object has no Bob's to render it will now abort immediately, avoiding several context calls in Canvas mode.
+* If the Blitter object has no Bobs to render it will now abort immediately, avoiding several context calls in Canvas mode.
 * `Scene.run` will now pass the optional `data` object in all cases, no matter if it's waking, resuming or starting a Scene (thanks @rook2pawn)
 * `ScenePlugin.start` and `ScenePlugin.restart` will now always queue the op with the Scene Manager, regardless of the state of the Scene, in order to avoid issues where plugins carry on running for a frame before closing down. Fix #3776 (thanks @jjalonso)
 * `Tileset.glTexture` is a new property that maps to the WebGL Texture for the Tileset image. It's used internally by the renderer to avoid expensive object look-ups and is set automatically in the `Tileset.setImage` method.
@@ -111,8 +125,6 @@ There is a new Game Object Component called `TextureCrop`. It replaces the Textu
 * The TextureManager Sprite Sheet Parser will now throw a concise console warning if you specify invalid frame sizes that would result in no frames being generated (thanks @andygroff)
 * The `Quad` Game Object now has a new `setFrame` method that allows you to change the frame being rendered by the Quad, including using frames that are part of a texture atlas. Fix #3161 (thanks @halgorithm)
 * The `ScenePlugin` will now queue all of the following ops with the Scene Manager: `start`, `run`, `pause`, `resume`, `sleep`, `wake`, `switch` and `stop`. This means for all of these calls the Scene Manager will add the call into its queue and process it at the start of the next frame. This fixes #3812 and keeps things more predictable (thanks @Waclaw-I)
-* `GetBitmapTextSize`, which is used internally in the BitmapText Game Objects, will now produce different bounds from the previous version. Previously, the bounds were tight against the letters in the text. However, this meant the bounds were not properly aligned with the origin of the BitmapText, and consequently you'd get different bounds if the text consisted of different characters. The bounds are now calculated purely based on the glyph data and letter spacing values. This will give a far more consistent overall experience, but it does mean if you were using the bounds to position text previously, you'll need to revisit that code again. See issue #3799 for more details (and to discuss this further if you wish) (thanks @SBCGames)
-* `GetBitmapTextSize` and its exposed method `BitmapText.getTextBounds` now factor in the display origin of the BitmapText into the `global` position returned.
 
 ### Bug Fixes
 
@@ -136,7 +148,6 @@ There is a new Game Object Component called `TextureCrop`. It replaces the Textu
 * `clearMask(true)` would throw an exception if the Game Object didn't have a mask. Now it checks first before destroying the mask. Fix #3809 (thanks @NokFrt)
 * In the WebGL `GeometryMask` the stencil has been changed from `INVERT` to `KEEP` in order to fix issues when masking Graphics objects and other complex objects. Fix #3807. This also fixes the issue where children in Containers would display incorrectly outside of a Geometry mask. Fix #3746 (thanks @zilbuz @oklar)
 * `BitmapMask.destroy` will now remove the textures and framebuffers that it created from the WebGL Renderer as part of the destroy process. Fix #3771 (thanks @nunof07)
-* The `BitmapText` WebGL Renderer incorrectly calculated the font scale at very small sizes, causing characters to overlap when they shouldn't. Scale is now applied to the correct component parts in the render code.
 
 ### Examples, Documentation and TypeScript
 

src/gameobjects/bitmaptext/static/BitmapText.js

@@ -313,9 +313,9 @@ var BitmapText = new Class({
     },
 
     /**
-     * Set the content of this BitmapText.
+     * Set the textual content of this BitmapText.
      *
-     * An array of strings will be converted multi-line text.
+     * An array of strings will be converted into multi-line text. Use the align methods to change multi-line alignment.
      *
      * @method Phaser.GameObjects.BitmapText#setText
      * @since 3.0.0
@@ -357,6 +357,8 @@ var BitmapText = new Class({
      * Local size is based on just the font size and a [0, 0] position.
      *
      * Global size takes into account the Game Object's scale, world position and display origin.
+     * 
+     * Also in the object is data each the length of each line, should this be a multi-line BitmapText.
      *
      * @method Phaser.GameObjects.BitmapText#getTextBounds
      * @since 3.0.0
@@ -380,7 +382,10 @@ var BitmapText = new Class({
     },
 
     /**
-     * TODO
+     * Changes the font this BitmapText is using to render.
+     * 
+     * The new texture is loaded and applied to the BitmapText. The existing test, size and alignment are preserved,
+     * unless overridden via the arguments.
      *
      * @method Phaser.GameObjects.BitmapText#setFont
      * @since 3.11.0
@@ -407,6 +412,8 @@ var BitmapText = new Class({
                 this._fontSize = size;
                 this._align = align;
 
+                this.setTexture(entry.texture, entry.frame);
+
                 GetBitmapTextSize(this, false, this._bounds);
             }
         }