nsIWebProgress

The nsIWebProgress interface is used to add or remove nsIWebProgressListener instances to observe the loading of asynchronous requests (usually in the context of a DOM window).

nsIWebProgress instances may be arranged in a parent-child configuration, corresponding to the parent-child configuration of their respective DOM windows. However, in some cases a nsIWebProgress instance may not have an associated DOM window. The parent-child relationship of nsIWebProgress instances is not made explicit by this interface, but the relationship may exist in some implementations.

A nsIWebProgressListener instance receives notifications for the nsIWebProgress instance to which it added itself, and it may also receive notifications from any nsIWebProgress instances that are children of that nsIWebProgress instance.

Please add a summary to this article.
  Last changed in Gecko 1.8.0

Inherits from: nsISupports

Method overview

void addProgressListener(in nsIWebProgressListener aListener, in unsigned long aNotifyMask);
void removeProgressListener(in nsIWebProgressListener aListener);

Attributes

Attribute Type Description
DOMWindow nsIDOMWindow The DOM window associated with this nsIWebProgress instance. Read only.
Exceptions thrown
NS_ERROR_FAILURE
Indicates that there is no associated DOM window.
isLoadingDocument PRBool Indicates whether or not a document is currently being loaded in the context of this nsIWebProgress instance. Read only.

Constants

The following flags may be combined to form the aNotifyMask parameter for the addProgressListener() method. They limit the set of events that are delivered to an nsIWebProgressListener instance.

These flags indicate the state transistions to observe, corresponding to nsIWebProgressListener.onStateChange().

Constant Value Description
NOTIFY_STATE_REQUEST 0x00000001 Only receive the nsIWebProgressListener.onStateChange() event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_REQUEST.
NOTIFY_STATE_DOCUMENT 0x00000002 Only receive the nsIWebProgressListener.onStateChange() event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_DOCUMENT.
NOTIFY_STATE_NETWORK 0x00000004 Only receive the nsIWebProgressListener.onStateChange() event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_NETWORK.
NOTIFY_STATE_WINDOW 0x00000008 Only receive the nsIWebProgressListener.onStateChange() event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_WINDOW.
NOTIFY_STATE_ALL 0x0000000f Receive all nsIWebProgressListener.onStateChange() events.

These flags indicate the other events to observe, corresponding to the other four methods defined on nsIWebProgressListener.

Constant Value Description
NOTIFY_PROGRESS 0x00000010 Receive nsIWebProgressListener.onProgressChange() events.
NOTIFY_STATUS 0x00000020 Receive nsIWebProgressListener.onStatusChange() events.
NOTIFY_SECURITY 0x00000040 Receive nsIWebProgressListener.onSecurityChange() events.
NOTIFY_LOCATION 0x00000080 Receive nsIWebProgressListener.onLocationChange() events.
NOTIFY_REFRESH 0x00000100 Receive nsIWebProgressListener2.onRefreshAttempted() events. This is defined on nsIWebProgressListener2.
NOTIFY_ALL 0x000000ff <= Gecko 1.8.1
0x000001ff > Gecko 1.8.1		 This flag enables all notifications.

Methods

addProgressListener()

Registers a listener to receive web progress events.

void addProgressListener(
  in nsIWebProgressListener aListener,
  in unsigned long aNotifyMask
);
Parameters
aListener
The listener interface to be called when a progress event occurs. This object must also implement nsISupportsWeakReference.
aNotifyMask
The types of notifications to receive.
Exceptions thrown
NS_ERROR_INVALID_ARG
Indicates that aListener was either null or that it does not support weak references.
NS_ERROR_FAILURE
Indicates that aListener was already registered.

removeProgressListener()

Removes a previously registered listener of progress events.

void removeProgressListener(
  in nsIWebProgressListener aListener
);
Parameters
aListener
The listener interface previously registered with a call to addProgressListener().
Exceptions thrown
NS_ERROR_FAILURE
Indicates that aListener was not registered.

Document Tags and Contributors

Tags: 
 Contributors to this page: Sheppy, trevorh, Aengus, DimaVidmich, Mook, Ted_Mielczarek, Cheba, Nickolay
 Last updated by: Sheppy,