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:
Event | Description |
DOMLinkAdded | Dispatched when a new HTML <link> element is detected in the document. |
DOMTitleChanged | Dispatched when the title of the page changes. |
DOMContentLoaded | Dispatched when the initial DOM for the page is completely loaded. |
load | Dispatched after the page—including images—has first finished loading. |
unload | Dispatched when the user has navigated away from the page. |
pageshow | Dispatched when a page is newly displayed. |
pagehide | Dispatched when a page is hidden. |
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).