Timer

Kind of class:	class
Inherits from:	Dispatcher
Author:	Martijn de Visser
Classpath:	org.asapframework.util.timer.Timer
File last modified:	Thursday, 13 July 2006, 13:48:48

► View source

▼ Hide source

/*
Copyright 2005-2006 by the authors of asapframework, http://asapframework.org

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

import org.asapframework.events.Dispatcher;
import org.asapframework.util.timer.TimerEvent;

/**
@author Martijn de Visser
@description The Timer class enables the creation of timers that run for a specific number of milliseconds and can optionally run for a specific number of loops. Generated events : start, stop, pause, resume, progress, loopReady, timerReady. Please note that by default, the Timer does NOT generate progress events. Use either the 'reportProgress' paramter in the {@link #start} method to enable progress reporting, or set the 'reportProgress' to true. Progress reporting is very CPU INTENSIVE!
@usage The following creates and then starts a Timer with an infinite number of 2 second loops:<br>
    <code>
    myTimer:Timer = new Timer(2000);
    myTimer.start();
    </code>
    This creates a timer that runs 2 one second loops:<br>
    <code>
    myTimer:Timer = new Timer(1000, 2 );
    myTimer.start();
    </code>
*/

class org.asapframework.util.timer.Timer extends Dispatcher {

    /**
        @method addEventListener
        @usage <code>Timer.addEventListener(event, listener)</code><p>
        @description See {@link TimerEvent}
        @param event (String) Required; event to subscribe listener to.
        @param listener (Object) The listener object to subscribe to the specified event.
    */

    /**
        @method removeEventListener
        @usage <code>Timer.removeEventListener(event, listener)</code><p>
        @description  Stops a listener from receiving the specified event.
        @param event (String) Required; event to unsubscribe listener from.
        @param listener (Object) The listener object to unsubscribe from the specified event.
    */
    // event handling
    private var bPaused:Boolean;
    private var bRunning:Boolean;
    private var bReportProgress:Boolean;

    private var startTime:Number;
    private var playTime:Number;
    private var nLoop:Number;
    private var nLoops:Number;
    private var nDuration:Number;
    private var updateInterval:Number;
    private var intervalID:Number;

    /**
    Constructor
    @param nDuration (Number) Optional, number of milliseconds to run.
    @param loops (Number) Optional, number of loops to run. Defaults to 1 when ommitted.
    @param interval (Number) Optional, specifies how often the Timer is updated. Default is 50 milliseconds (e.g. 20 times a second).
    @param start (Boolean) Optional, if true, immediately starts the Timer after creation. Default is false.
    */
    public function Timer( inDuration:Number, inLoops:Number, inInterval:Number, inStartTimer:Boolean ) {

        super();

        // set vars
        bPaused = false;
        bRunning = false;
        bReportProgress = false;
        playTime = 0;
        nLoop = 0;
        nLoops = 1;
        intervalID = -1;
        updateInterval = 50;

        if (inDuration != undefined) { nDuration = inDuration; }
        if (inLoops != undefined) { nLoops = inLoops; }
        if (inInterval != undefined) { updateInterval = inInterval; }

        // if _startTimer is true, start the time
        if (inStartTimer)    {

            start(nDuration);
        }
    }


    //////////////////////////
    //                         //
    //     PRIVATE FUNCTIONS    //
    //                         //
    //////////////////////////


    // called through setInterval to update timer
    /**
    @sends TimerEvent#PROGRESS
    @sends TimerEvent#LOOPREADY
    @sends TimerEvent#READY
    */
    private function update() : Void {

        // update timer
        playTime = (getTimer() - startTime);

        // dispatch progress event
        dispatchEvent( new TimerEvent( TimerEvent.PROGRESS, this, loop, loops, loopProgress, totalProgress ));

        if (playTime >= nDuration) {

            // dispatch loopReady event
            dispatchEvent( new TimerEvent( TimerEvent.LOOPREADY, this, loop, loops ));

            if (nLoops > 0) {

                // check current nLoop
                if (nLoop == nLoops) {

                    // dispatch ready event
                    dispatchEvent( new TimerEvent( TimerEvent.READY, this ));

                    // clear interval
                    clearInterval(intervalID);
                    bRunning = false;

                } else {

                    // start next loop
                    nLoop++;
                    startTime = getTimer();
                }

            } else {

                // run indefinitively
                startTime = getTimer();
            }
        }
    }

    //////////////////////////
    //                        //
    //     PUBLIC FUNCTIONS    //
    //                        //
    //////////////////////////


    /**
        @method start
        @usage <code>Timer.start( nDuration );</code><p>
        @description Starts the timer.
        @param inDuration (Number) Number of milliseconds / loop. Optional when already set on construction.
        @param inReportProgress (Boolean) optional, set to true to have the time report loop progress. CPU INTENSIVE!
        @sends TimerEvent#START
    */
    public function start( inDuration:Number, inReportProgress:Boolean ) : Void {

        // start the timer
        if (inDuration != undefined) nDuration = inDuration;
        if (nLoops > 0 ) { nLoop = 1; }
        startTime = getTimer();
        bPaused = false;
        bRunning = true;
        
        // dispatch start event
        dispatchEvent( new TimerEvent( TimerEvent.START, this, loop, loops ));

        // was reportProgress param passed along?
        if (inReportProgress != undefined) bReportProgress = inReportProgress;

        // set interval
        if (bReportProgress) {
            intervalID = setInterval(this, "update", updateInterval );
        } else {
            intervalID = setInterval(this, "update", nDuration );
        }
    }

    /**
        @method stop
        @usage <code>Timer.stop();</code><p>
        @description Stops the timer.
        @sends TimerEvent#STOP
    */
    public function stop() : Void {

        // dispatch stop event
        dispatchEvent( new TimerEvent( TimerEvent.STOP, this ));
        clearInterval(intervalID);
        bRunning = false;
    }

    /**
        @method pause
        @usage <code>Timer.pause();</code><p>
        @description Pauses the timer.
        @sends TimerEvent#PAUSE
    */
    public function pause() : Void {
        
        // dispatch pause event
        dispatchEvent( new TimerEvent( TimerEvent.PAUSE, this ));
        // clear interval
        clearInterval(intervalID);
        // set flag
        bPaused = true;
    }

    /**
        @method resume
        @usage <code>Timer.resume();</code><p>
        @description Resumes the timer.
        @sends TimerEvent#RESUME
    */
    public function resume() : Void {

        if (bPaused) {

            // dispatch resume event
            dispatchEvent( new TimerEvent( TimerEvent.RESUME, this ));
            // set flag
            bPaused = false;
            // update timer
            startTime = getTimer() - playTime;
            // set interval
            intervalID = setInterval(this, "update", updateInterval );
        }
    }

    /**
        @method reset
        @usage <code>Timer.reset();</code><p>
        @description Resets the timer (same as a .stop(), followed by a .start()).
        @sends TimerEvent#RESET
    */
    public function reset() : Void {

        // dispatch reset event
        dispatchEvent( new TimerEvent( TimerEvent.RESET, this ));
        stop();
        start();
    }


    //////////////////////////////////////////
    //                                        //
    //     PUBLIC GETTER / SETTER FUNCTIONS    //
    //                                        //
    //////////////////////////////////////////


    /**
        @property loopProgress (Number) Returns the progress of current loop in milliseconds.
    */
    public function get loopProgress() : Number {

        return playTime;
    }

    /**
        @property totalProgress (Number) Returns the progress of all loops in milliseconds.
    */
    public function get totalProgress() : Number {

        return ((nLoop - 1) * nDuration ) + playTime;
    }

    /**
        @property loopPercentage (Number) Returns the progress of current loop as a percentage.
    */
    public function get loopPercentage() : Number {

        return int(Math.max(1, Math.min(100, (playTime / nDuration ) * 100)));
    }

    /**
        @property totalPercentage (Number) Returns the progress of all loops as a percentage.
    */
    public function get totalPercentage() : Number {

        return int(Math.max(1, Math.min(100, (totalProgress / (nLoops * nDuration ) ) * 100)));
    }

    /**
        @property duration (Number) Returns or sets the duration of a loop.
    */
    public function get duration() : Number {

        return nDuration;
    }

    public function set duration( value:Number ) : Void {

        nDuration = (value < 0)? 0 : value;
    }

    /**
        @property interval (Number) Specifies how often the Timer is updated (msecs).
    */
    public function set interval( value:Number ) : Void {

        updateInterval = (value < 1)? 10 : value;
    }
    
    /**
        @property Set this value to true to have the timer report loop progress by default. CPU INTENSIVE!
    */
    public function set reportProgress ( inReportProgress:Boolean ) {
    
        bReportProgress = inReportProgress;
    }

    /**
        @property paused (Boolean) Returns if the timer is bPaused
    */
    public function get paused() : Boolean {

        return bPaused;
    }

    /**
        @property running (Boolean) Returns if the timer is running (true during a pause!)
    */
    public function get running() : Boolean {

        return bRunning;
    }

    /**
        @property loop (Number) Returns the current loop the timer is in.
    */
    public function get loop() : Number {

        return nLoop;
    }

    /**
        @property loops (Number) Returns or sets the total number of loops.
    */
    public function get loops() : Number {

        return nLoops;
    }

    public function set loops( value:Number ) : Void {

        nLoops = (value < 0)? 0 : value;
    }

    public function toString () : String {
        return ";org.asapframework.util.timer.Timer";
    }
}

The Timer class enables the creation of timers that run for a specific number of milliseconds and can optionally run for a specific number of loops. Generated events : start, stop, pause, resume, progress, loopReady, timerReady. Please note that by default, the Timer does NOT generate progress events. Use either the 'reportProgress' paramter in the start method to enable progress reporting, or set the 'reportProgress' to true. Progress reporting is very CPU INTENSIVE!

Usage:

The following creates and then starts a Timer with an infinite number of 2 second loops:
```
myTimer:Timer = new Timer(2000);
myTimer.start();
```
This creates a timer that runs 2 one second loops:
```
myTimer:Timer = new Timer(1000, 2 );
myTimer.start();
```

Events broadcasted to listeners:

TimerEvent with type: PROGRESS
- (null)
TimerEvent with type: LOOPREADY
- (null)
TimerEvent with type: READY
- (null)
TimerEvent with type: START
- (null)
TimerEvent with type: STOP
- (null)
TimerEvent with type: PAUSE
- (null)
TimerEvent with type: RESUME
- (null)
TimerEvent with type: RESET
- (null)

Summary

Constructor

Timer (inDuration:Number, inLoops:Number, inInterval:Number, inStartTimer:Boolean)
- Constructor

Instance properties

bPaused : Boolean
- See TimerEvent
bRunning : Boolean
bReportProgress : Boolean
startTime : Number
playTime : Number
nLoop : Number
nLoops : Number
nDuration : Number
updateInterval : Number
intervalID : Number
loopProgress : Number
totalProgress : Number
loopPercentage : Number
totalPercentage : Number
duration : Number
interval (value:Number) : Number
reportProgress (inReportProgress:Boolean)
paused : Boolean
running : Boolean
loop : Number
loops : Number

Instance properties inherited from Dispatcher

addEventListener dispatchEvent removeEventListener

Instance methods

update : Void
start (inDuration:Number, inReportProgress:Boolean) : Void
- Starts the timer.
stop : Void
- Stops the timer.
pause : Void
- Pauses the timer.
resume : Void
- Resumes the timer.
reset : Void
- Resets the timer (same as a .stop(), followed by a .start()).
toString : String

Constructor

Timer

function Timer (

inDuration:Number, inLoops:Number, inInterval:Number, inStartTimer:Boolean)

Constructor

Parameters:

nDuration:

(Number) Optional, number of milliseconds to run.

loops :

(Number) Optional, number of loops to run. Defaults to 1 when ommitted.

interval :

(Number) Optional, specifies how often the Timer is updated. Default is 50 milliseconds (e.g. 20 times a second).

start :

(Boolean) Optional, if true, immediately starts the Timer after creation. Default is false.

Instance properties

bPaused

private bPaused:Boolean

(read)

See TimerEvent

Parameters:

event :

(String) Required; event to subscribe listener to.

listener:

(Object) The listener object to subscribe to the specified event.

Usage:

Timer.addEventListener(event, listener)

bReportProgress

private bReportProgress:Boolean

(read)

bRunning

private bRunning:Boolean

(read)

duration

duration:Number

(read,write)

interval

interval:Number

(write)

intervalID

private intervalID:Number

(read)

loop

loop:Number

(read)

loopPercentage

loopPercentage:Number

(read)

loopProgress

loopProgress:Number

(read)

loops

loops:Number

(read,write)

nDuration

private nDuration:Number

(read)

nLoop

private nLoop:Number

(read)

nLoops

private nLoops:Number

(read)

paused

paused:Boolean

(read)

playTime

private playTime:Number

(read)

reportProgress

reportProgress

(write)

running

running:Boolean

(read)

startTime

private startTime:Number

(read)

totalPercentage

totalPercentage:Number

(read)

totalProgress

totalProgress:Number

(read)

updateInterval

private updateInterval:Number

(read)

Instance methods

pause

function pause (

) : Void

Pauses the timer.

Usage:

Timer.pause();

Events broadcasted to listeners:

TimerEvent with type: PAUSE
- (null)

reset

function reset (

) : Void

Resets the timer (same as a .stop(), followed by a .start()).

Usage:

Timer.reset();

Events broadcasted to listeners:

TimerEvent with type: RESET
- (null)

resume

function resume (

) : Void

Resumes the timer.

Usage:

Timer.resume();

Events broadcasted to listeners:

TimerEvent with type: RESUME
- (null)

start

function start (

inDuration:Number, inReportProgress:Boolean) : Void

Starts the timer.

Parameters:

inDuration :

(Number) Number of milliseconds / loop. Optional when already set on construction.

inReportProgress:

(Boolean) optional, set to true to have the time report loop progress. CPU INTENSIVE!

Usage:

Timer.start( nDuration );

Events broadcasted to listeners:

TimerEvent with type: START
- (null)

stop

function stop (

) : Void

Stops the timer.

Usage:

Timer.stop();

Events broadcasted to listeners:

TimerEvent with type: STOP
- (null)

toString

function toString (

) : String

update

private function update (

) : Void

Events broadcasted to listeners:

TimerEvent with type: PROGRESS
- (null)
TimerEvent with type: LOOPREADY
- (null)
TimerEvent with type: READY
- (null)