nsITimer

The nsITimer interface offers a functionality to invoke a function after a specified delay.

Note that the delay is approximate: the timer can be fired before the requested time has elapsed.

nsITimer instances must be initialized by calling one of the initialization methods. You may also re-initialize (using one of the initialization 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.

Inherits from: nsISupports

Implemented by: @mozilla.org/timer;1. To create an instance, use:

var timer = Components.classes["@mozilla.org/timer;1"]
            .createInstance(Components.interfaces.nsITimer);

Method overview

Attributes

Constants

Methods

cancel()

Cancels 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 cancel();

Parameters

None.

init()

Initialize a timer that will fire after the specified delay. A user must keep a reference to this timer till it is no longer needed or has been cancelled.

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

Parameters

aObserver

A callback Object, that is capable listening to timer events. If the timer fires, the observer will be notified via the nsIObserver Interface. The subject is set to the nsITimer Object which fired, the topic is equal to "timer-callback" and data is always set to null.

aDelay

Timeout delay in milliseconds.

aType

Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

initWithCallback()

Initialize a timer to fire after the given millisecond interval. This version takes a function to call.

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

Parameters

aCallback

An nsITimerCallback interface to call when timer expires.

aDelay

Timeout delay in milliseconds.

aType

Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

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.

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

Parameters

aCallback

A nsTimerCallbackFunc interface compatible function to call when timer fires.

aClosure

An opaque pointer to pass to that function.

aDelay

Timeout delay in milliseconds.

aType

Defines the timer type: one shot, repeating slack or repeating precise. Must be one of the constants defined under Constants on this page.

Remarks

TYPE_REPEATING_SLACK timer is the preferable repeating timer type for most situations

Example

Using initWithCallback:

// we need an nsITimerCallback compatible...
// ... interface for the callbacks.
var event = {
  notify: function(timer) {
    alert("Fire!");
  }
}
// Now it is time to create the timer...  
var timer = Components.classes["@mozilla.org/timer;1"].createInstance(Components.interfaces.nsITimer);
// ... and to initialize it, we want to call event.notify() ...
// ... one time after exactly ten seconds. 
timer.initWithCallback(event,10000, Components.interfaces.nsITimer.TYPE_ONE_SHOT);

Using init, we fire an event every 10 seconds:

var event = {
  observe: function(subject, topic, data) {
    dump("hello world\n");
  }
}
var timer = Components.classes["@mozilla.org/timer;1"].createInstance(Components.interfaces.nsITimer);
const TYPE_REPEATING_PRECISE_CAN_SKIP = Components.interfaces.nsITimer.TYPE_REPEATING_PRECISE_CAN_SKIP;
timer.init(event, 10*1000, TYPE_REPEATING_PRECISE_CAN_SKIP);

See also

• nsTimerCallbackFunc
• nsITimerCallback