/embedding/base/nsIWindowProvider.idl

  1/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is Mozilla.org code.
 16 *
 17 * The Initial Developer of the Original Code is Mozilla.com.
 18 * Portions created by the Initial Developer are Copyright (C) 2006
 19 * the Initial Developer. All Rights Reserved.
 20 *
 21 * Contributor(s):
 22 *      Boris Zbarsky <bzbarsky@mit.edu> (Original Author)
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either the GNU General Public License Version 2 or later (the "GPL"), or
 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38/**
 39 * nsIWindowProvider is a callback interface used by Gecko when it needs to
 40 * open a new window.  This interface can be implemented by Gecko consumers who
 41 * wish to provide a custom "new window" of their own (for example by returning
 42 * a new tab, an existing window, etc) instead of just having a real new
 43 * toplevel window open.
 44 */
 45
 46#include "nsISupports.idl"
 47
 48interface nsIDOMWindow;
 49interface nsIURI;
 50
 51/**
 52 * The nsIWindowProvider interface exists so that the window watcher's default
 53 * behavior of opening a new window can be easly modified.  When the window
 54 * watcher needs to open a new window, it will first check with the
 55 * nsIWindowProvider it gets from the parent window.  If there is no provider
 56 * or the provider does not provide a window, the window watcher will proceed
 57 * to actually open a new window.
 58 */
 59[scriptable, uuid(f607bd66-08e5-4d2e-ad83-9f9f3ca17658)]
 60interface nsIWindowProvider : nsISupports
 61{
 62  /**
 63   * A method to request that this provider provide a window.  The window
 64   * returned need not to have the right name or parent set on it; setting
 65   * those is the caller's responsibility.  The provider can always return null
 66   * to have the caller create a brand-new window.
 67   *
 68   * @param aParent Must not be null.  This is the window that the caller wants
 69   *                to use as the parent for the new window.  Generally,
 70   *                nsIWindowProvider implementors can expect to be somehow
 71   *                related to aParent; the relationship may depend on the
 72   *                nsIWindowProvider implementation.
 73   * @param aChromeFlags The chrome flags the caller will use to create a new
 74   *                      window if this provider returns null.  See
 75   *                      nsIWebBrowserChrome for the possible values of this
 76   *                      field.
 77   * @param aPositionSpecified Whether the attempt to create a window is trying
 78   *                           to specify a position for the new window.
 79   * @param aSizeSpecified Whether the attempt to create a window is trying to
 80   *                       specify a size for the new window.
 81   * @param aURI The URI to be loaded in the new window.  The nsIWindowProvider
 82   *             implementation MUST NOT load this URI in the window it
 83   *             returns.  This URI is provided solely to help the
 84   *             nsIWindowProvider implementation make decisions; the caller
 85   *             will handle loading the URI in the window returned if
 86   *             provideWindow returns a window.  Note that the URI may be null
 87   *             if the load cannot be represented by a single URI (e.g. if
 88   *             the load has extra load flags, POST data, etc).
 89   * @param aName The name of the window being opened.  Setting the name on the
 90   *              return value of provideWindow will be handled by the caller;
 91   *              aName is provided solely to help the nsIWindowProvider
 92   *              implementation make decisions.
 93   * @param aFeatures The feature string for the window being opened.  This may
 94   *                  be empty.  The nsIWindowProvider implementation is
 95   *                  allowed to apply the feature string to the window it
 96   *                  returns in any way it sees fit.  See the nsIWindowWatcher
 97   *                  interface for details on feature strings.
 98   * @param aWindowIsNew [out] Whether the window being returned was just
 99   *                           created by the window provider implementation.
100   *                           This can be used by callers to keep track of which
101   *                           windows were opened by the user as opposed to
102   *                           being opened programmatically.  This should be set
103   *                           to false if the window being returned existed
104   *                           before the provideWindow() call.  The value of this
105   *                           out parameter is meaningless if provideWindow()
106   *                           returns null.
107   * @return A window the caller should use or null if the caller should just
108   *         create a new window.  The returned window may be newly opened by
109   *         the nsIWindowProvider implementation or may be a window that
110   *         already existed.
111   *
112   * @see nsIWindowWatcher for more information on aFeatures.
113   * @see nsIWebBrowserChrome for more information on aChromeFlags.
114   */
115  nsIDOMWindow provideWindow(in nsIDOMWindow aParent,
116                             in unsigned long aChromeFlags,
117                             in boolean aCalledFromJS,
118                             in boolean aPositionSpecified,
119                             in boolean aSizeSpecified,
120                             in nsIURI aURI,
121                             in AString aName,
122                             in AUTF8String aFeatures,
123                             out boolean aWindowIsNew);
124};