embedding/browser/webBrowser/nsIWebBrowser.idl

   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  *
  26  * Alternatively, the contents of this file may be used under the terms of
  27  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29  * in which case the provisions of the GPL or the LGPL are applicable instead
  30  * of those above. If you wish to allow use of your version of this file only
  31  * under the terms of either the GPL or the LGPL, and not to allow others to
  32  * use your version of this file under the terms of the MPL, indicate your
  33  * decision by deleting the provisions above and replace them with the notice
  34  * and other provisions required by the GPL or the LGPL. If you do not delete
  35  * the provisions above, a recipient may use your version of this file under
  36  * the terms of any one of the MPL, the GPL or the LGPL.
  37  *
  38  * ***** END LICENSE BLOCK ***** */
  39
  40 #include "nsISupports.idl"
  41
  42 interface nsIInterfaceRequestor;
  43 interface nsIWebBrowserChrome;
  44 interface nsIURIContentListener;
  45 interface nsIDOMWindow;
  46 interface nsIWeakReference;
  47
  48 /**
  49  * The nsIWebBrowser interface is implemented by web browser objects.
  50  * Embedders use this interface during initialisation to associate
  51  * the new web browser instance with the embedders chrome and
  52  * to register any listeners. The interface may also be used at runtime
  53  * to obtain the content DOM window and from that the rest of the DOM.
  54  *
  55  * @status FROZEN
  56  */
  57 [scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)]
  58 interface nsIWebBrowser : nsISupports
  59 {
  60     /**
  61      * Registers a listener of the type specified by the iid to receive
  62      * callbacks. The browser stores a weak reference to the listener
  63      * to avoid any circular dependencies.
  64      * Typically this method will be called to register an object
  65      * to receive <CODE>nsIWebProgressListener</CODE> or
  66      * <CODE>nsISHistoryListener</CODE> notifications in which case the
  67      * the IID is that of the interface.
  68      *
  69      * @param aListener The listener to be added.
  70      * @param aIID      The IID of the interface that will be called
  71      *                  on the listener as appropriate.
  72      * @return          <CODE>NS_OK</CODE> for successful registration;
  73      *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
  74      *                  supposed to be registered using this method;
  75      *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
  76      *                  expose the interface specified by the IID, or some
  77      *                  other internal error occurred.
  78      *
  79      * @see removeWebBrowserListener
  80      * @see nsIWeakReference
  81      * @see nsIWebProgressListener
  82      * @see nsISHistoryListener
  83      *
  84      * @return <CODE>NS_OK</CODE>, listener was successfully added;
  85      *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
  86      *         invalid or the object did not implement the interface
  87      *         specified by the IID.
  88      */
  89     void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
  90
  91     /**
  92      * Removes a previously registered listener.
  93      *
  94      * @param aListener The listener to be removed.
  95      * @param aIID      The IID of the interface on the listener that will
  96      *                  no longer be called.
  97      *
  98      * @return <CODE>NS_OK</CODE>, listener was successfully removed;
  99      *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
 100      *         the object did not implement the interface specified by the IID.
 101      *
 102      * @see addWebBrowserListener
 103      * @see nsIWeakReference
 104      */
 105     void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
 106
 107     /**
 108      * The chrome object associated with the browser instance. The embedder
 109      * must create one chrome object for <I>each</I> browser object
 110      * that is instantiated. The embedder must associate the two by setting
 111      * this property to point to the chrome object before creating the browser
 112      * window via the browser's <CODE>nsIBaseWindow</CODE> interface.
 113      *
 114      * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
 115      *
 116      * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
 117      * <CODE>nsIWebBrowserChromeFocus</CODE>,
 118      * <CODE>nsIContextMenuListener</CODE> and
 119      * <CODE>nsITooltipListener</CODE> to receive additional notifications
 120      * from the browser object.
 121      *
 122      * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE>
 123      * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
 124      * <CODE>removeWebBrowserListener</CODE> to register a progress listener
 125      * object. If the implementation does this, it must also implement
 126      * <CODE>nsIWeakReference</CODE>.
 127      *
 128      * @note The implementation should not refcount the supplied chrome
 129      *       object; it should assume that a non <CODE>nsnull</CODE> value is
 130      *       always valid. The embedder must explicitly set this value back
 131      *       to nsnull if the chrome object is destroyed before the browser
 132      *       object.
 133      *
 134      * @see nsIBaseWindow
 135      * @see nsIWebBrowserChrome
 136      * @see nsIEmbeddingSiteWindow
 137      * @see nsIInterfaceRequestor
 138      * @see nsIWebBrowserChromeFocus
 139      * @see nsIContextMenuListener
 140      * @see nsITooltipListener
 141      * @see nsIWeakReference
 142      * @see nsIWebProgressListener
 143      */
 144     attribute nsIWebBrowserChrome containerWindow;
 145
 146     /**
 147      * URI content listener parent. The embedder may set this property to
 148      * their own implementation if they intend to override or prevent
 149      * how certain kinds of content are loaded.
 150      *
 151      * @note If this attribute is set to an object that implements
 152      *       nsISupportsWeakReference, the implementation should get the
 153      *       nsIWeakReference and hold that.  Otherwise, the implementation
 154      *       should not refcount this interface; it should assume that a non
 155      *       null value is always valid.  In that case, the embedder should
 156      *       explicitly set this value back to null if the parent content
 157      *       listener is destroyed before the browser object.
 158      *
 159      * @see nsIURIContentListener
 160      */
 161     attribute nsIURIContentListener parentURIContentListener;
 162
 163     /**
 164      * The top-level DOM window. The embedder may walk the entire
 165      * DOM starting from this value.
 166      *
 167      * @see nsIDOMWindow
 168      */
 169     readonly attribute nsIDOMWindow contentDOMWindow;
 170 };