Listening to events in Firefox extensions

Gecko uses events to pass information about interesting things that have occurred along to the parties that may wish to know about them.  There are several different categories of events; this article will help you learn about them and direct you to more specific documentation covering each of them.  It also provides some use cases that may be of specific interest.

Types of events

There are multiple types of events that application and extension authors can use to receive notifications from browser and tabbrowser elements to hear about changes relating to loads of the content contained within them.

Simple DOM events

Registering for a DOM event is done using with code such as the following:

function callback(evt) {
  // Do your processing here. Check evt.target for the target of the event.
}

b.addEventListener("event", callback, false)

Where b is the browser or tabbrowser you wish to watch for events from. Keep in mind that the events may come from any frame within the browser or, for a tabbrowser, any of the browsers within it.

Some of the more interesting DOM events you may wish to monitor are listed here:

More details on when load, unload, pageshow and pagehide events are and aren't dispatched is covered in the article on Firefox's caching behaviour.

Web progress listeners

For more information about web loads a web progress listener can be used; these provide more details about the progress of loading data from the web. Both browser and tabbrowser elements support the following:

var progressListener = {
  // add nsIWebProgressImplementation here
}

b.addProgressListener(progressListener);

Where b is the browser or tabbrowser you want to listen to events for. There are code snippets available that give more detail on using web progress listeners.

For a tabbrowser, the above code will only get events from the browser that is currently displayed at the time the event occurs. In order to listen to events from all browsers, including those not currently being displayed, the following example can be used:

var tabsProgressListener = {
  // add tabs progress listener implementation here
}

gBrowser.addTabsProgressListener(tabsProgressListener);

This lets you receive events related to all tabs. More information about listening to events from all tabs is available.

How events are used by Firefox

The Firefox frontend already listens for a number of these progress events from web pages. Most of this goes on in browser.js.

DOMLinkHandler

The DOMLinkHandler object is called by the DOMLinkAdded event in order to detect any RSS feeds, site icons, or OpenSearch plugins for the web site.

pageShowEventHandlers

The pageShowEventHandlers() function is called by the pageshow event and is used to populate the character set menu and update the UI elements associated with any detected feeds or OpenSearch plugins for the website.

XULBrowserWindow

XULBrowserWindow is an nsIWebProgressListener used to get progress events for the currently visible browser. It is used to update the UI for many different reasons:

• Update the progress bar and status messages as pages load
• Turn on and off the throbber as pages load
• Set the site icon when available
• Update the address bar as the user navigates
• Hide notification bars when appropriate as the user navigates
• Apply the site zoom preferences to newly loading pages
• Update the bookmarking star button UI
• Update the identity display as the site's security changes

TabsProgressListener

This object is a tabs progress listener and receives events for all browsers in the window. It is used to detect when a webpage attempts to refresh itself and allow the user to block the attempt.

How events are used by the tabbrowser

tabbrowser maintains a set of objects relating to progress listening for each browser. First it creates a browser-status-filter and adds it as a web progress listener for the browser. Next it creates an internal object to receive all web progress events from the browser. This is created by the method mTabProgressListener(). This receives events from the browser-status-filter. The filter acts to reduce the number of status and progress events to improve performance. The filters are held in the array mFilters, the internal listeners in the array mTabListeners.

The internal listeners are used to send out progress events to listeners registered with addProgressListener() (which receives events from the browser that is currently visible) and addTabsProgressListener() (which receives events from all browsers).

See also

• event
• Listening to events on all tabs
• Mouse gesture events
• Code snippets: Progress listeners