michael@0: /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
michael@0:  *
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIInterfaceRequestor;
michael@0: interface nsIWebBrowserChrome;
michael@0: interface nsIURIContentListener;
michael@0: interface nsIDOMWindow;
michael@0: interface nsIWeakReference;
michael@0: 
michael@0: /**
michael@0:  * The nsIWebBrowser interface is implemented by web browser objects.
michael@0:  * Embedders use this interface during initialisation to associate
michael@0:  * the new web browser instance with the embedders chrome and
michael@0:  * to register any listeners. The interface may also be used at runtime
michael@0:  * to obtain the content DOM window and from that the rest of the DOM.
michael@0:  */
michael@0: [scriptable, uuid(33e9d001-caab-4ba9-8961-54902f197202)]
michael@0: interface nsIWebBrowser : nsISupports
michael@0: {
michael@0:     /**
michael@0:      * Registers a listener of the type specified by the iid to receive
michael@0:      * callbacks. The browser stores a weak reference to the listener
michael@0:      * to avoid any circular dependencies.
michael@0:      * Typically this method will be called to register an object
michael@0:      * to receive <CODE>nsIWebProgressListener</CODE> or 
michael@0:      * <CODE>nsISHistoryListener</CODE> notifications in which case the
michael@0:      * the IID is that of the interface.
michael@0:      *
michael@0:      * @param aListener The listener to be added.
michael@0:      * @param aIID      The IID of the interface that will be called
michael@0:      *                  on the listener as appropriate.
michael@0:      * @return          <CODE>NS_OK</CODE> for successful registration;
michael@0:      *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
michael@0:      *                  supposed to be registered using this method;
michael@0:      *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
michael@0:      *                  expose the interface specified by the IID, or some
michael@0:      *                  other internal error occurred.
michael@0:      *
michael@0:      * @see removeWebBrowserListener
michael@0:      * @see nsIWeakReference
michael@0:      * @see nsIWebProgressListener
michael@0:      * @see nsISHistoryListener
michael@0:      *
michael@0:      * @return <CODE>NS_OK</CODE>, listener was successfully added;
michael@0:      *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
michael@0:      *         invalid or the object did not implement the interface
michael@0:      *         specified by the IID.
michael@0:      */
michael@0:     void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
michael@0: 
michael@0:     /**
michael@0:      * Removes a previously registered listener.
michael@0:      *
michael@0:      * @param aListener The listener to be removed.
michael@0:      * @param aIID      The IID of the interface on the listener that will
michael@0:      *                  no longer be called.
michael@0:      *
michael@0:      * @return <CODE>NS_OK</CODE>, listener was successfully removed;
michael@0:      *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
michael@0:      *         the object did not implement the interface specified by the IID.
michael@0:      *
michael@0:      * @see addWebBrowserListener
michael@0:      * @see nsIWeakReference
michael@0:      */
michael@0:     void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
michael@0: 
michael@0:     /**
michael@0:      * The chrome object associated with the browser instance. The embedder
michael@0:      * must create one chrome object for <I>each</I> browser object
michael@0:      * that is instantiated. The embedder must associate the two by setting
michael@0:      * this property to point to the chrome object before creating the browser
michael@0:      * window via the browser's <CODE>nsIBaseWindow</CODE> interface. 
michael@0:      *
michael@0:      * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
michael@0:      *
michael@0:      * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
michael@0:      * <CODE>nsIWebBrowserChromeFocus</CODE>,
michael@0:      * <CODE>nsIContextMenuListener</CODE> and
michael@0:      * <CODE>nsITooltipListener</CODE> to receive additional notifications
michael@0:      * from the browser object.
michael@0:      *
michael@0:      * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE> 
michael@0:      * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
michael@0:      * <CODE>removeWebBrowserListener</CODE> to register a progress listener
michael@0:      * object. If the implementation does this, it must also implement
michael@0:      * <CODE>nsIWeakReference</CODE>.
michael@0:      * 
michael@0:      * @note The implementation should not refcount the supplied chrome
michael@0:      *       object; it should assume that a non <CODE>nullptr</CODE> value is
michael@0:      *       always valid. The embedder must explicitly set this value back
michael@0:      *       to nullptr if the chrome object is destroyed before the browser
michael@0:      *       object.
michael@0:      *
michael@0:      * @see nsIBaseWindow
michael@0:      * @see nsIWebBrowserChrome
michael@0:      * @see nsIEmbeddingSiteWindow
michael@0:      * @see nsIInterfaceRequestor
michael@0:      * @see nsIWebBrowserChromeFocus
michael@0:      * @see nsIContextMenuListener
michael@0:      * @see nsITooltipListener
michael@0:      * @see nsIWeakReference
michael@0:      * @see nsIWebProgressListener
michael@0:      */
michael@0:     attribute nsIWebBrowserChrome containerWindow;
michael@0: 
michael@0:     /**
michael@0:      * URI content listener parent. The embedder may set this property to
michael@0:      * their own implementation if they intend to override or prevent
michael@0:      * how certain kinds of content are loaded.
michael@0:      *
michael@0:      * @note If this attribute is set to an object that implements
michael@0:      *       nsISupportsWeakReference, the implementation should get the
michael@0:      *       nsIWeakReference and hold that.  Otherwise, the implementation
michael@0:      *       should not refcount this interface; it should assume that a non
michael@0:      *       null value is always valid.  In that case, the embedder should
michael@0:      *       explicitly set this value back to null if the parent content
michael@0:      *       listener is destroyed before the browser object.
michael@0:      *
michael@0:      * @see nsIURIContentListener
michael@0:      */
michael@0:     attribute nsIURIContentListener parentURIContentListener;
michael@0: 
michael@0:     /**
michael@0:      * The top-level DOM window. The embedder may walk the entire
michael@0:      * DOM starting from this value.
michael@0:      *
michael@0:      * @see nsIDOMWindow
michael@0:      */
michael@0:     readonly attribute nsIDOMWindow contentDOMWindow;
michael@0: 
michael@0:     /**
michael@0:      * Whether this web browser is active. Active means that it's visible
michael@0:      * enough that we want to avoid certain optimizations like discarding
michael@0:      * decoded image data and throttling the refresh driver. In Firefox,
michael@0:      * this corresponds to the visible tab.
michael@0:      *
michael@0:      * Defaults to true. For optimal performance, set it to false when
michael@0:      * appropriate.
michael@0:      */
michael@0:     attribute boolean isActive;
michael@0: };