/* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- * * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is the Mozilla browser. * * The Initial Developer of the Original Code is * Netscape Communications, Inc. * Portions created by the Initial Developer are Copyright (C) 1999 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Travis Bogard <travis@netscape.com> * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" interface nsIInterfaceRequestor; interface nsIWebBrowserChrome; interface nsIURIContentListener; interface nsIDOMWindow; interface nsIWeakReference; /** * The nsIWebBrowser interface is implemented by web browser objects. * Embedders use this interface during initialisation to associate * the new web browser instance with the embedders chrome and * to register any listeners. The interface may also be used at runtime * to obtain the content DOM window and from that the rest of the DOM. * * @status FROZEN */ [scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)] interface nsIWebBrowser : nsISupports { /** * Registers a listener of the type specified by the iid to receive * callbacks. The browser stores a weak reference to the listener * to avoid any circular dependencies. * Typically this method will be called to register an object * to receive <CODE>nsIWebProgressListener</CODE> or * <CODE>nsISHistoryListener</CODE> notifications in which case the * the IID is that of the interface. * * @param aListener The listener to be added. * @param aIID The IID of the interface that will be called * on the listener as appropriate. * @return <CODE>NS_OK</CODE> for successful registration; * <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not * supposed to be registered using this method; * <CODE>NS_ERROR_FAILURE</CODE> either aListener did not * expose the interface specified by the IID, or some * other internal error occurred. * * @see removeWebBrowserListener * @see nsIWeakReference * @see nsIWebProgressListener * @see nsISHistoryListener * * @return <CODE>NS_OK</CODE>, listener was successfully added; * <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was * invalid or the object did not implement the interface * specified by the IID. */ void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID); /** * Removes a previously registered listener. * * @param aListener The listener to be removed. * @param aIID The IID of the interface on the listener that will * no longer be called. * * @return <CODE>NS_OK</CODE>, listener was successfully removed; * <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or * the object did not implement the interface specified by the IID. * * @see addWebBrowserListener * @see nsIWeakReference */ void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID); /** * The chrome object associated with the browser instance. The embedder * must create one chrome object for <I>each</I> browser object * that is instantiated. The embedder must associate the two by setting * this property to point to the chrome object before creating the browser * window via the browser's <CODE>nsIBaseWindow</CODE> interface. * * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>. * * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>, * <CODE>nsIWebBrowserChromeFocus</CODE>, * <CODE>nsIContextMenuListener</CODE> and * <CODE>nsITooltipListener</CODE> to receive additional notifications * from the browser object. * * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE> * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and * <CODE>removeWebBrowserListener</CODE> to register a progress listener * object. If the implementation does this, it must also implement * <CODE>nsIWeakReference</CODE>. * * @note The implementation should not refcount the supplied chrome * object; it should assume that a non <CODE>nsnull</CODE> value is * always valid. The embedder must explicitly set this value back * to nsnull if the chrome object is destroyed before the browser * object. * * @see nsIBaseWindow * @see nsIWebBrowserChrome * @see nsIEmbeddingSiteWindow * @see nsIInterfaceRequestor * @see nsIWebBrowserChromeFocus * @see nsIContextMenuListener * @see nsITooltipListener * @see nsIWeakReference * @see nsIWebProgressListener */ attribute nsIWebBrowserChrome containerWindow; /** * URI content listener parent. The embedder may set this property to * their own implementation if they intend to override or prevent * how certain kinds of content are loaded. * * @note If this attribute is set to an object that implements * nsISupportsWeakReference, the implementation should get the * nsIWeakReference and hold that. Otherwise, the implementation * should not refcount this interface; it should assume that a non * null value is always valid. In that case, the embedder should * explicitly set this value back to null if the parent content * listener is destroyed before the browser object. * * @see nsIURIContentListener */ attribute nsIURIContentListener parentURIContentListener; /** * The top-level DOM window. The embedder may walk the entire * DOM starting from this value. * * @see nsIDOMWindow */ readonly attribute nsIDOMWindow contentDOMWindow; };