Listening to events on all tabs

  • Revision slug: Listening_to_events_on_all_tabs
  • Revision title: Listening to events on all tabs
  • Revision id: 64337
  • Created:
  • Creator: saneyuki_s
  • Is current revision? No
  • Comment 18 words added, 18 words removed

Revision Content

{{ fx_minversion_header("3.5") }}

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
);
Parameters
aBrowser
The browser representing the tab whose location changed.
aWebProgress
The progress instance responsible for handling the events.
aRequest
The {{ interface("nsIRequest") }} object representing the associated request.
aLocation
An {{ interface("nsIURI") }} object indicating the tab's new URI.

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 {{ interface("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.

Note: These notifications will only occur if a security package is installed.
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 {{ interface("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 {{ interface("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.
NOTE: aStatus may be a success code even for server generated errors, such as the HTTP 404 File Not Found error. In such cases, the request itself should be queried for extended error information (e.g., for HTTP requests see nsIHttpChannel).

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.

onLinkIconAvailable

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

void onLinkIconAvailable(
  nsIDOMXULElement aBrowser,
);
Parameters
aBrowser
The browser that fired the notification.

Revision Source

<p>{{ fx_minversion_header("3.5") }}</p>
<p>Firefox 3.5 adds support for listening to progress events on all tabs.</p>
<h2>Adding a listener</h2>
<p>To listen to progress events on all tabs, call the browser's <code>addTabsProgressListener()</code> method:</p>
<pre>gBrowser.addTabsProgressListener(myProgressListener);
</pre>
<p><code>myProgressListener</code> is an object that implements the callbacks used to provide notifications of progress events.</p>
<h2>Removing a listener</h2>
<p>To remove a previously installed progress listener, call <code>removeTabsProgressListener()</code>:</p>
<pre>gBrowser.removeTabsProgressListener(myProgressListener);
</pre>
<h2>Implementing a listener</h2>
<p>The listener object itself has five methods it can implement to handle various events:</p>
<h3>onLocationChange</h3>
<p>Called when the URI of the document displayed in the tab changes.</p>
<pre>void onLocationChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  nsIURI aLocation
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> representing the tab whose location changed.</dd> <dt><code>aWebProgress</code></dt> <dd>The progress instance responsible for handling the events.</dd> <dt><code>aRequest</code></dt> <dd>The {{ interface("nsIRequest") }} object representing the associated request.</dd> <dt><code>aLocation</code></dt> <dd>An {{ interface("nsIURI") }} object indicating the tab's new URI.</dd>
</dl>
<h3>onProgressChange</h3>
<p>Called when updated progress information for the download of a document is available.</p>
<pre>void onProgressChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  PRInt32 aCurSelfProgress,
  PRInt32 aMaxSelfProgress,
  PRInt32 aCurTotalProgress,
  PRInt32 aMaxTotalProgress
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> representing the tab for which updated progress information is being provided.</dd> <dt><code>aWebProgress</code></dt> <dd>The progress instance responsible for handling the events.</dd> <dt><code>aRequest</code></dt> <dd>The {{ interface("nsIRequest") }} object representing the associated request.</dd> <dt><code>aCurSelfProgress</code></dt> <dd>The current progress for the request indicated by the <code>request</code> parameter.</dd> <dt><code>aMaxSelfProgress</code></dt> <dd>The value representing 100% complete for the request indicated by the <code>request</code> parameter.</dd> <dt><code>aCurTotalProgress</code></dt> <dd>The current progress for all requests associated with <code>webProgress</code>.</dd> <dt><code>aMaxTotalProgress</code></dt> <dd>The total progress for all requests associated with <code>webProgress</code>.</dd>
</dl>
<h3>onSecurityChange</h3>
<p>Notification called for security progress. This method will be called on security transitions (eg HTTP -&gt; HTTPS, HTTPS -&gt; HTTP, FOO -&gt; HTTPS) and after document load completion. It might also be called if an error occurs during network loading.</p>
<div class="note"><strong>Note:</strong> These notifications will only occur if a security package is installed.</div>
<pre>void onSecurityChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  unsigned long aState
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> that fired the notification.</dd> <dt><code>aW</code><code>ebProgress</code></dt> <dd>The <code><a href="../../../../en/nsIWebProgress" rel="internal">nsIWebProgress</a></code> instance that fired the notification.</dd> <dt><code>aRequest</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/NsIRequest" title="en/NsIRequest">nsIRequest</a></code> that has new security state.</dd> <dt><code>aState</code></dt> <dd>A value composed of the <a class="internal" href="/en/XPCOM_Interface_Reference/nsIWebProgressListener#Security_Strength_Flags" title="en/nsIWebProgressListener#Security Strength Flags">Security State Flags</a> and the <a href="#Security_Strength_Flags">Security Strength Flags</a> described in the documentation for {{ interface("nsIWebProgressListener") }}.</dd>
</dl>
<h3>onStateChange</h3>
<p>Notification indicating the state has changed for one of the requests associated with <code>aWebProgress</code>.</p>
<pre>void onStateChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  unsigned long aStateFlags,
  nsresult aStatus
);
</pre>
<h6>Parameters</h6>
<dl> <dt> </dt><dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> that fired the notification.</dd> <dt><code>aWebProgress</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/nsIWebProgress" title="en/nsIWebProgress">nsIWebProgress</a></code> instance that fired the notification.</dd> <dt><code>aRequest</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/NsIRequest" title="en/NsIRequest">nsIRequest</a></code> that has changed state. This parameter may be <code>null</code>. <em>Need more information on what NULL means.</em></dd> <dt><code>aStateFlags</code></dt> <dd>Flags indicating the new state. This value is a combination of one of the <a class="internal" href="/en/XPCOM_Interface_Reference/nsIWebProgressListener#State_Transition_Flags" title="en/nsIWebProgressListener#State Transition Flags">State Transition Flags</a> and one or more of the <a class="internal" href="/en/XPCOM_Interface_Reference/nsIWebProgressListener#State_Type_Flags" title="en/nsIWebProgressListener#State Type Flags">State Type Flags</a> defined in the {{ interface("nsIWebProgressListener") }} documentation. Any undefined bits are reserved for future use.</dd> <dt><code>aStatus</code></dt> <dd>Error status code associated with the state change; this indicates whether or not the request was successful. This parameter should be ignored unless <code>aStateFlags</code> includes the <code>STATE_STOP</code> bit.</dd>
</dl>
<div class="note"><strong>NOTE</strong>: <code>aStatus</code> may be a success code even for server generated errors, such as the HTTP <code><a href="/en/HTTP/HTTP_response_codes#404" title="https://developer.mozilla.org/en/HTTP/HTTP_response_codes#404">404 File Not Found</a></code> error. In such cases, the request itself should be queried for extended error information (e.g., for HTTP requests see <code><a href="/en/XPCOM_Interface_Reference/nsIHttpChannel" title="en/nsIHttpChannel">nsIHttpChannel</a></code>).</div>
<h3>onStatusChange</h3>
<p>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).</p>
<pre>void onStatusChange(
  nsIDOMXULElement aBrowser,
  nsIWebProgress aWebProgress,
  nsIRequest aRequest,
  nsresult aStatus,
  PRUnichar *aMessage
);</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> that fired the notification.</dd> <dt><code>aWebProgress</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/nsIWebProgress" title="en/nsIWebProgress">nsIWebProgress</a></code> instance that fired the notification.</dd> <dt><code>aRequest</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/NsIRequest" title="en/NsIRequest">nsIRequest</a></code> that has new status.</dd> <dt><code>aStatus</code></dt> <dd>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. <div class="note"><strong>Note:</strong> Some status values are defined by <code><a href="/en/XPCOM_Interface_Reference/nsITransport" title="en/nsITransport">nsITransport</a></code> and <code><a href="/en/XPCOM_Interface_Reference/nsISocketTransport" title="en/nsISocketTransport">nsISocketTransport</a></code>.</div> </dd> <dt><code>aMessage</code></dt> <dd>Localized text corresponding to <code>aStatus</code>.</dd>
</dl>
<h3>onRefreshAttempted</h3>
<p>Notification that a refresh or redirect has been requested in aWebProgress for example, via a &lt;meta http-equiv="refresh"&gt; or an HTTP Refresh: header. If any registered progress listener returns false from this method then the attempt to refresh will be blocked.</p>
<pre>boolean onRefreshAttempted(
  nsIDOMXULElement aBrowser,
  nsIWebProgress webProgress,
  nsIURI aRefreshURI,
  long aMillis,
  boolean aSameURI
);</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> that fired the notification.</dd>
</dl>
<dl> <dt><code>aWebProgress</code></dt> <dd>The <code><a href="/en/XPCOM_Interface_Reference/nsIWebProgress" title="en/nsIWebProgress">nsIWebProgress</a></code> instance that fired the notification.</dd>
</dl>
<dl> <dt><code>aRefreshURI</code></dt> <dd> <p>The new URI that aWebProgress has requested redirecting to.</p> </dd>
</dl>
<dl> <dt><code>aMillis</code></dt> <dd> <p>The delay (in milliseconds) before refresh.</p> </dd>
</dl>
<dl> <dt><code>aSameURI</code></dt> <dd> <p>True if aWebProgress is requesting a refresh of the current URI. False if aWebProgress is requesting a redirection to a different URI.</p> </dd>
</dl>
<h3>onLinkIconAvailable</h3>
<p>Notification that the site icon for a browser has been found.</p>
<pre>void onLinkIconAvailable(
  nsIDOMXULElement aBrowser,
);</pre>
<h6>Parameters</h6>
<dl> <dt><code>aBrowser</code></dt> <dd>The <a class="internal" href="/en/XUL/browser" title="En/XUL:browser">browser</a> that fired the notification.</dd>
</dl>
Revert to this revision