Version 1.8 of gecko-sdk. Downloaded from here:...

gecko-sdk/idl/nsIWebBrowser.idl

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