embedding/nsIWindowProvider.idl

   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/. */
   5
   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  */
  13
  14 #include "nsISupports.idl"
  15
  16 interface nsIDOMWindow;
  17 interface nsIURI;
  18
  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.
  81
  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 };