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/. */
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.
14 #include
"nsISupports.idl"
16 interface nsIDOMWindow
;
20 * The nsIWindowProvider interface exists so that the window watcher's default
21 * behavior of opening a new window can be easly modified. When the window
22 * watcher needs to open a new window, it will first check with the
23 * nsIWindowProvider it gets from the parent window. If there is no provider
24 * or the provider does not provide a window, the window watcher will proceed
25 * to actually open a new window.
27 [scriptable
, uuid(f607bd66
-08e5
-4d2e
-ad83
-9f9f3ca17658
)]
28 interface nsIWindowProvider
: nsISupports
31 * A method to request that this provider provide a window. The window
32 * returned need not to have the right name or parent set on it; setting
33 * those is the caller's responsibility. The provider can always return null
34 * to have the caller create a brand-new window.
36 * @param aParent Must not be null. This is the window that the caller wants
37 * to use as the parent for the new window. Generally,
38 * nsIWindowProvider implementors can expect to be somehow related to
39 * aParent; the relationship may depend on the nsIWindowProvider
42 * @param aChromeFlags The chrome flags the caller will use to create a new
43 * window if this provider returns null. See nsIWebBrowserChrome for
44 * the possible values of this field.
46 * @param aPositionSpecified Whether the attempt to create a window is trying
47 * to specify a position for the new window.
49 * @param aSizeSpecified Whether the attempt to create a window is trying to
50 * specify a size for the new window.
52 * @param aURI The URI to be loaded in the new window (may be NULL). The
53 * nsIWindowProvider implementation must not load this URI into the
54 * window it returns. This URI is provided solely to help the
55 * nsIWindowProvider implementation make decisions; the caller will
56 * handle loading the URI in the window returned if provideWindow
59 * When making decisions based on aURI, note that even when it's not
60 * null, aURI may not represent all relevant information about the
61 * load. For example, the load may have extra load flags, POST data,
64 * @param aName The name of the window being opened. Setting the name on the
65 * return value of provideWindow will be handled by the caller; aName
66 * is provided solely to help the nsIWindowProvider implementation
69 * @param aFeatures The feature string for the window being opened. This may
70 * be empty. The nsIWindowProvider implementation is allowed to apply
71 * the feature string to the window it returns in any way it sees fit.
72 * See the nsIWindowWatcher interface for details on feature strings.
74 * @param aWindowIsNew [out] Whether the window being returned was just
75 * created by the window provider implementation. This can be used by
76 * callers to keep track of which windows were opened by the user as
77 * opposed to being opened programmatically. This should be set to
78 * false if the window being returned existed before the
79 * provideWindow() call. The value of this out parameter is
80 * meaningless if provideWindow() returns null.
82 * @return A window the caller should use or null if the caller should just
83 * create a new window. The returned window may be newly opened by
84 * the nsIWindowProvider implementation or may be a window that
87 * @throw NS_ERROR_ABORT if the caller should cease its attempt to open a new
90 * @see nsIWindowWatcher for more information on aFeatures.
91 * @see nsIWebBrowserChrome for more information on aChromeFlags.
93 nsIDOMWindow provideWindow
(in nsIDOMWindow aParent
,
94 in unsigned long aChromeFlags
,
95 in boolean aCalledFromJS
,
96 in boolean aPositionSpecified
,
97 in boolean aSizeSpecified
,
100 in AUTF8String aFeatures
,
101 out boolean aWindowIsNew
);