The Tor Browser: embedding/browser/webBrowser/nsIWebBrowser.idl@6474c204b198

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

     1 /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-

     2  *

     3  * This Source Code Form is subject to the terms of the Mozilla Public

     4  * License, v. 2.0. If a copy of the MPL was not distributed with this

     5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

     7 #include "nsISupports.idl"

     9 interface nsIInterfaceRequestor;

    10 interface nsIWebBrowserChrome;

    11 interface nsIURIContentListener;

    12 interface nsIDOMWindow;

    13 interface nsIWeakReference;

    15 /**

    16  * The nsIWebBrowser interface is implemented by web browser objects.

    17  * Embedders use this interface during initialisation to associate

    18  * the new web browser instance with the embedders chrome and

    19  * to register any listeners. The interface may also be used at runtime

    20  * to obtain the content DOM window and from that the rest of the DOM.

    21  */

    22 [scriptable, uuid(33e9d001-caab-4ba9-8961-54902f197202)]

    23 interface nsIWebBrowser : nsISupports

    24 {

    25     /**

    26      * Registers a listener of the type specified by the iid to receive

    27      * callbacks. The browser stores a weak reference to the listener

    28      * to avoid any circular dependencies.

    29      * Typically this method will be called to register an object

    30      * to receive <CODE>nsIWebProgressListener</CODE> or

    31      * <CODE>nsISHistoryListener</CODE> notifications in which case the

    32      * the IID is that of the interface.

    33      *

    34      * @param aListener The listener to be added.

    35      * @param aIID      The IID of the interface that will be called

    36      *                  on the listener as appropriate.

    37      * @return          <CODE>NS_OK</CODE> for successful registration;

    38      *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not

    39      *                  supposed to be registered using this method;

    40      *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not

    41      *                  expose the interface specified by the IID, or some

    42      *                  other internal error occurred.

    43      *

    44      * @see removeWebBrowserListener

    45      * @see nsIWeakReference

    46      * @see nsIWebProgressListener

    47      * @see nsISHistoryListener

    48      *

    49      * @return <CODE>NS_OK</CODE>, listener was successfully added;

    50      *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was

    51      *         invalid or the object did not implement the interface

    52      *         specified by the IID.

    53      */

    54     void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

    56     /**

    57      * Removes a previously registered listener.

    58      *

    59      * @param aListener The listener to be removed.

    60      * @param aIID      The IID of the interface on the listener that will

    61      *                  no longer be called.

    62      *

    63      * @return <CODE>NS_OK</CODE>, listener was successfully removed;

    64      *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or

    65      *         the object did not implement the interface specified by the IID.

    66      *

    67      * @see addWebBrowserListener

    68      * @see nsIWeakReference

    69      */

    70     void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);

    72     /**

    73      * The chrome object associated with the browser instance. The embedder

    74      * must create one chrome object for <I>each</I> browser object

    75      * that is instantiated. The embedder must associate the two by setting

    76      * this property to point to the chrome object before creating the browser

    77      * window via the browser's <CODE>nsIBaseWindow</CODE> interface.

    78      *

    79      * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.

    80      *

    81      * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,

    82      * <CODE>nsIWebBrowserChromeFocus</CODE>,

    83      * <CODE>nsIContextMenuListener</CODE> and

    84      * <CODE>nsITooltipListener</CODE> to receive additional notifications

    85      * from the browser object.

    86      *

    87      * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE>

    88      * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and

    89      * <CODE>removeWebBrowserListener</CODE> to register a progress listener

    90      * object. If the implementation does this, it must also implement

    91      * <CODE>nsIWeakReference</CODE>.

    92      *

    93      * @note The implementation should not refcount the supplied chrome

    94      *       object; it should assume that a non <CODE>nullptr</CODE> value is

    95      *       always valid. The embedder must explicitly set this value back

    96      *       to nullptr if the chrome object is destroyed before the browser

    97      *       object.

    98      *

    99      * @see nsIBaseWindow

   100      * @see nsIWebBrowserChrome

   101      * @see nsIEmbeddingSiteWindow

   102      * @see nsIInterfaceRequestor

   103      * @see nsIWebBrowserChromeFocus

   104      * @see nsIContextMenuListener

   105      * @see nsITooltipListener

   106      * @see nsIWeakReference

   107      * @see nsIWebProgressListener

   108      */

   109     attribute nsIWebBrowserChrome containerWindow;

   111     /**

   112      * URI content listener parent. The embedder may set this property to

   113      * their own implementation if they intend to override or prevent

   114      * how certain kinds of content are loaded.

   115      *

   116      * @note If this attribute is set to an object that implements

   117      *       nsISupportsWeakReference, the implementation should get the

   118      *       nsIWeakReference and hold that.  Otherwise, the implementation

   119      *       should not refcount this interface; it should assume that a non

   120      *       null value is always valid.  In that case, the embedder should

   121      *       explicitly set this value back to null if the parent content

   122      *       listener is destroyed before the browser object.

   123      *

   124      * @see nsIURIContentListener

   125      */

   126     attribute nsIURIContentListener parentURIContentListener;

   128     /**

   129      * The top-level DOM window. The embedder may walk the entire

   130      * DOM starting from this value.

   131      *

   132      * @see nsIDOMWindow

   133      */

   134     readonly attribute nsIDOMWindow contentDOMWindow;

   136     /**

   137      * Whether this web browser is active. Active means that it's visible

   138      * enough that we want to avoid certain optimizations like discarding

   139      * decoded image data and throttling the refresh driver. In Firefox,

   140      * this corresponds to the visible tab.

   141      *

   142      * Defaults to true. For optimal performance, set it to false when

   143      * appropriate.

   144      */

   145     attribute boolean isActive;

   146 };

The Tor Browser / file revision