Source: text/Typewriter.js

//------------------------------------------------------------------------------
// Constructor scope
//------------------------------------------------------------------------------

/**
 * Creates a typewriter for a bitmap text field.
 *
 * @constructor
 * @param {rune.text.BitmapField} field The target field, retained but not owned.
 * @class
 * @classdesc
 * Reveals text over time without changing its full layout. BitmapField creates,
 * updates and disposes its writer automatically. Character positions use UTF-16
 * code units, matching BitmapField; spaces and newlines consume time as well.
 */
rune.text.Typewriter = function(field) {
    //--------------------------------------------------------------------------
    // Private properties
    //--------------------------------------------------------------------------

    /**
     * Target text field.
     * @type {rune.text.BitmapField}
     * @private
     */
    this.m_field = field;

    /**
     * Whether text is currently being revealed.
     * @type {boolean}
     * @private
     */
    this.m_running = false;

    /**
     * Milliseconds between characters.
     * @type {number}
     * @private
     */
    this.m_interval = 40;

    /**
     * Accumulated time not yet consumed by a character.
     * @type {number}
     * @private
     */
    this.m_elapsed = 0;

    /**
     * Number of source characters revealed in the current run.
     * @type {number}
     * @private
     */
    this.m_index = 0;

    /**
     * Run identifier guarding against callback-driven restarts or cancellation.
     * @type {number}
     * @private
     */
    this.m_generation = 0;

    /**
     * Optional per-character callback.
     * @type {rune.util.Executable}
     * @private
     */
    this.m_onCharacter = null;

    /**
     * Optional completion callback.
     * @type {rune.util.Executable}
     * @private
     */
    this.m_onComplete = null;
};

//------------------------------------------------------------------------------
// Public getter and setter methods
//------------------------------------------------------------------------------

/**
 * Whether the writer is revealing text.
 * @member {boolean} running
 * @memberof rune.text.Typewriter
 * @instance
 * @readonly
 */
Object.defineProperty(rune.text.Typewriter.prototype, "running", {
    /**
     * @this rune.text.Typewriter
     * @ignore
     */
    get : function() {
        return this.m_running;
    }
});

//------------------------------------------------------------------------------
// Public prototype methods (API)
//------------------------------------------------------------------------------

/**
 * Replaces the field text and starts revealing it after the first interval.
 * Empty text completes immediately. Callback registrations survive restarts.
 *
 * @param {string} text The full text to display.
 * @param {number} [interval=40] Positive milliseconds per character.
 * @return {undefined}
 * @suppress {accessControls}
 */
rune.text.Typewriter.prototype.start = function(text, interval) {
    if (this.m_field == null) return;
    this.stop();
    this.m_field.stopTextEffects();
    this.m_field['text'] = text;
    this.m_interval = (typeof interval === "number" && isFinite(interval) && interval > 0) ? interval : 40;
    this.m_index = 0;
    this.m_elapsed = 0;
    this.m_field['maxVisibleCharacters'] = 0;
    this.m_running = true;
    if (this.m_field['text'].length === 0) this.complete();
};

/**
 * Reveals all remaining text and invokes onComplete once if currently running.
 * Skipped characters do not trigger onCharacter callbacks.
 *
 * @return {undefined}
 */
rune.text.Typewriter.prototype.complete = function() {
    if (this.m_field == null) return;
    var running = this.m_running;
    this.stop();
    this.m_index = this.m_field['text'].length;
    this.m_field['maxVisibleCharacters'] = Infinity;
    if (running && this.m_onComplete != null) this.m_onComplete.execute(this.m_field);
};

/**
 * Stops revealing text, preserving the current visible characters. Does not
 * invoke onComplete. Assigning different field text stops and reveals it fully.
 *
 * @return {undefined}
 */
rune.text.Typewriter.prototype.stop = function() {
    this.m_generation++;
    this.m_running = false;
    this.m_elapsed = 0;
};

/**
 * Registers or clears the per-character callback. Receives the character,
 * its zero-based source index and the field, including spaces and newlines.
 *
 * @param {Function} func Callback, or null to remove it.
 * @param {Object} [scope] Callback execution scope.
 * @return {undefined}
 */
rune.text.Typewriter.prototype.onCharacter = function(func, scope) {
    if (this.m_onCharacter != null) this.m_onCharacter.dispose();
    this.m_onCharacter = func ? new rune.util.Executable(func, scope) : null;
};

/**
 * Registers or clears the completion callback. Receives the target field.
 *
 * @param {Function} func Callback, or null to remove it.
 * @param {Object} [scope] Callback execution scope.
 * @return {undefined}
 */
rune.text.Typewriter.prototype.onComplete = function(func, scope) {
    if (this.m_onComplete != null) this.m_onComplete.dispose();
    this.m_onComplete = func ? new rune.util.Executable(func, scope) : null;
};

/**
 * Stops the writer and releases callbacks and its field reference. The field is
 * not disposed, and its current visible text is retained.
 *
 * @return {undefined}
 */
rune.text.Typewriter.prototype.dispose = function() {
    this.stop();
    if (this.m_onCharacter != null) this.m_onCharacter.dispose();
    if (this.m_onComplete != null) this.m_onComplete.dispose();
    this.m_onCharacter = null;
    this.m_onComplete = null;
    this.m_field = null;
};

//------------------------------------------------------------------------------
// Internal prototype methods
//------------------------------------------------------------------------------

/**
 * Advances the writer, retaining fractional time and catching up after slow
 * frames. A callback may stop, restart, complete or dispose the writer safely.
 *
 * @param {number} step Elapsed milliseconds.
 * @return {undefined}
 * @package
 * @ignore
 */
rune.text.Typewriter.prototype.update = function(step) {
    if (!this.m_running || typeof step !== "number" || !isFinite(step) || step <= 0) return;
    this.m_elapsed += step;
    var generation = this.m_generation;
    while (this.m_running && this.m_elapsed >= this.m_interval) {
        this.m_elapsed -= this.m_interval;
        var index = this.m_index++;
        this.m_field['maxVisibleCharacters'] = this.m_index;
        if (this.m_onCharacter != null) {
            this.m_onCharacter.execute(this.m_field['text'].charAt(index), index, this.m_field);
        }
        if (generation !== this.m_generation) return;
        if (this.m_index >= this.m_field['text'].length) this.complete();
    }
};