michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /** michael@0: * nsIWindowProvider is a callback interface used by Gecko when it needs to michael@0: * open a new window. This interface can be implemented by Gecko consumers who michael@0: * wish to provide a custom "new window" of their own (for example by returning michael@0: * a new tab, an existing window, etc) instead of just having a real new michael@0: * toplevel window open. michael@0: */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIDOMWindow; michael@0: interface nsIURI; michael@0: michael@0: /** michael@0: * The nsIWindowProvider interface exists so that the window watcher's default michael@0: * behavior of opening a new window can be easly modified. When the window michael@0: * watcher needs to open a new window, it will first check with the michael@0: * nsIWindowProvider it gets from the parent window. If there is no provider michael@0: * or the provider does not provide a window, the window watcher will proceed michael@0: * to actually open a new window. michael@0: */ michael@0: [scriptable, uuid(f607bd66-08e5-4d2e-ad83-9f9f3ca17658)] michael@0: interface nsIWindowProvider : nsISupports michael@0: { michael@0: /** michael@0: * A method to request that this provider provide a window. The window michael@0: * returned need not to have the right name or parent set on it; setting michael@0: * those is the caller's responsibility. The provider can always return null michael@0: * to have the caller create a brand-new window. michael@0: * michael@0: * @param aParent Must not be null. This is the window that the caller wants michael@0: * to use as the parent for the new window. Generally, michael@0: * nsIWindowProvider implementors can expect to be somehow related to michael@0: * aParent; the relationship may depend on the nsIWindowProvider michael@0: * implementation. michael@0: * michael@0: * @param aChromeFlags The chrome flags the caller will use to create a new michael@0: * window if this provider returns null. See nsIWebBrowserChrome for michael@0: * the possible values of this field. michael@0: * michael@0: * @param aPositionSpecified Whether the attempt to create a window is trying michael@0: * to specify a position for the new window. michael@0: * michael@0: * @param aSizeSpecified Whether the attempt to create a window is trying to michael@0: * specify a size for the new window. michael@0: * michael@0: * @param aURI The URI to be loaded in the new window (may be NULL). The michael@0: * nsIWindowProvider implementation must not load this URI into the michael@0: * window it returns. This URI is provided solely to help the michael@0: * nsIWindowProvider implementation make decisions; the caller will michael@0: * handle loading the URI in the window returned if provideWindow michael@0: * returns a window. michael@0: * michael@0: * When making decisions based on aURI, note that even when it's not michael@0: * null, aURI may not represent all relevant information about the michael@0: * load. For example, the load may have extra load flags, POST data, michael@0: * etc. michael@0: * michael@0: * @param aName The name of the window being opened. Setting the name on the michael@0: * return value of provideWindow will be handled by the caller; aName michael@0: * is provided solely to help the nsIWindowProvider implementation michael@0: * make decisions. michael@0: * michael@0: * @param aFeatures The feature string for the window being opened. This may michael@0: * be empty. The nsIWindowProvider implementation is allowed to apply michael@0: * the feature string to the window it returns in any way it sees fit. michael@0: * See the nsIWindowWatcher interface for details on feature strings. michael@0: * michael@0: * @param aWindowIsNew [out] Whether the window being returned was just michael@0: * created by the window provider implementation. This can be used by michael@0: * callers to keep track of which windows were opened by the user as michael@0: * opposed to being opened programmatically. This should be set to michael@0: * false if the window being returned existed before the michael@0: * provideWindow() call. The value of this out parameter is michael@0: * meaningless if provideWindow() returns null. michael@0: michael@0: * @return A window the caller should use or null if the caller should just michael@0: * create a new window. The returned window may be newly opened by michael@0: * the nsIWindowProvider implementation or may be a window that michael@0: * already existed. michael@0: * michael@0: * @throw NS_ERROR_ABORT if the caller should cease its attempt to open a new michael@0: * window. michael@0: * michael@0: * @see nsIWindowWatcher for more information on aFeatures. michael@0: * @see nsIWebBrowserChrome for more information on aChromeFlags. michael@0: */ michael@0: nsIDOMWindow provideWindow(in nsIDOMWindow aParent, michael@0: in unsigned long aChromeFlags, michael@0: in boolean aCalledFromJS, michael@0: in boolean aPositionSpecified, michael@0: in boolean aSizeSpecified, michael@0: in nsIURI aURI, michael@0: in AString aName, michael@0: in AUTF8String aFeatures, michael@0: out boolean aWindowIsNew); michael@0: };