Skip to main content

Visit Mozilla.org

nsIWindowWatcher

From MDC

nsIWindowWatcher is the keeper of Gecko/DOM Windows. It maintains a list of open top-level windows, and allows some operations on them.

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.


Contents

nsIWindowWatcher is defined in embedding/components/windowwatcher/public/nsIWindowWatcher.idl. It is scriptable and has been frozen since Mozilla 0.9.6.

Inherits from: nsISupports

[edit] Method overview

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


[edit] 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 obviously can return null if no windows are open, but should otherwise always return a valid window.

[edit] Methods

[edit] openWindow()

Create 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);
[edit] 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.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.open for details. Can be null.

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.

[edit] Return value

An nsIDOMWindow for the opened window.

[edit] 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: This method may examine the JS context stack for purposes of determining the security context to use for the search for a given window named aName.

Note: This method should 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.

[edit] 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);
[edit] Parameters
aObserver

the nsIObserver to be notified when windows are opened or closed. aObserver should implement an observe method: 

 void observe( in nsISupports aSubject,
               in string      aTopic,
               in wstring     aData );

which will be called with the following parameters:

  • aSubject - the window being opened or closed, sent as an nsISupports which can be QueryInterfaced to an nsIDOMWindow.
  • aTopic - a wstring, either "domwindowopened" or "domwindowclosed".
  • aData - not used.
Note: Be careful about generate open/close window events inside the nsIObserver::observe method. 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

[edit] 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);
[edit] Parameters
aObserver

the nsIObserver to be removed.

[edit] getWindowEnumerator()

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

 nsISimpleEnumerator getWindowEnumerator();
[edit] Return value

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

[edit] getNewPrompter()

Return a newly created nsIPrompt implementation. 

 nsIPrompt getNewPrompter(in nsIDOMWindow aParent);
[edit] Parameters
aParent

the parent nsIDOMWindow used for posing alerts. can be null.

[edit] Return value

A new nsIPrompt object.

[edit] getNewAuthPrompter()

Return a newly created nsIAuthPrompt implementation. 

 nsIAuthPrompt getNewAuthPrompter(in nsIDOMWindow aParent);
[edit] Parameters
aParent

the parent window used for posing alerts. Can be null.

[edit] Return value

A new nsIAuthPrompt object

[edit] 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);
[edit] Parameters
creator

The nsIWindowCreator callback. If this is null the callback will be cleared and window creation capabilities lost.

[edit] 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);
[edit] Parameters
aWindow

The nsIDOMWindow whose chrome window the caller needs.

[edit] Return value

An nsIWebBrowserChrome object for the corresponding chrome window

[edit] getWindowByName()

Retrieve an existing window (or frame). 

 nsIDOMWindow getWindowByName(in wstring aTargetName,
                              in nsIDOMWindow aCurrentWindow);
[edit] 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.

[edit] Return value

The nsIDOMWindow with the target name.

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!
Retrieved from "http://developer.mozilla.org/en/docs/nsIWindowWatcher"