Source: timer/Timers.js

//------------------------------------------------------------------------------
// CONSTRUCTOR SCOPE
//------------------------------------------------------------------------------

/** 
 * Creates a new instance of the Timers class.
 * 
 * @constructor
 *
 * @param {Object} [scope] Scope within which the Timer object's callback functions are executed.
 * 
 * @class
 * @classdesc
 * 
 * The Timers class represents a handler for Timer objects. All handling of 
 * Timer objects must be done via an instance of this class.
 */
rune.timer.Timers = function(scope) {

    //--------------------------------------------------------------------------
    // PUBLIC PROPERTIES
    //--------------------------------------------------------------------------

    /**
     * Pauses all Timer objects that are registered with the Timers instance.
     *
     * @type {boolean}
     * @default false
     */
    this.paused = false;

    //--------------------------------------------------------------------------
    // PRIVATE PROPERTIES
    //--------------------------------------------------------------------------

    /**
     * List containing all Timer objects registered with the manager.
     *
     * @type {Array.<rune.timer.Timer>}
     * @private
     */
    this.m_timers = [];

    /**
     * Scope within which the Timer object's callback functions are executed.
     *
     * @type {Object}
     * @private
     */
    this.m_scope = scope || window;
};

//------------------------------------------------------------------------------
// PUBLIC GETTER AND SETTER METHODS
//------------------------------------------------------------------------------

/**
 * The number of Timer objects that are currently registered with the Timer 
 * instance. Returns zero after disposal.
 *
 * @member {number} length
 * @memberof rune.timer.Timers
 * @instance
 * @readonly
 */
Object.defineProperty(rune.timer.Timers.prototype, "length", {
    /**
     * @this rune.timer.Timers
     * @ignore
     */
    get : function() {
        return this.m_timers != null ? this.m_timers.length : 0;
    }
});

/**
 * The number of registered Timer objects that are currently active. Stopped 
 * Timer objects are inactive, but paused are still considered active.
 * Returns zero after disposal.
 *
 * @member {number} numActive
 * @memberof rune.timer.Timers
 * @instance
 * @readonly
 */
Object.defineProperty(rune.timer.Timers.prototype, "numActive", {
    /**
     * @this rune.timer.Timers
     * @ignore
     */
    get : function() {
        var n = 0;
        var i = this.length;
        while (i--) {
            if (this.m_timers[i]['active'] == true) {
                n++;
            }
        }
        
        return n;
    }
});

//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE METHODS (API)
//------------------------------------------------------------------------------

/**
 * Adds the specified Timer object to the handler. Note that new Timer objects 
 * should be created using the create method.
 *
 * @param {rune.timer.Timer} timer Timer object to add.
 * @param {boolean} [autoStart=true] If the Timer object is to be started automatically.
 *
 * @returns {rune.timer.Timer}
 */
rune.timer.Timers.prototype.add = function(timer, autoStart) {
    var i = this.m_timers.indexOf(timer);
    if (i === -1) {
        this.m_timers.push(timer);
        if (autoStart !== false) timer.start();
    }
    
    return timer;
};

/**
 * Removes, and deallocates all registered Timer objects. Does nothing after disposal.
 *
 * @returns {undefined}
 */
rune.timer.Timers.prototype.clear = function() {
    while (this.m_timers != null && this.m_timers.length > 0) {
        this.remove(this.m_timers[0]);
    }
};

/**
 * Creates and registers a new Timer object according to the specified 
 * options object. The supplied options are not modified.
 *
 * @param {Object} options Timer options.
 * @param {boolean} [autoStart=true] If the Timer object is to be started automatically.
 *
 * @returns {rune.timer.Timer} The new Timer object.
 */
rune.timer.Timers.prototype.create = function(options, autoStart) {
    var settings = new rune.timer.TimerOptions(options);
    settings.scope = settings.scope || this.m_scope;

    var timer = new rune.timer.Timer(settings);

    return this.add(timer, autoStart);
};

/**
 * Creates and starts a timer that invokes the callback once on completion.
 * Uses the same duration handling as create(). The callback receives the timer
 * and runs in the manager's scope unless another scope is supplied.
 *
 * @param {number} delay Delay in milliseconds.
 * @param {Function} callback Function to invoke when the timer completes.
 * @param {Object} [scope] Callback scope; defaults to the manager's scope.
 *
 * @returns {rune.timer.Timer} The new timer, which can be paused or removed.
 */
rune.timer.Timers.prototype.once = function(delay, callback, scope) {
    return this.create({
        duration: delay,
        repeat: 0,
        onComplete: callback,
        scope: scope
    });
};

/**
 * Removes the specified Timer object from the handler and activates the 
 * deallocation process for that object. The timer is removed before disposal,
 * allowing its onAbort callback to safely modify the handler's timer list.
 *
 * @param {rune.timer.Timer} timer Timer to remove.
 *
 * @returns {boolean}
 */
rune.timer.Timers.prototype.remove = function(timer) {
    if (this.m_timers == null) {
        return false;
    }

    var i = this.m_timers.indexOf(timer);
    if (i > -1) {
        this.m_timers.splice(i, 1);
        timer.dispose();
        
        return true;
    }
    
    return false;
};

/**
 * Deletes Timer objects that have been completed and restarts Timer objects 
 * that have not yet been completed.
 *
 * @returns {undefined}
 */
rune.timer.Timers.prototype.reset = function() {
    if (this.m_timers == null) {
        return;
    }

    for (var i = 0; i < this.m_timers.length; i++) {
        if (this.m_timers[i].disposed) {
            this.m_timers.splice(i, 1);
            i--;
        }
        else this.m_timers[i].restart();
    }
};

//------------------------------------------------------------------------------
// PUBLIC PROTOTYPE METHODS (ENGINE)
//------------------------------------------------------------------------------

/**
 * Deletes all Timer objects.
 *
 * @returns {undefined}
 * @ignore
 */
rune.timer.Timers.prototype.dispose = function() {
    this.m_disposeTimers();
};

/**
 * Updates all Timer objects.
 *
 * @param {number} step Current time step.
 *
 * @returns {undefined}
 * @ignore
 */
rune.timer.Timers.prototype.update = function(step) {
    this.m_updateTimers(step);
};

//------------------------------------------------------------------------------
// PRIVATE PROTOTYPE METHODS
//------------------------------------------------------------------------------

/**
 * Updates all Timer objects.
 *
 * @param {number} step Current time step.
 *
 * @return {undefined}
 * @private
 */
rune.timer.Timers.prototype.m_updateTimers = function(step) {
    if (this.paused == true || this.m_timers == null) {
        return;
    }
    
    // CALLBACKS MAY REMOVE TIMERS OR DISPOSE THE MANAGER. NEW TIMERS WAIT
    // UNTIL THE NEXT UPDATE, AND EACH REMAINING TIMER IS UPDATED ONCE.
    var timers = this.m_timers.slice();
    for (var i = 0; i < timers.length; i++) {
        var timer = timers[i];
        if (this.m_timers == null) return;
        if (this.m_timers.indexOf(timer) < 0) continue;
        if (timer.disposed || timer['complete'] === true) {
            this.remove(timer);
        } else {
            this.m_updateTimer(timer, step);
        }
    }
};

/**
 * Updating a Timer object.
 *
 * @param {rune.timer.Timer} timer Timer to update.
 * @param {number} step Current time step.
 *
 * @return {boolean}
 * @private
 */
rune.timer.Timers.prototype.m_updateTimer = function(timer, step) {
    if (timer.update(step) && this.m_timers != null && this.m_timers.indexOf(timer) >= 0) {
        return this.remove(timer);
    }

    return false;
};

/**
 * Deletes all Timer objects.
 *
 * @return {undefined}
 * @private
 */
rune.timer.Timers.prototype.m_disposeTimers = function() {
    this.clear();
    
    this.m_timers = null;
};