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

Attributes

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).

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.

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);

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

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:

• aSubject - the window being opened or closed, sent as an nsISupports which can be nsISupports.QueryInterface() (QueryInterfaced) to an nsIDOMWindow.
• aTopic - a wstring, either "domwindowopened" or "domwindowclosed".
• aData - not used.

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.