nsIWindowWatcher

This interface is the keeper of Gecko/DOM Windows. It maintains a list of open top-level windows, and allows some operations on them.
Inherits from: nsISupports Last changed in Gecko 0.9.6

Usage notes: This component has an activeWindow property. Clients may expect this property to be always current, so to properly integrate this component the application will need to keep it current by setting the property as the active window changes. This component should not keep a (XPCOM) reference to any windows; the implementation will claim no ownership. Windows must notify this component when they are created or destroyed, so only a weak reference is kept. Note that there is no interface for such notifications (not a public one, anyway). This is taken care of both in Mozilla and by common embedding code. Embedding clients need do nothing special about that requirement.

This component must be initialized at application startup by calling setWindowCreator().

Method overview

nsIWebBrowserChrome getChromeForWindow(in nsIDOMWindow aWindow);
nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);
nsIPrompt getNewPrompter(in nsIDOMWindow aParent);
nsIDOMWindow getWindowByName(in wstring aTargetName, in nsIDOMWindow aCurrentWindow);
nsISimpleEnumerator getWindowEnumerator();
nsIDOMWindow openWindow(in nsIDOMWindow aParent, in string aUrl, in string aName, in string aFeatures, in nsISupports aArguments);
void registerNotification(in nsIObserver aObserver);
void setWindowCreator(in nsIWindowCreator creator);
void unregisterNotification(in nsIObserver aObserver);

Attributes

Attribute Type Description
activeWindow nsIDOMWindow The Watcher serves as a global storage facility for the current active (front most non-floating-palette-type) window, storing and returning it on demand. Users must keep this attribute current, including after the topmost window is closed. This attribute will be null if the active window is not an nsIDOMWindow; for example, if the active window is an alert.

Methods

getChromeForWindow()

Retrieve the chrome window mapped to the given DOM window. nsIWindowWatcher keeps a list of all top-level DOM windows currently open, along with their corresponding chrome interfaces. Since DOM Windows lack a (public) means of retrieving their corresponding chrome, this method will do that.

nsIWebBrowserChrome getChromeForWindow(
  in nsIDOMWindow aWindow
);
Parameters
aWindow
The nsIDOMWindow whose chrome window the caller needs.
Return value

An nsIWebBrowserChrome object for the corresponding chrome window

getNewAuthPrompter()

Return a newly created nsIAuthPrompt implementation.

nsIAuthPrompt getNewAuthPrompter(
  in nsIDOMWindow aParent
);
Parameters
aParent
The parent window used for posing alerts. can be null.
Return value

A new nsIAuthPrompt object.

getNewPrompter()

Return a newly created nsIPrompt implementation.

nsIPrompt getNewPrompter(
  in nsIDOMWindow aParent
);
Parameters
aParent
The parent nsIDOMWindow used for posing alerts. Can be null.
Return value

A new nsIPrompt object.

getWindowByName()

Retrieve an existing window (or frame).

Note: This method will search all open windows for any window or frame with the given window name. Make sure you understand the security implications of this before using this method!
nsIDOMWindow getWindowByName(
  in wstring aTargetName,
  in nsIDOMWindow aCurrentWindow
);
Parameters
aTargetName
The window name.
aCurrentWindow
The nsIDOMWindow starting point in the window hierarchy to begin the search. If null, each top level window will be searched.
Return value

The nsIDOMWindow with the target name.

getWindowEnumerator()

Get an nsISimpleEnumerator for currently open windows in the order they were opened, guaranteeing that each will be visited exactly once.

nsISimpleEnumerator getWindowEnumerator();
Parameters

None.

Return value

An nsISimpleEnumerator which will itself return nsISupports objects which can be nsISupports.QueryInterface() (QueryInterfaced) to an nsIDOMWindow.

openWindow()

Creates a new window. It will automatically be added to our list.

Note: This method may examine the Javascript context stack for purposes of determining the security context to use for the search for a given window named aName.
Note: This method will try to set the default charset for the new window to the default charset of aParent. This is not guaranteed, however.
Note: This method may dispatch a "toplevel-window-ready" notification via nsIObserverService if the window did not already exist.
Note: Supported nsISupportsPrimitive objects will be reflected into window.arguments as the base type, however ID, void and 64-bit primitive types are not currently supported and will reflect into window.arguments as null.
nsIDOMWindow openWindow(
  in nsIDOMWindow aParent,
  in string aUrl,
  in string aName,
  in string aFeatures,
  in nsISupports aArguments
);
Parameters
aParent
The parent window, if any. null if no parent. If it is impossible to get to an nsIWebBrowserChrome from aParent, this method will effectively act as if aParent were null.
aUrl
The url to open in the new window. Must already be escaped, if applicable. Can be null.
aName
A window name assigned using Window interface's open() method loads the specified resource into the browsing context (window, <iframe> or tab) with the specified name. If the name doesn't exist, then a new window is opened and the specified resource is loaded into its browsing context.">window.open. Can be null. If a window with this name already exists, the openWindow call may just load aUrl in it (if aUrl is not null) and return it.
aFeatures
Window features. See Window interface's open() method loads the specified resource into the browsing context (window, <iframe> or tab) with the specified name. If the name doesn't exist, then a new window is opened and the specified resource is loaded into its browsing context.">window.open for details. Can be null. List of Feature Options
aArguments
Extra argument(s) to be attached to the new window as the window.arguments property. An nsISupportsArray will be unwound into multiple arguments (but not recursively!). Can be null, in which case the window.arguments property will not be set on the new window. As of Gecko 1.9 alpha 1, can also be an nsIArray instead.
Return value

An nsIDOMWindow for the opened window.

Example

For example, in a XUL application or Mozilla extension, if the window object is unavailable (for example, when opening a window from XPCOM component code), you might want to use this interface for opening a new window:

 var ww = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
                    .getService(Components.interfaces.nsIWindowWatcher);
 var win = ww.openWindow(null, "chrome://myextension/content/about.xul",
                         "aboutMyExtension", "chrome,centerscreen", null);
Note: Versions of Gecko before Gecko 2.0 would ignore some of the chrome flags when opening a chrome window without an opener window, instead behaving as if the "all" flag was present. This was fixed in bug 509124.

registerNotification()

Clients of this service can register themselves to be notified when a window is opened or closed (added to or removed from this service). This method adds an nsIObserver to the list of objects to be notified.

void registerNotification(
  in nsIObserver aObserver
);
Parameters
Note: Be careful about generating open/close window events inside nsIObserver.observe(). For example the following code will block the system because it will open windows continuously:
function MyWindowObserver() {
  this.observe=function(aSubject, aTopic, aData) {
    alert("window event: " + aTopic)
    //and this is where the bugs origins because opening this alert will cause a window-open
    //event and the call of this method again (forever)
  }
}
var ww = Components.classes["@mozilla.org/embedcomp/window-watcher;1"]
              .getService(Components.interfaces.nsIWindowWatcher);
ww.registerNotification(new MyWindowObserver())
alert("") //generate the first window-open event
aObserver
The nsIObserver to be notified when windows are opened or closed. aObserver should implement an observe method, which will be called with the following parameters:

setWindowCreator()

Set the window creator callback. It must be filled in by the app. openWindow() will use it to create new windows.

void setWindowCreator(
  in nsIWindowCreator creator
);
Parameters
creator
The nsIWindowCreator callback. If this is null the callback will be cleared and window creation capabilities lost.

unregisterNotification()

Clients of this service can register themselves to be notified when a window is opened or closed (added to or removed from this service). This method removes an nsIObserver from the list of objects to be notified.

void unregisterNotification(
  in nsIObserver aObserver
);
Parameters
aObserver
the nsIObserver to be removed.