PageRenderTime 103ms CodeModel.GetById 60ms app.highlight 2ms RepoModel.GetById 38ms app.codeStats 0ms

/gecko_sdk/idl/nsIWebBrowser.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 170 lines | 15 code | 7 blank | 148 comment | 0 complexity | 77ce17c6154413e9dc5e6799ee1bcee3 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 *
 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
 42interface nsIInterfaceRequestor;
 43interface nsIWebBrowserChrome;
 44interface nsIURIContentListener;
 45interface nsIDOMWindow;
 46interface 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)]
 58interface 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};