/* Javascript Object Oriented Timer, version 1.0
 * --------------------------------------------------------
 * Copyright (C) 2008 zp bappi | zpbappi (at) gmail (dot) com
 *
 * Details and latest version at:
 * http://abcoder.com/javascript/core_javascript/javascript_timer
 *
 *
 * This script is distributed under the GNU Lesser General Public License (Version 3, 29 June 2007 or later).
 *
 * ================================ IMPORTANT ===========================================
 * This library is free software; you can redistribute it and/or modify it under the terms
 * of the GNU Lesser General Public License as published by the Free Software Foundation;
 * either version 2.1 of the License, or (at your option) any later version.

 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 * See the GNU Lesser General Public License for more details.
 * =======================================================================================
 *
 * Read the entire license text here: http://www.gnu.org/licenses/lgpl.html
 */


/* just declaring the class and pointing the real constructor */
var Timer = function(millis, callback){
        return this._init(millis, callback);
}

Timer.prototype = {
        //*******************************************************
        //Private Block starts here *****************************
        //
        //funcations and variables listed bellow
        //should not be accessed from outside
        //*******************************************************
        VERSION: 1.0,

        /* constructor for Timer object */
        _init: function(millis, callback){

                /* private variables */
                this._interval = 1000;
                this._timer = null;
                this._cbs = [];
                this._multipliers = [];
                this._tickCounts = [];
                this._canRun = [];
                this._stoppedThreads = 0;
                this._runOnce = false;
                this._startedAt = -1;
                this._pausedAt = -1;

                if(typeof(millis)=='number') this._interval = millis;
                this.addCallback(callback);

                return this;
        },


        /* some preset operation, called from start() */
        _preset: function(){
                this._stoppedThreads = 0;
                this._startedAt = -1;
                this._pausedAt = -1;
                for(var i=0; i<this._cbs.length; i++){
                        this._canRun[i] = true;
                        this._tickCounts[i] = 0;
                }
        },


        /* private clock pulse handler */
        /* The kernel */
        // this method actually makes things work
        _ticks: function(initInterval){

                /* process callback here */
                var me = this;
                for(var i=0; i<this._cbs.length; i++){
                        if(typeof(this._cbs[i])=='function' && this._canRun[i]){
                                this._tickCounts[i]++;
                                if(this._tickCounts[i] == this._multipliers[i]){
                                        this._tickCounts[i] = 0;

                                        if(this.runOnce()){
                                                //in runOnce(true) mode, none is allowed to run more once
                                                this._canRun[i] = false;

                                                //count number of callback operations finished
                                                this._stoppedThreads++;
                                        }

                                        /* actually executing callback functions here */
                                        // trying to achieve parallelism for each function
                                        window.setTimeout(me._cbs[i], 0);
                                }
                        }
                }

                /* detect ending pulse for runOnce(true) mode */
                //all callback functions must be called exactly once when running in runOnce(true) mode
                if(this.runOnce() && this._stoppedThreads == this._cbs.length)
                        this.stop();


                /* resume logic */
                if(typeof(initInterval)=='number'){
                        //when resuming, after the first pulse,
                        //start clock with assigned interval and without presetting
                        this.stop().start(null, true);
                }
        },

        //**********************************************************************
        // Private block ends here *********************************************
        //**********************************************************************
        // bellow is public block, i.e., listed function are available to use.
        // further detail about functions can be found just above the function
        //**********************************************************************




        /* get/set mode of running */
        //Parameters:
        //        isRunOnce(optional)->         accepts true or false for setting the mode. default is false.
        //                                                        if false, then timer runs untill each callback executes exactly once.
        //                                                        if true, then timer runs forever until stop() or pause() is called.
        //                                                        also, calling runOnce() without parameter returns the current mode of timer (true or false)
        //Returns: current Timer object(this) or boolean specifying current mode.

        runOnce: function(isRunOnce){
                if(typeof(isRunOnce)=='undefined') return this._runOnce;
                else if(typeof(isRunOnce)=='boolean') this._runOnce = isRunOnce;
                else alert("Invalid argument for runOnce(...).\n\nUsage: runOnce(true | false) /*Default value: false*/\nor, runOnce() to get status");
                return this;
        },


        /* get/set timer clock interval in milli sec */
        //Parameters:
        //        millis(optional)->         accepts integer number only. default is 1000 (1 sec).
        //                                                also, calling runOnce() without parameter returns the current interval of timer in milli sec
        //                                                using any other variation will have no effect, you may try...
        //Returns: current Timer object(this) or integer specifying current interval of the timer

        interval: function(millis){
                if(typeof(millis)=='undefined') return this._interval;
                else if(typeof(millis)=='number') this._interval = Math.floor(millis);
                return this;
        },


        /* stops the timer */
        //Returns: current Timer object(this)
        //CAUTION: DO NOT pass any patameter when using stop. this may have the same destructive effect (or a little less) described for start method.

        stop: function(isPausing){
                if(this._timer){
                        if(!isPausing) this._pausedAt = -1;
                        try{
                                window.clearInterval(this._timer);
                        }
                        catch(ex){
                                //i dont know if this line will be executed ever...
                        }
                        this._timer = null;
                }
                return this;
        },


        /* checks if timer is stopped */
        //Returns:        true if timer is stopped, false otherwise
        //Note:                paused and stopped are different states

        isStopped: function(){
                return ((this._timer == null) && !this.isPaused());
        },


        /* starts the timer */
        //DO NOT pass the parameters when using the timer. these parameters are for internal use only.
        //just use start(). this works fine :)
        //CAUTION:        passing the parameters may cause you diarrhoea or reveal your secret credentials in
        //                         world wide web or have significant desructive effect on your browser!
        //                        the outcome is unpredictable in nature.
        //Returns:  current Timer object(this)

        start: function(_initialInterval, _withoutPreset){
                //when timer is paused, calling start behaves same as calling resume
                //but i do not recomment it
                //use resume when timer is paused
                if(this.isPaused())
                        return this.resume();

                //prevent unnecessary calls to start
                if(!this.isStopped())
                        return this;

                //when resuming, after one pulse, start is called to restore default default attitude of the timer.
                //hence, preset is not to be called
                if(!_withoutPreset)
                        this._preset();

                var tmpInterval = this._interval;

                //when resuming, before the very first pulse,
                //start is called from resume with calculated interval
                //to behave like actually what resume means.
                //in all other cases, it is undefined or null
                if(typeof(_initialInterval)=='number') tmpInterval = _initialInterval;

                //what is this?
                //this is me.
                var me = this;


                //initializing the timer
                //looks familiar, eh!
                this._timer = window.setInterval(function(){me._ticks(_initialInterval);}, tmpInterval);

                //keeps track when the timer starts
                this._startedAt = (new Date()).getTime();
                //needed when resume() then pause() then again resume() is called
                //just track back one step before
                this._startedAt -= (this._interval - tmpInterval);
                return this;
        },


        /* pauses the timer, i.e., freezes execution */
        //it actually works like freezing the timer, dont be fooled by the code.
        //Returns:  current Timer object(this)

        pause: function(){
                if(this._timer){
                        this._pausedAt = (new Date()).getTime();
                        this.stop(true);
                }
                return this;
        },


        /* checks if timer is paused */
        //Returns:        true if timer is paused, false otherwise.
        //Note:                paused and stopped are different stages

        isPaused: function(){
                return (this._pausedAt >= 0);
        },


        /* resumes the timer from paused state */
        //if timer is paused, it is resumed from the state it was (before pause)
        //if timer was not paused, it has no effect
        //Returns:        current Timer object(this)

        resume: function(){
                if(this.isPaused()){
                        var tempInterval = this._interval - ((this._pausedAt - this._startedAt)%this._interval);
                        this._pausedAt = -1;
                        this.start(tempInterval, true);
                }
                return this;
        },


        /* restarts the timer */
        //just a shortcut for stop() and then start()
        //Returns:        current Timer object(this)
        restart: function(){
                return this.stop().start();
        },


        /* adds a callback function to be called */
        //Parameters:
        //        callback(mandatory)->         accepts only a function to be called at each Nth pulse of timer clock
        //                                                        if not a function, the call to this function has no effect.
        //        N(optional)->                        accept only integer value (takes floor if floating number is passed). default value is 1.
        //                                                        calls the callback function at each Nth pulsh of the timer clock.
        //Returns: current Timer object(this)

        addCallback: function(callback, N){
                if(typeof(callback)=='function'){
                        this._cbs.push(callback);
                        if(typeof(N)=='number'){
                                N = Math.floor(N)
                                this._multipliers.push((N < 1 ? 1 : N));
                        }
                        else
                                this._multipliers.push(1);

                        this._tickCounts.push(0);
                        this._canRun.push(true);
                }
                return this;
        },


        /* removes all callback functions added previously */
        //Returns: current Timer object(this)

        clearCallbacks: function(){
                this._cbs.length = 0;
                this._multipliers.length = 0;
                this._canRun.length = 0;
                this._tickCounts.length = 0;
                this._stoppedThreads = 0;
                return this;
        }
};