/* 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;

                    }

};