1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/embedding/components/windowwatcher/public/nsIWindowWatcher.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,167 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +
1.12 +interface nsIDOMWindow;
1.13 +interface nsIObserver;
1.14 +interface nsIPrompt;
1.15 +interface nsIAuthPrompt;
1.16 +interface nsISimpleEnumerator;
1.17 +interface nsIWebBrowserChrome;
1.18 +interface nsIWindowCreator;
1.19 +
1.20 +
1.21 +
1.22 +/**
1.23 + * nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains
1.24 + * a list of open top-level windows, and allows some operations on them.
1.25 +
1.26 + * Usage notes:
1.27 +
1.28 + * This component has an |activeWindow| property. Clients may expect
1.29 + * this property to be always current, so to properly integrate this component
1.30 + * the application will need to keep it current by setting the property
1.31 + * as the active window changes.
1.32 + * This component should not keep a (XPCOM) reference to any windows;
1.33 + * the implementation will claim no ownership. Windows must notify
1.34 + * this component when they are created or destroyed, so only a weak
1.35 + * reference is kept. Note that there is no interface for such notifications
1.36 + * (not a public one, anyway). This is taken care of both in Mozilla and
1.37 + * by common embedding code. Embedding clients need do nothing special
1.38 + * about that requirement.
1.39 + * This component must be initialized at application startup by calling
1.40 + * setWindowCreator.
1.41 + */
1.42 +[scriptable, uuid(67bc1691-fbaf-484a-a15b-c96212b45034)]
1.43 +interface nsIWindowWatcher : nsISupports {
1.44 +
1.45 + /** Create a new window. It will automatically be added to our list
1.46 + (via addWindow()).
1.47 + @param aParent parent window, if any. Null if no parent. If it is
1.48 + impossible to get to an nsIWebBrowserChrome from aParent, this
1.49 + method will effectively act as if aParent were null.
1.50 + @param aURL url to which to open the new window. Must already be
1.51 + escaped, if applicable. can be null.
1.52 + @param aName window name from JS window.open. can be null. If a window
1.53 + with this name already exists, the openWindow call may just load
1.54 + aUrl in it (if aUrl is not null) and return it.
1.55 + @param aFeatures window features from JS window.open. can be null.
1.56 + @param aArguments extra argument(s) to the new window, to be attached
1.57 + as the |arguments| property. An nsISupportsArray will be
1.58 + unwound into multiple arguments (but not recursively!).
1.59 + can be null.
1.60 + @return the new window
1.61 +
1.62 + @note This method may examine the JS context stack for purposes of
1.63 + determining the security context to use for the search for a given
1.64 + window named aName.
1.65 + @note This method should try to set the default charset for the new
1.66 + window to the default charset of aParent. This is not guaranteed,
1.67 + however.
1.68 + @note This method may dispatch a "toplevel-window-ready" notification
1.69 + via nsIObserverService if the window did not already exist.
1.70 + */
1.71 + nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl,
1.72 + in string aName, in string aFeatures,
1.73 + in nsISupports aArguments);
1.74 +
1.75 + /** Clients of this service can register themselves to be notified
1.76 + when a window is opened or closed (added to or removed from this
1.77 + service). This method adds an aObserver to the list of objects
1.78 + to be notified.
1.79 + @param aObserver the object to be notified when windows are
1.80 + opened or closed. Its Observe method will be
1.81 + called with the following parameters:
1.82 +
1.83 + aObserver::Observe interprets its parameters so:
1.84 + aSubject the window being opened or closed, sent as an nsISupports
1.85 + which can be QIed to an nsIDOMWindow.
1.86 + aTopic a wstring, either "domwindowopened" or "domwindowclosed".
1.87 + someData not used.
1.88 + */
1.89 + void registerNotification(in nsIObserver aObserver);
1.90 +
1.91 + /** Clients of this service can register themselves to be notified
1.92 + when a window is opened or closed (added to or removed from this
1.93 + service). This method removes an aObserver from the list of objects
1.94 + to be notified.
1.95 + @param aObserver the observer to be removed.
1.96 + */
1.97 + void unregisterNotification(in nsIObserver aObserver);
1.98 +
1.99 + /** Get an iterator for currently open windows in the order they were opened,
1.100 + guaranteeing that each will be visited exactly once.
1.101 + @return an enumerator which will itself return nsISupports objects which
1.102 + can be QIed to an nsIDOMWindow
1.103 + */
1.104 +
1.105 + nsISimpleEnumerator getWindowEnumerator();
1.106 +
1.107 + /** Return a newly created nsIPrompt implementation.
1.108 + @param aParent the parent window used for posing alerts. can be null.
1.109 + @return a new nsIPrompt object
1.110 + */
1.111 +
1.112 + nsIPrompt getNewPrompter(in nsIDOMWindow aParent);
1.113 +
1.114 + /** Return a newly created nsIAuthPrompt implementation.
1.115 + @param aParent the parent window used for posing alerts. can be null.
1.116 + @return a new nsIAuthPrompt object
1.117 + */
1.118 +
1.119 + nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);
1.120 +
1.121 + /** Set the window creator callback. It must be filled in by the app.
1.122 + openWindow will use it to create new windows.
1.123 + @param creator the callback. if null, the callback will be cleared
1.124 + and window creation capabilities lost.
1.125 + */
1.126 + void setWindowCreator(in nsIWindowCreator creator);
1.127 +
1.128 + /** Returns true if a window creator callback has been set, false otherwise.
1.129 + */
1.130 + boolean hasWindowCreator();
1.131 +
1.132 +
1.133 + /** Retrieve the chrome window mapped to the given DOM window. Window
1.134 + Watcher keeps a list of all top-level DOM windows currently open,
1.135 + along with their corresponding chrome interfaces. Since DOM Windows
1.136 + lack a (public) means of retrieving their corresponding chrome,
1.137 + this method will do that.
1.138 + @param aWindow the DOM window whose chrome window the caller needs
1.139 + @return the corresponding chrome window
1.140 + */
1.141 + nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);
1.142 +
1.143 + /**
1.144 + Retrieve an existing window (or frame).
1.145 + @param aTargetName the window name
1.146 + @param aCurrentWindow a starting point in the window hierarchy to
1.147 + begin the search. If null, each toplevel window
1.148 + will be searched.
1.149 +
1.150 + Note: This method will search all open windows for any window or
1.151 + frame with the given window name. Make sure you understand the
1.152 + security implications of this before using this method!
1.153 + */
1.154 + nsIDOMWindow getWindowByName(in wstring aTargetName,
1.155 + in nsIDOMWindow aCurrentWindow);
1.156 +
1.157 + /** The Watcher serves as a global storage facility for the current active
1.158 + (frontmost non-floating-palette-type) window, storing and returning
1.159 + it on demand. Users must keep this attribute current, including after
1.160 + the topmost window is closed. This attribute obviously can return null
1.161 + if no windows are open, but should otherwise always return a valid
1.162 + window.
1.163 + */
1.164 + attribute nsIDOMWindow activeWindow;
1.165 +
1.166 +};
1.167 +
1.168 +%{C++
1.169 +#define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1"
1.170 +%}
