nsIWebProgress

From MDC

« XPCOM API Reference

Contents 1 Summary 2 Interface Code 3 Constants 4 Methods 4.1 addProgressListener 4.1.1 Parameters 4.1.2 Exceptions 4.2 removeProgressListener 4.2.1 Parameters 4.2.2 Exceptions 5 Attributes 5.1 DOMWindow 5.1.1 Exceptions 5.2 isLoadingDocument

[edit] Summary

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.

nsIWebProgress is defined in uriloader/base/nsIWebProgress.idl. It is scriptable and has been frozen since Gecko 1.8.0.

[edit] Interface Code

[scriptable, uuid(570F39D0-EFD0-11d3-B093-00A024FFC08C)]
interface nsIWebProgress : nsISupports
{
  const unsigned long NOTIFY_STATE_REQUEST  = 0x00000001;
  const unsigned long NOTIFY_STATE_DOCUMENT = 0x00000002;
  const unsigned long NOTIFY_STATE_NETWORK  = 0x00000004;
  const unsigned long NOTIFY_STATE_WINDOW   = 0x00000008;
  const unsigned long NOTIFY_STATE_ALL      = 0x0000000f;

  const unsigned long NOTIFY_PROGRESS       = 0x00000010;
  const unsigned long NOTIFY_STATUS         = 0x00000020;
  const unsigned long NOTIFY_SECURITY       = 0x00000040;
  const unsigned long NOTIFY_LOCATION       = 0x00000080;

  const unsigned long NOTIFY_ALL            = 0x000000ff;

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

  void removeProgressListener(in nsIWebProgressListener aListener);

  readonly attribute nsIDOMWindow DOMWindow;

  readonly attribute PRBool isLoadingDocument;
};

[edit] Constants

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

NOTIFY_STATE_REQUEST

Only receive the onStateChange event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_REQUEST.

NOTIFY_STATE_DOCUMENT

Only receive the onStateChange event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_DOCUMENT.

NOTIFY_STATE_NETWORK

Only receive the onStateChange event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_NETWORK.

NOTIFY_STATE_WINDOW

Only receive the onStateChange event if the aStateFlags parameter includes nsIWebProgressListener::STATE_IS_WINDOW.

NOTIFY_STATE_ALL

Receive all onStateChange events.

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

NOTIFY_PROGRESS

Receive onProgressChange events.

NOTIFY_STATUS

Receive onStatusChange events.

NOTIFY_SECURITY

Receive onSecurityChange events.

NOTIFY_LOCATION

Receive onLocationChange events.

[edit] Methods

[edit] addProgressListener

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

Registers a listener to receive web progress events.

[edit] 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.

[edit] Exceptions

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.

[edit] removeProgressListener

void removeProgressListener(in nsIWebProgressListener aListener);

[edit] Parameters

aListener

The listener interface previously registered with a call to addProgressListener.

[edit] Exceptions

NS_ERROR_FAILURE

Indicates that aListener was not registered.

[edit] Attributes

[edit] DOMWindow

readonly attribute nsIDOMWindow DOMWindow;

The DOM window associated with this nsIWebProgress instance.

[edit] Exceptions

NS_ERROR_FAILURE

Indicates that there is no associated DOM window.

[edit] isLoadingDocument

readonly attribute PRBool isLoadingDocument;

Indicates whether or not a document is currently being loaded in the context of this nsIWebProgress instance.