summaryrefslogtreecommitdiffstats
path: root/toolkit/components/windowcreator/nsIWindowProvider.idl
diff options
context:
space:
mode:
Diffstat (limited to 'toolkit/components/windowcreator/nsIWindowProvider.idl')
-rw-r--r--toolkit/components/windowcreator/nsIWindowProvider.idl109
1 files changed, 109 insertions, 0 deletions
diff --git a/toolkit/components/windowcreator/nsIWindowProvider.idl b/toolkit/components/windowcreator/nsIWindowProvider.idl
new file mode 100644
index 0000000000..a51b5689ee
--- /dev/null
+++ b/toolkit/components/windowcreator/nsIWindowProvider.idl
@@ -0,0 +1,109 @@
+/* -*- 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"
+
+%{ C++
+class nsDocShellLoadState;
+%}
+
+webidl BrowsingContext;
+interface mozIDOMWindowProxy;
+interface nsIURI;
+interface nsIOpenWindowInfo;
+native nsDocShellLoadStatePtr(nsDocShellLoadState*);
+
+/**
+ * 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(e97a3830-15ef-499b-8372-c22d128091c1)]
+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 aOpenWindowInfo Must not be null. This is the information the
+ * caller wants to be used to construct the new window.
+ *
+ * @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 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 aIsPopupRequested True if this window is opened by window.open
+ * with requesting a popup window. This doesn't necessarily mean
+ * whether the actual window is shown as minimal popup or not.
+ *
+ * @param aLoadState Specify setup information of the load in the new window
+ *
+ * @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.
+ */
+ [noscript]
+ BrowsingContext provideWindow(in nsIOpenWindowInfo aOpenWindowInfo,
+ in unsigned long aChromeFlags,
+ in boolean aCalledFromJS,
+ in nsIURI aURI,
+ in AString aName,
+ in AUTF8String aFeatures,
+ in boolean aForceNoOpener,
+ in boolean aForceNoReferrer,
+ in boolean aIsPopupRequested,
+ in nsDocShellLoadStatePtr aLoadState,
+ out boolean aWindowIsNew);
+};