| /* -*- 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; |
| }; |
