The Tor Browser: embedding/base/nsIWindowProvider.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: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */

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

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

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

     6 /**

     7  * nsIWindowProvider is a callback interface used by Gecko when it needs to

     8  * open a new window.  This interface can be implemented by Gecko consumers who

     9  * wish to provide a custom "new window" of their own (for example by returning

    10  * a new tab, an existing window, etc) instead of just having a real new

    11  * toplevel window open.

    12  */

    14 #include "nsISupports.idl"

    16 interface nsIDOMWindow;

    17 interface nsIURI;

    19 /**

    20  * The nsIWindowProvider interface exists so that the window watcher's default

    21  * behavior of opening a new window can be easly modified.  When the window

    22  * watcher needs to open a new window, it will first check with the

    23  * nsIWindowProvider it gets from the parent window.  If there is no provider

    24  * or the provider does not provide a window, the window watcher will proceed

    25  * to actually open a new window.

    26  */

    27 [scriptable, uuid(f607bd66-08e5-4d2e-ad83-9f9f3ca17658)]

    28 interface nsIWindowProvider : nsISupports

    29 {

    30   /**

    31    * A method to request that this provider provide a window.  The window

    32    * returned need not to have the right name or parent set on it; setting

    33    * those is the caller's responsibility.  The provider can always return null

    34    * to have the caller create a brand-new window.

    35    *

    36    * @param aParent Must not be null.  This is the window that the caller wants

    37    *        to use as the parent for the new window.  Generally,

    38    *        nsIWindowProvider implementors can expect to be somehow related to

    39    *        aParent; the relationship may depend on the nsIWindowProvider

    40    *        implementation.

    41    *

    42    * @param aChromeFlags The chrome flags the caller will use to create a new

    43    *        window if this provider returns null.  See nsIWebBrowserChrome for

    44    *        the possible values of this field.

    45    *

    46    * @param aPositionSpecified Whether the attempt to create a window is trying

    47    *        to specify a position for the new window.

    48    *

    49    * @param aSizeSpecified Whether the attempt to create a window is trying to

    50    *        specify a size for the new window.

    51    *

    52    * @param aURI The URI to be loaded in the new window (may be NULL).  The

    53    *        nsIWindowProvider implementation must not load this URI into the

    54    *        window it returns.  This URI is provided solely to help the

    55    *        nsIWindowProvider implementation make decisions; the caller will

    56    *        handle loading the URI in the window returned if provideWindow

    57    *        returns a window.

    58    *

    59    *        When making decisions based on aURI, note that even when it's not

    60    *        null, aURI may not represent all relevant information about the

    61    *        load.  For example, the load may have extra load flags, POST data,

    62    *        etc.

    63    *

    64    * @param aName The name of the window being opened.  Setting the name on the

    65    *        return value of provideWindow will be handled by the caller; aName

    66    *        is provided solely to help the nsIWindowProvider implementation

    67    *        make decisions.

    68    *

    69    * @param aFeatures The feature string for the window being opened.  This may

    70    *        be empty.  The nsIWindowProvider implementation is allowed to apply

    71    *        the feature string to the window it returns in any way it sees fit.

    72    *        See the nsIWindowWatcher interface for details on feature strings.

    73    *

    74    * @param aWindowIsNew [out] Whether the window being returned was just

    75    *        created by the window provider implementation.  This can be used by

    76    *        callers to keep track of which windows were opened by the user as

    77    *        opposed to being opened programmatically.  This should be set to

    78    *        false if the window being returned existed before the

    79    *        provideWindow() call.  The value of this out parameter is

    80    *        meaningless if provideWindow() returns null.

    82    * @return A window the caller should use or null if the caller should just

    83    *         create a new window.  The returned window may be newly opened by

    84    *         the nsIWindowProvider implementation or may be a window that

    85    *         already existed.

    86    *

    87    * @throw NS_ERROR_ABORT if the caller should cease its attempt to open a new

    88    *                       window.

    89    *

    90    * @see nsIWindowWatcher for more information on aFeatures.

    91    * @see nsIWebBrowserChrome for more information on aChromeFlags.

    92    */

    93   nsIDOMWindow provideWindow(in nsIDOMWindow aParent,

    94                              in unsigned long aChromeFlags,

    95                              in boolean aCalledFromJS,

    96                              in boolean aPositionSpecified,

    97                              in boolean aSizeSpecified,

    98                              in nsIURI aURI,

    99                              in AString aName,

   100                              in AUTF8String aFeatures,

   101                              out boolean aWindowIsNew);

   102 };

The Tor Browser / file revision