1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/base/nsIWindowProvider.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,102 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +/**
1.10 + * nsIWindowProvider is a callback interface used by Gecko when it needs to
1.11 + * open a new window. This interface can be implemented by Gecko consumers who
1.12 + * wish to provide a custom "new window" of their own (for example by returning
1.13 + * a new tab, an existing window, etc) instead of just having a real new
1.14 + * toplevel window open.
1.15 + */
1.16 +
1.17 +#include "nsISupports.idl"
1.18 +
1.19 +interface nsIDOMWindow;
1.20 +interface nsIURI;
1.21 +
1.22 +/**
1.23 + * The nsIWindowProvider interface exists so that the window watcher's default
1.24 + * behavior of opening a new window can be easly modified. When the window
1.25 + * watcher needs to open a new window, it will first check with the
1.26 + * nsIWindowProvider it gets from the parent window. If there is no provider
1.27 + * or the provider does not provide a window, the window watcher will proceed
1.28 + * to actually open a new window.
1.29 + */
1.30 +[scriptable, uuid(f607bd66-08e5-4d2e-ad83-9f9f3ca17658)]
1.31 +interface nsIWindowProvider : nsISupports
1.32 +{
1.33 + /**
1.34 + * A method to request that this provider provide a window. The window
1.35 + * returned need not to have the right name or parent set on it; setting
1.36 + * those is the caller's responsibility. The provider can always return null
1.37 + * to have the caller create a brand-new window.
1.38 + *
1.39 + * @param aParent Must not be null. This is the window that the caller wants
1.40 + * to use as the parent for the new window. Generally,
1.41 + * nsIWindowProvider implementors can expect to be somehow related to
1.42 + * aParent; the relationship may depend on the nsIWindowProvider
1.43 + * implementation.
1.44 + *
1.45 + * @param aChromeFlags The chrome flags the caller will use to create a new
1.46 + * window if this provider returns null. See nsIWebBrowserChrome for
1.47 + * the possible values of this field.
1.48 + *
1.49 + * @param aPositionSpecified Whether the attempt to create a window is trying
1.50 + * to specify a position for the new window.
1.51 + *
1.52 + * @param aSizeSpecified Whether the attempt to create a window is trying to
1.53 + * specify a size for the new window.
1.54 + *
1.55 + * @param aURI The URI to be loaded in the new window (may be NULL). The
1.56 + * nsIWindowProvider implementation must not load this URI into the
1.57 + * window it returns. This URI is provided solely to help the
1.58 + * nsIWindowProvider implementation make decisions; the caller will
1.59 + * handle loading the URI in the window returned if provideWindow
1.60 + * returns a window.
1.61 + *
1.62 + * When making decisions based on aURI, note that even when it's not
1.63 + * null, aURI may not represent all relevant information about the
1.64 + * load. For example, the load may have extra load flags, POST data,
1.65 + * etc.
1.66 + *
1.67 + * @param aName The name of the window being opened. Setting the name on the
1.68 + * return value of provideWindow will be handled by the caller; aName
1.69 + * is provided solely to help the nsIWindowProvider implementation
1.70 + * make decisions.
1.71 + *
1.72 + * @param aFeatures The feature string for the window being opened. This may
1.73 + * be empty. The nsIWindowProvider implementation is allowed to apply
1.74 + * the feature string to the window it returns in any way it sees fit.
1.75 + * See the nsIWindowWatcher interface for details on feature strings.
1.76 + *
1.77 + * @param aWindowIsNew [out] Whether the window being returned was just
1.78 + * created by the window provider implementation. This can be used by
1.79 + * callers to keep track of which windows were opened by the user as
1.80 + * opposed to being opened programmatically. This should be set to
1.81 + * false if the window being returned existed before the
1.82 + * provideWindow() call. The value of this out parameter is
1.83 + * meaningless if provideWindow() returns null.
1.84 +
1.85 + * @return A window the caller should use or null if the caller should just
1.86 + * create a new window. The returned window may be newly opened by
1.87 + * the nsIWindowProvider implementation or may be a window that
1.88 + * already existed.
1.89 + *
1.90 + * @throw NS_ERROR_ABORT if the caller should cease its attempt to open a new
1.91 + * window.
1.92 + *
1.93 + * @see nsIWindowWatcher for more information on aFeatures.
1.94 + * @see nsIWebBrowserChrome for more information on aChromeFlags.
1.95 + */
1.96 + nsIDOMWindow provideWindow(in nsIDOMWindow aParent,
1.97 + in unsigned long aChromeFlags,
1.98 + in boolean aCalledFromJS,
1.99 + in boolean aPositionSpecified,
1.100 + in boolean aSizeSpecified,
1.101 + in nsIURI aURI,
1.102 + in AString aName,
1.103 + in AUTF8String aFeatures,
1.104 + out boolean aWindowIsNew);
1.105 +};
