/**
 * TimerHelper
 * John Reeves, john.reeves@mailc.net, http://www.jonnyreeves.co.uk/
 * March 2008
 *
 * Timer Class based on user’s system clock for accurate timing in ActionScript
 * When creating an instance of this class, use the `onTick` prototype to get
 * readings, a simple example would be:
 *
 *      class TimerExample
 *      {
 *              private var _timer:TimerHelper;
 *
 *              // Constructor, create instance of Timer.
 *              public function TimerExample() {
 *                      this._timer = new TimerHelper();
 *                      this._timer.onTick = mx.utils.Delegate.create(this, onTimerTick);
 *              }
 *
 *              // Timer callback, handled by the Delegate above.
 *              public function onTimerTick():Void {
 *                      trace(’Timer Callback: ‘ + this._timer.getElapsed() + ‘ seconds’);
 *              }
 *
*/
class co.uk.jonnyreeves.helpers.TimerHelper
{
        /**
         * Indicaqtes if the TimerHelper is Running.
        */
        private var _isRunning:Boolean;
       
        /**
         * Interval for Tracking the clock’s ticks
        */
        private var _tickInterval:Number;
       
        /**
         * Time in seconds elapsed whilist the timer has been running
        */
        private var _secondsElpased:Number;
       
        /**
         * Previous Reading from the Date Object.
        */
        private var _previousTime:Number;
       
        /**
         * Is the TimerHelper using the system clock, or falling back to using an
         * Interval.
        */
        private var _useSystemClock:Boolean;
       
       
        /**
         * Constructor.
         *
         *      @param Void
         *      @return Void
        */
        public function TimerHelper()
        {
                this._isRunning = false;
                this._tickInterval = 0;
                this._secondsElpased = 0;
               
                // Check that we can use the local system clock
                if (isNaN(new Date().getTime())) {
                        this._useSystemClock = false;
                        trace (‘Timer::construct() -> Could not initialise Local System Clock’);
                }
                else {
                        this._useSystemClock = true;
                }
        }

       
        /**
         * Starts the timer.
         *
         *      @param Void
         *      @return Void
        */
        public function start():Void
        {
                // Remove an existing interval
                if (this._isRunning) {
                        this.pause();
                }
               
                // Update last time
                if (this._useSystemClock) {
                        this._previousTime = new Date().getTime();
                }
               
                // Create the new interval.
                this._tickInterval = setInterval(this, ‘__advanceOneTick’, 1000);
                this._isRunning = true;
        }
       
        /**
         * Pauses the timer on its current value.
         *
         *      @param Void
         *      @return Void
        */
        public function pause():Void
        {
                clearInterval(this._tickInterval);
        }
       
       
        /**
         * Resets the Timer back to 0.
         *
         *      @param Void
         *      @return Void
        */
        public function reset():Void
        {
                this.pause();
                this._secondsElpased = 0;
                this._isRunning = false;
        }
       
       
        /**
         * Advance the timer one "tick" either by polling the System Clock, or
         * incrementing.
         *
         *      @param Void
         *      @return Void
        */
        private function __advanceOneTick():Void
        {
                if (this._useSystemClock)
                {
                        var date:Date = new Date();
                        this._secondsElpased += (date.getTime() – this._previousTime) / 1000
                        this._previousTime = date.getTime();
                }
                else {
                        // Fall back to incremening, this method is less acurate.
                        this._secondsElpased += 1;
                }
                               
                // Call the callback Method (depricated)
                this.onTick();
        }
       
       
        /**
         * Accessor method for getting the number of seconds elapsed
         *
         *      @param Void
         *      @return Void
        */
        public function getElapsed():Number
        {
                return this._secondsElpased
        }
       
       
        /**
         * Call back method letting you hook into the timer.
         *
         *      @param Void
         *      @return Void
         *      @depricated
        */
        public function onTick():Void
        {
        }
}