//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------
/**
* Creates a new BitmapField.
*
* @constructor
* @extends rune.display.DisplayObject
*
* @param {string} [text=""] A string that is the current text in the text field.
* @param {string} [resource] Name of the texture to be used for characters.
*
* @class
* @classdesc
*
* The BitmapField class represents a bitmap-based text field. Each character
* in the text field is retrieved from a bitmap-based texture file that is
* passed as an optional parameter to the constructor. If no texture file is
* specified, {@link rune.text.BitmapFormat.FONT_SMALL} is used. Each field has
* its own Texture wrapper so colors can be replaced without changing other
* fields that use the same font resource.
*/
rune.text.BitmapField = function(text, resource) {
//--------------------------------------------------------------------------
// Private properties
//--------------------------------------------------------------------------
/**
* Controls automatic sizing and alignment of text fields.
*
* @type {boolean}
* @private
*/
this.m_autoSize = false;
/**
* Horizontal alignment of each row within the local pixel buffer.
*
* @type {string}
* @private
*/
this.m_align = rune.text.BitmapField.ALIGN_LEFT;
/**
* Represent a font.
*
* @type {rune.text.BitmapFormat}
* @private
*/
this.m_format = new rune.text.BitmapFormat(resource);
/**
* The field's font texture. Source pixels remain shared until modified.
*
* @type {rune.display.Texture}
* @private
*/
this.m_texture = new rune.display.Texture(this, this.m_format['texture']);
/**
* A number representing the amount of space that is uniformly distributed
* between all characters.
*
* @type {number}
* @private
*/
this.m_letterSpacing = 0;
/**
* An integer representing the amount of vertical space (called leading)
* between lines.
*
* @type {number}
* @private
*/
this.m_leading = 0;
/**
* A string that is the current text in the text field.
*
* @type {string}
* @private
*/
this.m_text = this.m_formatText(text);
/**
* Whether text wraps within the local buffer width.
* @type {boolean}
* @private
*/
this.m_wordWrap = false;
/**
* Cached visual rows shared by measurement and rendering.
* @type {Array.<string>}
* @private
*/
this.m_rows = null;
/**
* Text used to build the cached visual rows.
* @type {?string}
* @private
*/
this.m_layoutText = null;
/**
* Buffer width used to build the cached visual rows.
* @type {number}
* @private
*/
this.m_layoutWidth = -1;
/**
* Character spacing used to build the cached visual rows.
* @type {number}
* @private
*/
this.m_layoutSpacing = 0;
/**
* Lazily created typewriter, owned and updated by this field.
*
* @type {rune.text.Typewriter}
* @private
*/
this.m_writer = null;
/**
* Exclusive source-text position up to which characters are rendered.
*
* @type {number}
* @private
*/
this.m_maxVisibleCharacters = Infinity;
/**
* Source-text start position for each cached visual row.
*
* @type {Array.<number>}
* @private
*/
this.m_rowStarts = [];
/**
* Optional scramble effect, created on first access.
* @type {rune.text.TextScramble}
* @private
*/
this.m_scramble = null;
/**
* Optional numeric text animation, created on first access.
* @type {rune.text.TextCounter}
* @private
*/
this.m_counter = null;
//--------------------------------------------------------------------------
// Super call
//--------------------------------------------------------------------------
/**
* Extend DisplayObject.
*/
rune.display.DisplayObject.call(this, 0, 0, 140, 10);
};
//------------------------------------------------------------------------------
// Inheritance
//------------------------------------------------------------------------------
rune.text.BitmapField.prototype = Object.create(rune.display.DisplayObject.prototype);
rune.text.BitmapField.prototype.constructor = rune.text.BitmapField;
//------------------------------------------------------------------------------
// Public static constants
//------------------------------------------------------------------------------
/**
* Aligns text to the left edge of the field.
* @const {string}
*/
rune.text.BitmapField.ALIGN_LEFT = "left";
/**
* Centers each row horizontally within the field.
* @const {string}
*/
rune.text.BitmapField.ALIGN_CENTER = "center";
/**
* Aligns text to the right edge of the field.
* @const {string}
*/
rune.text.BitmapField.ALIGN_RIGHT = "right";
//------------------------------------------------------------------------------
// Public prototype getter and setter methods
//------------------------------------------------------------------------------
/**
* Horizontal text alignment: ALIGN_LEFT (default), ALIGN_CENTER or ALIGN_RIGHT.
* Each row is aligned within the unscaled buffer width. Overflow is clipped.
* With autoSize enabled and wrapping disabled, shorter rows align within the
* longest row's width. Wrapped rows use the configured buffer width.
* Unsupported values are ignored.
*
* @member {string} align
* @memberof rune.text.BitmapField
* @instance
*/
Object.defineProperty(rune.text.BitmapField.prototype, "align", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_align;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
if (value !== rune.text.BitmapField.ALIGN_LEFT &&
value !== rune.text.BitmapField.ALIGN_CENTER &&
value !== rune.text.BitmapField.ALIGN_RIGHT) return;
if (this.m_align !== value) {
this.m_align = value;
this.breakCache();
}
}
});
/**
* Controls automatic sizing and alignment of text fields. If this property is
* set to false, a default width of 140 pixels and a default height of 10
* pixels are used initially. With wordWrap enabled, automatic sizing adjusts
* only height and preserves the configured width.
*
* @member {boolean} autoSize
* @memberof rune.text.BitmapField
* @instance
*/
Object.defineProperty(rune.text.BitmapField.prototype, "autoSize", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_autoSize;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
if (this.m_autoSize != value) {
this.m_autoSize = value;
if (this.m_autoSize == true) {
this.m_refit();
}
this.breakCache();
}
}
});
/**
* Represents the current font of the text field.
*
* @member {rune.text.BitmapFormat} format
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "format", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_format;
}
});
/**
* Which character spacing to use when rendering text fields.
*
* @member {number} letterSpacing
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "letterSpacing", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_letterSpacing;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
value = ~~value;
if (this.m_letterSpacing != value) {
this.m_letterSpacing = value;
if (this.m_autoSize == true) {
this.m_refit();
}
this.breakCache();
}
}
});
/**
* Maximum number of source-text characters to reveal. Defaults to Infinity.
* Newlines and spaces omitted by wrapping still count. Layout and measurements
* always use the full text. Values are rounded down and clamped to zero.
*
* @member {number} maxVisibleCharacters
* @memberof rune.text.BitmapField
* @instance
*/
Object.defineProperty(rune.text.BitmapField.prototype, "maxVisibleCharacters", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_maxVisibleCharacters;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
if (typeof value !== "number" || isNaN(value)) return;
value = Math.max(0, Math.floor(value));
if (this.m_maxVisibleCharacters !== value) {
this.m_maxVisibleCharacters = value;
this.breakCache();
}
}
});
/**
* Which line spacing to use when rendering text fields.
*
* @member {number} leading
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "leading", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_leading;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
value = ~~value;
if (this.m_leading != value) {
this.m_leading = value;
if (this.m_autoSize == true) {
this.m_refit();
}
this.breakCache();
}
}
});
/**
* Current text in the text field.
*
* @member {string} text
* @memberof rune.text.BitmapField
* @instance
*/
Object.defineProperty(rune.text.BitmapField.prototype, "text", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_text;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
this.setTextFromEffect(value, null);
}
});
/**
* The height of the text field based on current content.
*
* @member {number} textHeight
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "textHeight", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
var numRows = this.m_getRows().length;
return (numRows * this.m_format['charHeight']) + ((numRows - 1) * this.m_leading);
}
});
/**
* The width of the text field based on current content.
*
* @member {number} textWidth
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "textWidth", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
var numChars = 0;
var rows = this.m_getRows();
for (var ln = 0; ln < rows.length; ln++) {
numChars = Math.max(rows[ln].length, numChars);
}
return this.m_getRowWidth(numChars);
}
});
/**
* The font texture used to render this field. Calling replaceColor() creates
* unique pixel data for this field and invalidates its render cache. Other
* fields and the original font resource remain unchanged.
*
* @member {rune.display.Texture} texture
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "texture", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_texture;
}
});
/**
* Whether text wraps at spaces within the local buffer width. Defaults to false.
* Oversized words split between characters. Spaces at automatic breaks are
* omitted; explicit newlines and empty rows are preserved. The text is unchanged.
* With autoSize enabled, only height is fitted. Even a zero-width field advances
* by at least one character per row. Non-positive character advances disable
* automatic wrapping to preserve overlapping text layouts.
*
* @member {boolean} wordWrap
* @memberof rune.text.BitmapField
* @instance
*/
Object.defineProperty(rune.text.BitmapField.prototype, "wordWrap", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
return this.m_wordWrap;
},
/**
* @this rune.text.BitmapField
* @ignore
* @suppress {accessControls}
*/
set : function(value) {
value = Boolean(value);
if (this.m_wordWrap !== value) {
this.m_wordWrap = value;
this.m_rows = null;
if (this.m_autoSize) this.m_refit();
this.breakCache();
}
}
});
/**
* Typewriter subsystem, created on first access. Updated and disposed by this
* field. No manual update is required while the field is in the display list.
*
* @member {rune.text.Typewriter} writer
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "writer", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
if (this.m_writer == null) this.m_writer = new rune.text.Typewriter(this);
return this.m_writer;
}
});
/**
* Optional scramble subsystem. Created on first access, then updated and disposed
* automatically by this field.
*
* @member {rune.text.TextScramble} scramble
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "scramble", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
if (this.m_scramble == null) this.m_scramble = new rune.text.TextScramble(this);
return this.m_scramble;
}
});
/**
* Optional counter subsystem. Created on first access, then updated and disposed
* automatically by this field.
*
* @member {rune.text.TextCounter} counter
* @memberof rune.text.BitmapField
* @instance
* @readonly
*/
Object.defineProperty(rune.text.BitmapField.prototype, "counter", {
/**
* @this rune.text.BitmapField
* @ignore
*/
get : function() {
if (this.m_counter == null) this.m_counter = new rune.text.TextCounter(this);
return this.m_counter;
}
});
//------------------------------------------------------------------------------
// Override public prototype methods (ENGINE)
//------------------------------------------------------------------------------
/**
* @inheritDoc
* @suppress {accessControls}
*/
rune.text.BitmapField.prototype.update = function(step) {
rune.display.DisplayObject.prototype.update.call(this, step);
if (this.m_writer != null) this.m_writer.update(step);
if (this.m_scramble != null) this.m_scramble.update(step);
if (this.m_counter != null) this.m_counter.update(step);
};
/**
* @inheritDoc
* @suppress {accessControls}
*/
rune.text.BitmapField.prototype.render = function() {
if (this.m_cached == false) {
var version = this.m_cacheVersion;
this.m_renderBackgroundColor();
this.m_renderText();
this.m_renderStates();
this.restoreCache(version);
}
};
/**
* @inheritDoc
*/
rune.text.BitmapField.prototype.dispose = function() {
this.m_disposeWriter();
this.m_disposeScramble();
this.m_disposeCounter();
this.m_disposeTexture();
this.m_disposeFormat();
rune.display.DisplayObject.prototype.dispose.call(this);
};
//------------------------------------------------------------------------------
// Override internal prototype methods
//------------------------------------------------------------------------------
/**
* Stops text animations before another subsystem takes control of this field.
* Does not allocate unused subsystems.
*
* @return {undefined}
* @package
* @ignore
*/
rune.text.BitmapField.prototype.stopTextEffects = function() {
if (this.m_writer != null) this.m_writer.stop();
if (this.m_scramble != null) this.m_scramble.stop();
if (this.m_counter != null) this.m_counter.stop();
};
/**
* Assigns normalized text without cancelling the effect that produced it.
* A direct text assignment passes null and stops all effects when text changes.
*
* @param {*} value The new text.
* @param {Object} effect The owning effect, or null for a direct assignment.
* @return {undefined}
* @package
* @ignore
*/
rune.text.BitmapField.prototype.setTextFromEffect = function(value, effect) {
value = this.m_formatText(value);
if (this.m_text != value) {
if (this.m_writer != null && this.m_writer !== effect) this.m_writer.stop();
if (this.m_scramble != null && this.m_scramble !== effect) this.m_scramble.stop();
if (this.m_counter != null && this.m_counter !== effect) this.m_counter.stop();
this.m_maxVisibleCharacters = Infinity;
this.m_text = value;
if (this.m_autoSize) this.m_refit();
this.breakCache();
}
};
/**
* Invalidates rendering and refits wrapped height after a buffer width change.
* Width setters already invoke this method, including inherited width setters.
*
* @return {undefined}
* @package
* @ignore
* @suppress {accessControls}
*/
rune.text.BitmapField.prototype.breakCache = function() {
rune.display.DisplayObject.prototype.breakCache.call(this);
if (this.m_wordWrap && this.m_autoSize && this.m_canvas != null &&
this.m_layoutWidth !== this.m_canvas['width']) {
this.m_refit();
}
};
//------------------------------------------------------------------------------
// Private prototype methods
//------------------------------------------------------------------------------
/**
* Returns visual rows, rebuilding only when text, width or character spacing
* changes. Rows are shared by measurement and rendering, independently of scale.
*
* @return {Array.<string>} The cached visual rows.
* @private
*/
rune.text.BitmapField.prototype.m_getRows = function() {
var width = this.m_wordWrap ? this.m_canvas['width'] : -1;
if (this.m_rows != null && this.m_layoutText === this.m_text &&
this.m_layoutWidth === width && this.m_layoutSpacing === this.m_letterSpacing) {
return this.m_rows;
}
this.m_layoutText = this.m_text;
this.m_layoutWidth = width;
this.m_layoutSpacing = this.m_letterSpacing;
this.m_rows = [];
this.m_rowStarts.length = 0;
var source = 0;
var lines = this.m_text.split("\n");
var advance = this.m_format['charWidth'] + this.m_letterSpacing;
var limit = Math.max(1, Math.floor((width + this.m_letterSpacing) / advance));
for (var i = 0; i < lines.length; i++) {
var line = lines[i];
var start = source;
source += line.length + 1;
if (this.m_wordWrap && advance > 0) {
while (line.length > limit) {
var length = line.length;
this.m_rowStarts.push(start);
var split = line.lastIndexOf(" ", limit);
if (split > 0) {
this.m_rows.push(line.substring(0, split).replace(/ +$/, ""));
line = line.substring(split).replace(/^ +/, "");
} else {
this.m_rows.push(line.substring(0, limit));
line = line.substring(limit).replace(/^ +/, "");
}
start += length - line.length;
if (line.length === 0) break;
}
}
if (line.length > 0 || lines[i].length === 0) {
this.m_rows.push(line);
this.m_rowStarts.push(start);
}
}
return this.m_rows;
};
/**
* Renders a text field.
*
* @returns {undefined}
* @private
* @suppress {accessControls}
*/
rune.text.BitmapField.prototype.m_renderText = function() {
var text = "";
var rows = this.m_getRows();
for (var ln = 0; ln < rows.length; ln++) {
text = rows[ln];
var x = 0;
if (this.m_align === rune.text.BitmapField.ALIGN_CENTER) {
x = Math.floor((this.m_canvas['width'] - this.m_getRowWidth(text.length)) / 2);
} else if (this.m_align === rune.text.BitmapField.ALIGN_RIGHT) {
x = this.m_canvas['width'] - this.m_getRowWidth(text.length);
}
var y = (this.m_format['charHeight'] * ln) + (this.m_leading * ln);
for (var col = 0; col < text.length; col++) {
if (this.m_rowStarts[ln] + col >= this.m_maxVisibleCharacters) return;
var code = text.charCodeAt(col);
if (this.m_scramble != null) code = this.m_scramble.getCharCode(this.m_rowStarts[ln] + col, code);
this.m_renderCharacter(
code,
x,
y
);
x += this.m_format['charWidth'] + this.m_letterSpacing;
}
}
};
/**
* Measures a row in local pixels, excluding spacing after its final character.
* Empty rows have zero width.
*
* @param {number} numChars The number of characters in the row.
* @return {number} The row width in pixels.
* @private
*/
rune.text.BitmapField.prototype.m_getRowWidth = function(numChars) {
if (numChars > 0) {
return numChars * this.m_format['charWidth'] + (numChars - 1) * this.m_letterSpacing;
}
return 0;
};
/**
* Formats a value as text and normalizes Windows and legacy carriage-return
* line endings to newline characters for consistent layout and rendering.
*
* @param {*} value Value to format.
*
* @return {string}
* @private
*/
rune.text.BitmapField.prototype.m_formatText = function(value) {
if (value == null) return "";
else return value.toString().replace(/\r\n?/g, "\n");
};
/**
* Renders a character.
*
* @param {number} charCode Unicode character code.
* @param {number} x Position in the x-direction.
* @param {number} y Position in the y-direction.
*
* @return {undefined}
* @private
*/
rune.text.BitmapField.prototype.m_renderCharacter = function(charCode, x, y) {
var rect = this.m_format.getCharRect(charCode);
if (rect instanceof rune.geom.Rectangle) {
this.m_canvas.drawImage(
this.m_texture['data'],
x,
y,
rect.width,
rect.height,
rect.x,
rect.y,
rect.width,
rect.height
);
}
};
/**
* Stops and disposes the optional typewriter subsystem.
*
* @return {undefined}
* @private
*/
rune.text.BitmapField.prototype.m_disposeWriter = function() {
if (this.m_writer != null) {
this.m_writer.dispose();
this.m_writer = null;
}
};
/**
* Disposes the optional scramble subsystem.
* @return {undefined}
* @private
*/
rune.text.BitmapField.prototype.m_disposeScramble = function() {
if (this.m_scramble != null) {
this.m_scramble.dispose();
this.m_scramble = null;
}
};
/**
* Disposes the optional counter subsystem.
* @return {undefined}
* @private
*/
rune.text.BitmapField.prototype.m_disposeCounter = function() {
if (this.m_counter != null) {
this.m_counter.dispose();
this.m_counter = null;
}
};
/**
* Disposes the field's texture wrapper and any unique pixel buffer.
* The shared font resource is retained by the resource collection.
*
* @return {undefined}
* @private
* @suppress {accessControls}
*/
rune.text.BitmapField.prototype.m_disposeTexture = function() {
if (this.m_texture != null) {
this.m_texture.dispose();
this.m_texture = null;
}
};
/**
* Dispose format.
*
* @return {undefined}
* @protected
* @ignore
*/
rune.text.BitmapField.prototype.m_disposeFormat = function() {
if (this.m_format instanceof rune.text.BitmapFormat) {
this.m_format.dispose();
this.m_format = null;
}
};
/**
* Fits the local pixel buffer and hitbox to the text independently of the
* display object's scale. Wrapped fields retain their configured width.
*
* @return {undefined}
* @protected
* @ignore
*/
rune.text.BitmapField.prototype.m_refit = function() {
var width = this['textWidth'];
var height = this['textHeight'];
if (this.m_wordWrap) width = this['unscaledWidth'];
else this['unscaledWidth'] = width;
this['unscaledHeight'] = height;
this['hitbox'].set(
0,
0,
width,
height
);
};