Listening to events on all tabs

Firefox 3.5 adds support for listening to progress events on all tabs.

Adding a listener

To listen to progress events on all tabs, call the browser's addTabsProgressListener() method:

gBrowser.addTabsProgressListener(myProgressListener);

myProgressListener is an object that implements the callbacks used to provide notifications of progress events.

Removing a listener

To remove a previously installed progress listener, call removeTabsProgressListener():

gBrowser.removeTabsProgressListener(myProgressListener);

Implementing a listener

The listener object itself has five methods it can implement to handle various events:

onLocationChange

Called when the URI of the document displayed in the tab changes.

void onLocationChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  nsIURI aLocation
  [optional] in unsigned long aFlags
);

Parameters

aBrowser

The browser representing the tab whose location changed.

aWebProgress

The progress instance responsible for handling the events.

aRequest

The nsIRequest object representing the associated request.

aLocation

An nsIURI object indicating the tab's new URI.

aFlags

Optional: This is a value which explains the situation or the reason why the location has changed. Optional from Gecko 10

onProgressChange

Called when updated progress information for the download of a document is available.

void onProgressChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  PRInt32 aCurSelfProgress,
  PRInt32 aMaxSelfProgress,
  PRInt32 aCurTotalProgress,
  PRInt32 aMaxTotalProgress
);

Parameters

aBrowser

The browser representing the tab for which updated progress information is being provided.

aWebProgress

The progress instance responsible for handling the events.

aRequest

The nsIRequest object representing the associated request.

aCurSelfProgress

The current progress for the request indicated by the request parameter.

aMaxSelfProgress

The value representing 100% complete for the request indicated by the request parameter.

aCurTotalProgress

The current progress for all requests associated with webProgress.

aMaxTotalProgress

The total progress for all requests associated with webProgress.

onSecurityChange

Notification called for security progress. This method will be called on security transitions (eg HTTP -> HTTPS, HTTPS -> HTTP, FOO -> HTTPS) and after document load completion. It might also be called if an error occurs during network loading.

void onSecurityChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  unsigned long aState
);

Parameters

aBrowser

The browser that fired the notification.

aWebProgress

The nsIWebProgress instance that fired the notification.

aRequest

The nsIRequest that has new security state.

aState

A value composed of the Security State Flags and the Security Strength Flags described in the documentation for nsIWebProgressListener.

onStateChange

Notification indicating the state has changed for one of the requests associated with aWebProgress.

void onStateChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  unsigned long aStateFlags,
  nsresult aStatus
);

Parameters

 

aBrowser

The browser that fired the notification.

aWebProgress

The nsIWebProgress instance that fired the notification.

aRequest

The nsIRequest that has changed state. This parameter may be null. Need more information on what NULL means.

aStateFlags

Flags indicating the new state. This value is a combination of one of the State Transition Flags and one or more of the State Type Flags defined in the nsIWebProgressListener documentation. Any undefined bits are reserved for future use.

aStatus

Error status code associated with the state change; this indicates whether or not the request was successful. This parameter should be ignored unless aStateFlags includes the STATE_STOP bit.

onStatusChange

Notification that the status of a request has changed. The status message is intended to be displayed to the user (e.g., in the status bar of the browser).

void onStatusChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  nsresult aStatus,
  PRUnichar *aMessage
);

Parameters

aBrowser

The browser that fired the notification.

aWebProgress

The nsIWebProgress instance that fired the notification.

aRequest

The nsIRequest that has new status.

aStatus

This value is not an error code. Instead, it is a numeric value that indicates the current status of the request. This interface does not define the set of possible status codes.

Note: Some status values are defined by nsITransport and nsISocketTransport.

aMessage

Localized text corresponding to aStatus.

onRefreshAttempted

Notification that a refresh or redirect has been requested in aWebProgress for example, via a <meta http-equiv="refresh"> or an HTTP Refresh: header. If any registered progress listener returns false from this method then the attempt to refresh will be blocked.

boolean onRefreshAttempted(
  nsIDOMXULElement aBrowser,
  nsIWebProgress webProgress,
  nsIURI aRefreshURI,
  long aMillis,
  boolean aSameURI
);

Parameters

aBrowser

The browser that fired the notification.

aWebProgress

The nsIWebProgress instance that fired the notification.

aRefreshURI

The new URI that aWebProgress has requested redirecting to.

aMillis

The delay (in milliseconds) before refresh.

aSameURI

True if aWebProgress is requesting a refresh of the current URI. False if aWebProgress is requesting a redirection to a different URI.

Return value

true if the refresh may proceed. false if the refresh should be aborted.

onLinkIconAvailable

Notification that the site icon for a browser has been found.

void onLinkIconAvailable(
  nsIDOMXULElement aBrowser,
);

Parameters

aBrowser

The browser that fired the notification.