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.

uriloader/base/nsIWebProgress.idlScriptable

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.