gecko-dev/embedding/base/nsIWindowProvider.idl

103 lines
5.0 KiB
Plaintext

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