toolkit/components/windowcreator/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 %{ C++
  17 class nsDocShellLoadState;
  18 %}
  19
  20 webidl BrowsingContext;
  21 interface mozIDOMWindowProxy;
  22 interface nsIURI;
  23 interface nsIOpenWindowInfo;
  24 native nsDocShellLoadStatePtr(nsDocShellLoadState*);
  25
  26 /**
  27  * The nsIWindowProvider interface exists so that the window watcher's default
  28  * behavior of opening a new window can be easly modified.  When the window
  29  * watcher needs to open a new window, it will first check with the
  30  * nsIWindowProvider it gets from the parent window.  If there is no provider
  31  * or the provider does not provide a window, the window watcher will proceed
  32  * to actually open a new window.
  33  */
  34 [scriptable, uuid(e97a3830-15ef-499b-8372-c22d128091c1)]
  35 interface nsIWindowProvider : nsISupports
  36 {
  37   /**
  38    * A method to request that this provider provide a window.  The window
  39    * returned need not to have the right name or parent set on it; setting
  40    * those is the caller's responsibility.  The provider can always return null
  41    * to have the caller create a brand-new window.
  42    *
  43    * @param aOpenWindowInfo  Must not be null.  This is the information the
  44    *                         caller wants to be used to construct the new window.
  45    *
  46    * @param aChromeFlags The chrome flags the caller will use to create a new
  47    *        window if this provider returns null.  See nsIWebBrowserChrome for
  48    *        the possible values of this field.
  49    *
  50    * @param aURI The URI to be loaded in the new window (may be NULL).  The
  51    *        nsIWindowProvider implementation must not load this URI into the
  52    *        window it returns.  This URI is provided solely to help the
  53    *        nsIWindowProvider implementation make decisions; the caller will
  54    *        handle loading the URI in the window returned if provideWindow
  55    *        returns a window.
  56    *
  57    *        When making decisions based on aURI, note that even when it's not
  58    *        null, aURI may not represent all relevant information about the
  59    *        load.  For example, the load may have extra load flags, POST data,
  60    *        etc.
  61    *
  62    * @param aName The name of the window being opened.  Setting the name on the
  63    *        return value of provideWindow will be handled by the caller; aName
  64    *        is provided solely to help the nsIWindowProvider implementation
  65    *        make decisions.
  66    *
  67    * @param aFeatures The feature string for the window being opened.  This may
  68    *        be empty.  The nsIWindowProvider implementation is allowed to apply
  69    *        the feature string to the window it returns in any way it sees fit.
  70    *        See the nsIWindowWatcher interface for details on feature strings.
  71    *
  72    * @param aIsPopupRequested  True if this window is opened by window.open
  73    *        with requesting a popup window.  This doesn't necessarily mean
  74    *        whether the actual window is shown as minimal popup or not.
  75    *
  76    * @param aLoadState Specify setup information of the load in the new window
  77    *
  78    * @param aWindowIsNew [out] Whether the window being returned was just
  79    *        created by the window provider implementation.  This can be used by
  80    *        callers to keep track of which windows were opened by the user as
  81    *        opposed to being opened programmatically.  This should be set to
  82    *        false if the window being returned existed before the
  83    *        provideWindow() call.  The value of this out parameter is
  84    *        meaningless if provideWindow() returns null.
  85    *
  86    * @return A window the caller should use or null if the caller should just
  87    *         create a new window.  The returned window may be newly opened by
  88    *         the nsIWindowProvider implementation or may be a window that
  89    *         already existed.
  90    *
  91    * @throw NS_ERROR_ABORT if the caller should cease its attempt to open a new
  92    *                       window.
  93    *
  94    * @see nsIWindowWatcher for more information on aFeatures.
  95    * @see nsIWebBrowserChrome for more information on aChromeFlags.
  96    */
  97   [noscript]
  98   BrowsingContext provideWindow(in nsIOpenWindowInfo aOpenWindowInfo,
  99                                 in unsigned long aChromeFlags,
 100                                 in boolean aCalledFromJS,
 101                                 in nsIURI aURI,
 102                                 in AString aName,
 103                                 in AUTF8String aFeatures,
 104                                 in boolean aForceNoOpener,
 105                                 in boolean aForceNoReferrer,
 106                                 in boolean aIsPopupRequested,
 107                                 in nsDocShellLoadStatePtr aLoadState,
 108                                 out boolean aWindowIsNew);
 109 };