nsITimer Interface Reference

nsITimer instances must be initialized by calling one of the "init" methods documented below. More...

import "nsITimer.idl";

Collaboration diagram for nsITimer:

List of all members.

Public Member Functions
void	init (in nsIObserver aObserver, in unsigned long aDelay, in unsigned long aType)
	Initialize a timer that will fire after the said delay.
void	initWithFuncCallback (in nsTimerCallbackFunc aCallback, in voidPtr aClosure, in unsigned long aDelay, in unsigned long aType)
	Initialize a timer to fire after the given millisecond interval.
void	initWithCallback (in nsITimerCallback aCallback, in unsigned long aDelay, in unsigned long aType)
	Initialize a timer to fire after the given millisecond interval.
void	cancel ()
	Cancel the timer.
Public Attributes
const short	TYPE_ONE_SHOT = 0
	Type of a timer that fires once only.
const short	TYPE_REPEATING_SLACK = 1
	After firing, a TYPE_REPEATING_SLACK timer is stopped and not restarted until its callback completes.
const short	TYPE_REPEATING_PRECISE = 2
	An TYPE_REPEATING_PRECISE repeating timer aims to have constant period between firings.
attribute unsigned long	delay
	The millisecond delay of the timeout.
attribute unsigned long	type
	The timer type - one of the above TYPE_* constants.
readonly attribute voidPtr	closure
	The opaque pointer pass to initWithFuncCallback.
readonly attribute nsITimerCallback	callback
	The nsITimerCallback object passed to initWithCallback.
attribute nsIEventTarget	target
	The nsIEventTarget where the callback will be dispatched.

---

Detailed Description

nsITimer instances must be initialized by calling one of the "init" methods documented below.

You may also re-initialize (using one of the init() methods) an existing instance to avoid the overhead of destroying and creating a timer. It is not necessary to cancel the timer in that case.

---

Member Function Documentation

void nsITimer::cancel

(

)

Cancel the timer.

This method works on all types, not just on repeating timers -- you might want to cancel a TYPE_ONE_SHOT timer, and even reuse it by re-initializing it (to avoid object destruction and creation costs by conserving one timer instance).

void nsITimer::init	(	in nsIObserver	aObserver,
		in unsigned long	aDelay,
		in unsigned long	aType
	)

Initialize a timer that will fire after the said delay.

A user must keep a reference to this timer till it is is no longer needed or has been cancelled.

Parameters:

aObserver

the callback object that observes the ``timer-callback'' topic with the subject being the timer itself when the timer fires:

observe(nsISupports aSubject, => nsITimer string aTopic, => ``timer-callback'' wstring data => null

Parameters:

	aDelay	delay in milliseconds for timer to fire
	aType	timer type per TYPE* consts defined above

void nsITimer::initWithCallback	(	in nsITimerCallback	aCallback,
		in unsigned long	aDelay,
		in unsigned long	aType
	)

Initialize a timer to fire after the given millisecond interval.

This version takes a function to call and a closure to pass to that function.

Parameters:

	aFunc	nsITimerCallback interface to call when timer expires
	aDelay	The millisecond interval
	aType	Timer type per TYPE* consts defined above

void nsITimer::initWithFuncCallback	(	in nsTimerCallbackFunc	aCallback,
		in voidPtr	aClosure,
		in unsigned long	aDelay,
		in unsigned long	aType
	)

Initialize a timer to fire after the given millisecond interval.

This version takes a function to call and a closure to pass to that function.

Parameters:

	aFunc	The function to invoke
	aClosure	An opaque pointer to pass to that function
	aDelay	The millisecond interval
	aType	Timer type per TYPE* consts defined above

---

Member Data Documentation

readonly attribute nsITimerCallback nsITimer::callback

The nsITimerCallback object passed to initWithCallback.

readonly attribute voidPtr nsITimer::closure

The opaque pointer pass to initWithFuncCallback.

attribute unsigned long nsITimer::delay

The millisecond delay of the timeout.

NOTE: Re-setting the delay on a one-shot timer that has already fired doesn't restart the timer. Call one of the init() methods to restart a one-shot timer.

attribute nsIEventTarget nsITimer::target

The nsIEventTarget where the callback will be dispatched.

Note that this target may only be set before the call to one of the init methods above.

attribute unsigned long nsITimer::type

The timer type - one of the above TYPE_* constants.

const short nsITimer::TYPE_ONE_SHOT = 0

Type of a timer that fires once only.

const short nsITimer::TYPE_REPEATING_PRECISE = 2

An TYPE_REPEATING_PRECISE repeating timer aims to have constant period between firings.

The processing time for each timer callback should not influence the timer period. However, if the processing for the last timer firing could not be completed until just before the next firing occurs, then you could have two timer notification routines being executed in quick succession.

const short nsITimer::TYPE_REPEATING_SLACK = 1

After firing, a TYPE_REPEATING_SLACK timer is stopped and not restarted until its callback completes.

Specified timer period will be at least the time between when processing for last firing the callback completes and when the next firing occurs.

This is the preferable repeating type for most situations.

---

The documentation for this interface was generated from the following file:

• nsITimer.idl