manages timers that can fire at a particular time, or repeatedly at an interval More...

Inheritance diagram for TimerManager:

Collaboration diagram for TimerManager:

Public Member Functions
	cancelAllTimers ()
	stop and remove all timers More...

	cancelTimer (int id)
	stop and remove a timer More...

	delayTimer (int id, uint delay)
	delay the normal firing by a given amount More...

	delayTimerUntil (int id, uint msTime)
	postpone the normal firing of a timer until a specific time More...

number	getMilliseconds ()
	get the current time in milliseconds More...

number	getWhenTimerFiresNext (int id)
	get the millisecond time when the timer will fire More...

boolean	isPaused ()
	check if the TimerManager is paused More...

boolean	isTimerPaused (int id)
	check if a timer is paused More...

IEventHandler	onInterval (function func, int interval)
	setup handler to be called at a regular interval More...

IEventHandler	onTimeout (function func, int delay)
	setup handler to be called once after a delay More...

	pause ()
	pause all timers indefinitely More...

	pauseTimer (int id)
	pause a timer indefinitely More...

	startTimer (int id, uint delay, boolean oneShot=true)
	create and start a new timer More...

	unpause ()
	resume all paused timers More...

	unpauseTimer (int id)
	resume a specific timer More...

Public Member Functions inherited from EventEmitter
	addHandler (IEventHandler inHandler, int inEventType=all_events)
	add a new handler for some event type, or for all events if no type specified. More...

	blockEvent (int inEventType)
	temporarily ignore all events of a particular type. More...

	clear ()
	remove all handlers More...

	removeHandler (IEventHandler inHandler, int inEventType=all_events)
	remove a handler for some event type, or for all events (see note) if no type specified. More...

	unblockEvent (int inEventType)
	stop ignoring events of a particular type More...

Related Functions
(Note that these are not member functions.)
	getTimerManager
	get the singleton instance of the TimerManager used by the pdg framework More...

	tm
	the singleton instance of the TimerManager More...

Detailed Description

manages timers that can fire at a particular time, or repeatedly at an interval

Precondition: API Stability: 3 - Stable. The API has proven satisfactory, but cleanup in the underlying code may cause minor changes. Backwards-compatibility is guaranteed.

The singleton instance of the TimerManager can be accessed at pdg.tm, for example:

pdg.tm.onTimeout(function(evt) {
                console.log(evt);
}, 1000);

All TimerManager functions are safe to perform while a timer is firing. Functions that alter a timer can be safely used even from within the handler of the timer being changed (ie: while the target timer is in the process of firing)

The TimerManager is an EventEmitter, and will generate pdg.eventType_Timer events:

{ 
    emitter: {},            // the emitter that generated this event
    eventType: 3,           // the event type (pdg.eventType_Timer)
    id: 117440512,          // the timer id (auto-generated up by onTimeout())
    millisec: 1025448321,   // the millisecond time when the timer fired
    msElapsed: 18896        // the time elapsed since the timer was started or last fired
}

Member Function Documentation

cancelAllTimers ( )

stop and remove all timers

This is the same as calling cancelTimer() on every timer in the TimerManager

See Also: cancelTimer()

cancelTimer ( int id )

stop and remove a timer

Parameters

id	the id number of the timer to stop

See Also: cancelAllTimers()

delayTimer	(	int	id,
		uint	delay
	)

delay the normal firing by a given amount

Delay a timer's normal firing by the number of milliseconds passed in. If the timer is a repeating timer, this will only delay the next firing time; the interval will return to normal after the next firing.

If the timer is paused, this adds the delay but does not unpause the timer.

Parameters

id	the id number of the timer to delay
delay	the number of milliseconds to delay

See Also: pauseTimer(); delayTimerUntil()

delayTimerUntil	(	int	id,
		uint	msTime
	)

postpone the normal firing of a timer until a specific time

Sets the specific time in milliseconds (as returned by getMilliseconds() ) at which the timer should fire. If the timer is a repeating timer, this will only postpone the next firing time; it will fire at it's normal interval from then on.

If the timer is paused, this un-pauses the timer so it can fire at the specified time.

Parameters

id	the id number of the timer to postpone
msTime	the millisecond time when it should fire

Note: Millisecond accuracy is attempted but not guaranteed. An additional delay of several milliseconds is common.

See Also: delayTimer(); pauseTimer()

getMilliseconds ( )

get the current time in milliseconds

Gets the current millisecond time, from an arbitrary base time prior to the application start.

Note: Many events and callbacks pass this value (or a ms delta since the last call), so you can often avoid repeated calls to getMilliseconds() by using the value or millisecond delta passed in.

getWhenTimerFiresNext ( int id )

get the millisecond time when the timer will fire

Gets the millisecond time when the timer is set to fire next. If the timer is paused, or is a one-shot timer that is current firing, then it will return pdg.timer_Never.

Returns: the millisecond time the timer will fire

isPaused ( )

check if the TimerManager is paused

Returns: true if the TimerManager is paused, false if not

See Also: pause(); isTimerPaused()

isTimerPaused ( int id )

check if a timer is paused

Parameters

id	the id number of the timer to check

Returns: true if the timer is paused, false if not

See Also: pause(); pauseTimer()

onInterval	(	function	func,
		int	interval
	)

setup handler to be called at a regular interval

This creates a handler from your function and automatically assigns a timer id. You can call cancel() on the handler object returned to remove the timer and cleanup the handler. The timer field of the handler object contains the timer's id number for use in other TimerManager calls.

var t = pdg.tm.onInterval( function(evt) {
                console.log('fired ');
}, 1000);
pdg.tm.delayTimer(t.timer, 500);  // wait an extra 1/2 second to fire
t.cancel();   // removes the timer and the handler for it

Parameters

func	the handler function to call
interval	the number of milliseconds between calls

Returns: an IEventHandler object with a cancel() method and a timer value

See Also: onTimeout(); startTimer()

onTimeout	(	function	func,
		int	delay
	)

setup handler to be called once after a delay

This creates a handler from your function and automatically assigns a timer id. You can call cancel() on the handler object returned to remove the timer and cleanup the handler. The timer field of the handler object contains the timer's id number for use in other TimerManager calls.

Parameters

func	the handler function to call
delay	the number of milliseconds to wait

Returns: an IEventHandler object with a cancel() method and a timer value

See Also: onInterval(); startTimer()

pause ( )

pause all timers indefinitely

Pause all timers in the TimerManager until unpause() or unpauseTimer() are called. When unpaused they continue their behavior as if no time had passed between the pause() and unpause() calls.

Note: timers added after pause() is called are not paused and will run as normal.

See Also: unpause(); unpauseTimer(); isPaused()

pauseTimer ( int id )

pause a timer indefinitely

Pause the specified timer until unpause() or unpauseTimer() are called. When unpaused, the timer will continue as if no time had passed between the pauseTimer() and unpauseTimer() calls.

See Also: unpauseTimer(); unpause(); isTimerPaused()

startTimer	(	int	id,
		uint	delay,
		boolean	oneShot = `true`
	)

create and start a new timer

Create a new timer and start it running. If the timer is a one-shot timer, it will wait delay ms then fire off a pdg.eventType_Timer event. If it is a repeating timer it will fire repeatedly at the delay ms interval until canceled by a call to cancelTimer().

If there is already a timer with the given id, it will be removed and the new timer will replace it.

You must install an event handler to get the timer events, either in the TimerManager itself, or in the EventManager. For that reason it is often more convenient to use onTimeout() or onInterval(), since they set up the event handler for you.

Parameters

id	the id number of the timer to start or reset
delay	the time before the timer should fire (or the firing interval if this is a repeating timer)
oneShot	true mean