PageRenderTime 83ms CodeModel.GetById 40ms app.highlight 2ms RepoModel.GetById 38ms app.codeStats 0ms

/gecko_sdk/idl/nsIWebProgress.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 178 lines | 23 code | 10 blank | 145 comment | 0 complexity | 5364357c34bc7d8af0b918fcc871cfef MD5 | raw file
  1/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2 *
  3 * ***** BEGIN LICENSE BLOCK *****
  4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5 *
  6 * The contents of this file are subject to the Mozilla Public License Version
  7 * 1.1 (the "License"); you may not use this file except in compliance with
  8 * the License. You may obtain a copy of the License at
  9 * http://www.mozilla.org/MPL/
 10 *
 11 * Software distributed under the License is distributed on an "AS IS" basis,
 12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 13 * for the specific language governing rights and limitations under the
 14 * License.
 15 *
 16 * The Original Code is the Mozilla browser.
 17 *
 18 * The Initial Developer of the Original Code is
 19 * Netscape Communications, Inc.
 20 * Portions created by the Initial Developer are Copyright (C) 1999
 21 * the Initial Developer. All Rights Reserved.
 22 *
 23 * Contributor(s):
 24 *   Travis Bogard <travis@netscape.com>
 25 *   Darin Fisher <darin@meer.net>
 26 *   Mark Pilgrim <pilgrim@gmail.com>
 27 *
 28 * Alternatively, the contents of this file may be used under the terms of
 29 * either of the GNU General Public License Version 2 or later (the "GPL"),
 30 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 31 * in which case the provisions of the GPL or the LGPL are applicable instead
 32 * of those above. If you wish to allow use of your version of this file only
 33 * under the terms of either the GPL or the LGPL, and not to allow others to
 34 * use your version of this file under the terms of the MPL, indicate your
 35 * decision by deleting the provisions above and replace them with the notice
 36 * and other provisions required by the GPL or the LGPL. If you do not delete
 37 * the provisions above, a recipient may use your version of this file under
 38 * the terms of any one of the MPL, the GPL or the LGPL.
 39 *
 40 * ***** END LICENSE BLOCK ***** */
 41
 42#include "nsISupports.idl"
 43
 44interface nsIDOMWindow;
 45interface nsIWebProgressListener;
 46
 47/**
 48 * The nsIWebProgress interface is used to add or remove nsIWebProgressListener
 49 * instances to observe the loading of asynchronous requests (usually in the
 50 * context of a DOM window).
 51 *
 52 * nsIWebProgress instances may be arranged in a parent-child configuration,
 53 * corresponding to the parent-child configuration of their respective DOM
 54 * windows.  However, in some cases a nsIWebProgress instance may not have an
 55 * associated DOM window.  The parent-child relationship of nsIWebProgress
 56 * instances is not made explicit by this interface, but the relationship may
 57 * exist in some implementations.
 58 *
 59 * A nsIWebProgressListener instance receives notifications for the
 60 * nsIWebProgress instance to which it added itself, and it may also receive
 61 * notifications from any nsIWebProgress instances that are children of that
 62 * nsIWebProgress instance.
 63 *
 64 * @status FROZEN
 65 */
 66[scriptable, uuid(570F39D0-EFD0-11d3-B093-00A024FFC08C)]
 67interface nsIWebProgress : nsISupports
 68{
 69  /**
 70   * The following flags may be combined to form the aNotifyMask parameter for
 71   * the addProgressListener method.  They limit the set of events that are
 72   * delivered to an nsIWebProgressListener instance.
 73   */ 
 74
 75  /**
 76   * These flags indicate the state transistions to observe, corresponding to
 77   * nsIWebProgressListener::onStateChange.
 78   *
 79   * NOTIFY_STATE_REQUEST
 80   *   Only receive the onStateChange event if the aStateFlags parameter
 81   *   includes nsIWebProgressListener::STATE_IS_REQUEST.
 82   *   
 83   * NOTIFY_STATE_DOCUMENT
 84   *   Only receive the onStateChange event if the aStateFlags parameter
 85   *   includes nsIWebProgressListener::STATE_IS_DOCUMENT.
 86   *
 87   * NOTIFY_STATE_NETWORK
 88   *   Only receive the onStateChange event if the aStateFlags parameter
 89   *   includes nsIWebProgressListener::STATE_IS_NETWORK.
 90   *
 91   * NOTIFY_STATE_WINDOW
 92   *   Only receive the onStateChange event if the aStateFlags parameter
 93   *   includes nsIWebProgressListener::STATE_IS_WINDOW.
 94   *
 95   * NOTIFY_STATE_ALL
 96   *   Receive all onStateChange events.
 97   */
 98  const unsigned long NOTIFY_STATE_REQUEST  = 0x00000001;
 99  const unsigned long NOTIFY_STATE_DOCUMENT = 0x00000002;
100  const unsigned long NOTIFY_STATE_NETWORK  = 0x00000004;
101  const unsigned long NOTIFY_STATE_WINDOW   = 0x00000008;
102  const unsigned long NOTIFY_STATE_ALL      = 0x0000000f;
103
104  /**
105   * These flags indicate the other events to observe, corresponding to the
106   * other four methods defined on nsIWebProgressListener.
107   *
108   * NOTIFY_PROGRESS
109   *   Receive onProgressChange events.
110   *
111   * NOTIFY_STATUS
112   *   Receive onStatusChange events.
113   *
114   * NOTIFY_SECURITY
115   *   Receive onSecurityChange events.
116   *
117   * NOTIFY_LOCATION
118   *   Receive onLocationChange events.
119   *
120   * NOTIFY_REFRESH
121   *   Receive onRefreshAttempted events.
122   *   This is defined on nsIWebProgressListener2.
123   */
124  const unsigned long NOTIFY_PROGRESS       = 0x00000010;
125  const unsigned long NOTIFY_STATUS         = 0x00000020;
126  const unsigned long NOTIFY_SECURITY       = 0x00000040;
127  const unsigned long NOTIFY_LOCATION       = 0x00000080;
128  const unsigned long NOTIFY_REFRESH        = 0x00000100;
129
130  /**
131   * This flag enables all notifications.
132   */
133  const unsigned long NOTIFY_ALL            = 0x000001ff;
134
135  /**
136   * Registers a listener to receive web progress events.
137   *
138   * @param aListener
139   *        The listener interface to be called when a progress event occurs.
140   *        This object must also implement nsISupportsWeakReference.
141   * @param aNotifyMask
142   *        The types of notifications to receive.
143   *
144   * @throw NS_ERROR_INVALID_ARG
145   *        Indicates that aListener was either null or that it does not
146   *        support weak references.
147   * @throw NS_ERROR_FAILURE
148   *        Indicates that aListener was already registered.
149   */
150  void addProgressListener(in nsIWebProgressListener aListener,
151                           in unsigned long aNotifyMask);
152
153  /**
154   * Removes a previously registered listener of progress events.
155   *
156   * @param aListener
157   *        The listener interface previously registered with a call to
158   *        addProgressListener.
159   *
160   * @throw NS_ERROR_FAILURE
161   *        Indicates that aListener was not registered.
162   */
163  void removeProgressListener(in nsIWebProgressListener aListener);
164
165  /**
166   * The DOM window associated with this nsIWebProgress instance.
167   *
168   * @throw NS_ERROR_FAILURE
169   *        Indicates that there is no associated DOM window.
170   */
171  readonly attribute nsIDOMWindow DOMWindow;
172  
173  /**
174   * Indicates whether or not a document is currently being loaded
175   * in the context of this nsIWebProgress instance.
176   */
177  readonly attribute PRBool isLoadingDocument;
178};