michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- michael@0: * michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: michael@0: interface nsIDOMWindow; michael@0: interface nsIObserver; michael@0: interface nsIPrompt; michael@0: interface nsIAuthPrompt; michael@0: interface nsISimpleEnumerator; michael@0: interface nsIWebBrowserChrome; michael@0: interface nsIWindowCreator; michael@0: michael@0: michael@0: michael@0: /** michael@0: * nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains michael@0: * a list of open top-level windows, and allows some operations on them. michael@0: michael@0: * Usage notes: michael@0: michael@0: * This component has an |activeWindow| property. Clients may expect michael@0: * this property to be always current, so to properly integrate this component michael@0: * the application will need to keep it current by setting the property michael@0: * as the active window changes. michael@0: * This component should not keep a (XPCOM) reference to any windows; michael@0: * the implementation will claim no ownership. Windows must notify michael@0: * this component when they are created or destroyed, so only a weak michael@0: * reference is kept. Note that there is no interface for such notifications michael@0: * (not a public one, anyway). This is taken care of both in Mozilla and michael@0: * by common embedding code. Embedding clients need do nothing special michael@0: * about that requirement. michael@0: * This component must be initialized at application startup by calling michael@0: * setWindowCreator. michael@0: */ michael@0: [scriptable, uuid(67bc1691-fbaf-484a-a15b-c96212b45034)] michael@0: interface nsIWindowWatcher : nsISupports { michael@0: michael@0: /** Create a new window. It will automatically be added to our list michael@0: (via addWindow()). michael@0: @param aParent parent window, if any. Null if no parent. If it is michael@0: impossible to get to an nsIWebBrowserChrome from aParent, this michael@0: method will effectively act as if aParent were null. michael@0: @param aURL url to which to open the new window. Must already be michael@0: escaped, if applicable. can be null. michael@0: @param aName window name from JS window.open. can be null. If a window michael@0: with this name already exists, the openWindow call may just load michael@0: aUrl in it (if aUrl is not null) and return it. michael@0: @param aFeatures window features from JS window.open. can be null. michael@0: @param aArguments extra argument(s) to the new window, to be attached michael@0: as the |arguments| property. An nsISupportsArray will be michael@0: unwound into multiple arguments (but not recursively!). michael@0: can be null. michael@0: @return the new window michael@0: michael@0: @note This method may examine the JS context stack for purposes of michael@0: determining the security context to use for the search for a given michael@0: window named aName. michael@0: @note This method should try to set the default charset for the new michael@0: window to the default charset of aParent. This is not guaranteed, michael@0: however. michael@0: @note This method may dispatch a "toplevel-window-ready" notification michael@0: via nsIObserverService if the window did not already exist. michael@0: */ michael@0: nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl, michael@0: in string aName, in string aFeatures, michael@0: in nsISupports aArguments); michael@0: michael@0: /** Clients of this service can register themselves to be notified michael@0: when a window is opened or closed (added to or removed from this michael@0: service). This method adds an aObserver to the list of objects michael@0: to be notified. michael@0: @param aObserver the object to be notified when windows are michael@0: opened or closed. Its Observe method will be michael@0: called with the following parameters: michael@0: michael@0: aObserver::Observe interprets its parameters so: michael@0: aSubject the window being opened or closed, sent as an nsISupports michael@0: which can be QIed to an nsIDOMWindow. michael@0: aTopic a wstring, either "domwindowopened" or "domwindowclosed". michael@0: someData not used. michael@0: */ michael@0: void registerNotification(in nsIObserver aObserver); michael@0: michael@0: /** Clients of this service can register themselves to be notified michael@0: when a window is opened or closed (added to or removed from this michael@0: service). This method removes an aObserver from the list of objects michael@0: to be notified. michael@0: @param aObserver the observer to be removed. michael@0: */ michael@0: void unregisterNotification(in nsIObserver aObserver); michael@0: michael@0: /** Get an iterator for currently open windows in the order they were opened, michael@0: guaranteeing that each will be visited exactly once. michael@0: @return an enumerator which will itself return nsISupports objects which michael@0: can be QIed to an nsIDOMWindow michael@0: */ michael@0: michael@0: nsISimpleEnumerator getWindowEnumerator(); michael@0: michael@0: /** Return a newly created nsIPrompt implementation. michael@0: @param aParent the parent window used for posing alerts. can be null. michael@0: @return a new nsIPrompt object michael@0: */ michael@0: michael@0: nsIPrompt getNewPrompter(in nsIDOMWindow aParent); michael@0: michael@0: /** Return a newly created nsIAuthPrompt implementation. michael@0: @param aParent the parent window used for posing alerts. can be null. michael@0: @return a new nsIAuthPrompt object michael@0: */ michael@0: michael@0: nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent); michael@0: michael@0: /** Set the window creator callback. It must be filled in by the app. michael@0: openWindow will use it to create new windows. michael@0: @param creator the callback. if null, the callback will be cleared michael@0: and window creation capabilities lost. michael@0: */ michael@0: void setWindowCreator(in nsIWindowCreator creator); michael@0: michael@0: /** Returns true if a window creator callback has been set, false otherwise. michael@0: */ michael@0: boolean hasWindowCreator(); michael@0: michael@0: michael@0: /** Retrieve the chrome window mapped to the given DOM window. Window michael@0: Watcher keeps a list of all top-level DOM windows currently open, michael@0: along with their corresponding chrome interfaces. Since DOM Windows michael@0: lack a (public) means of retrieving their corresponding chrome, michael@0: this method will do that. michael@0: @param aWindow the DOM window whose chrome window the caller needs michael@0: @return the corresponding chrome window michael@0: */ michael@0: nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow); michael@0: michael@0: /** michael@0: Retrieve an existing window (or frame). michael@0: @param aTargetName the window name michael@0: @param aCurrentWindow a starting point in the window hierarchy to michael@0: begin the search. If null, each toplevel window michael@0: will be searched. michael@0: michael@0: Note: This method will search all open windows for any window or michael@0: frame with the given window name. Make sure you understand the michael@0: security implications of this before using this method! michael@0: */ michael@0: nsIDOMWindow getWindowByName(in wstring aTargetName, michael@0: in nsIDOMWindow aCurrentWindow); michael@0: michael@0: /** The Watcher serves as a global storage facility for the current active michael@0: (frontmost non-floating-palette-type) window, storing and returning michael@0: it on demand. Users must keep this attribute current, including after michael@0: the topmost window is closed. This attribute obviously can return null michael@0: if no windows are open, but should otherwise always return a valid michael@0: window. michael@0: */ michael@0: attribute nsIDOMWindow activeWindow; michael@0: michael@0: }; michael@0: michael@0: %{C++ michael@0: #define NS_WINDOWWATCHER_CONTRACTID "@mozilla.org/embedcomp/window-watcher;1" michael@0: %}