Mozilla

• About
• Developers
• Store
• Support
• Products

nsIWindowWatcher

---

This interface keeps track of Gecko/DOM Windows. It is a service that maintains a list of open top-level windows, and allows some operations on them. The interface is scriptable.

Note: This component has an activeWindow attribute. The application must keep this attribute current by setting it as the active window changes, as some clients may expect it to be always to be up-to-date.

Also, because windows must notify the component when they are created or destroyed, this component should keep only a weak reference to any window, not an owning reference. Note that there is no public interface for such notifications. This is taken care of automatically by common embedding code. Embedding clients need do nothing special about this requirement.

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

See also: nsIWindowCreator.

Methods

openWindow

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

Syntax:

nsIDOMWindow nsIWindowWatcher::openWindow(
	in nsIDOMWindow aParent, in string aUrl, 
	in string aName, in string aFeatures,
	in nsISupports aArguments) 

Parameters:

aParent: The parent window. null if there is none.

aUrl: The url which will be loaded into the new window. Must already be escaped, if applicable. It can be null.

aName: The window name from JS window.open. It can be null.

aFeatures: Window features from JS window.open. It can be null.

aArguments: Extra argument(s) to the new window, to be attached as the arguments property. An nsISupportsArray will be unwound into multiple arguments (but not recursively!). It can be null.

Returns:

The new window.

registerNotification

Registers a client of this service to be notified when a window is opened or closed (added to or removed from this service). This method adds an aObserver to the list of objects to be notified.

Syntax:

void nsIWindowWatcher::registerNotification(
	in nsIObserver aObserver) 

Parameters:

aObserver: The object to be notified when windows are opened or closed. Its Observe method will be called with the following parameters:

See also: nsIObserver.

nsresult:

NS_OK if successful.

unregisterNotification

Removes aObserver from the list of objects to be notified.

Syntax:

void nsIWindowWatcher::unregisterNotification(
	in nsIObserver aObserver) 

Parameters:

aObserver: The object to be removed.

nsresult:

NS_OK if successful.

getWindowEnumerator

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

Syntax:

nsISimpleEnumerator nsIWindowWatcher::getWindowEnumerator() 

Parameters:

None.

Returns:

An enumerator which will itself return nsISupports objects which can be QIed to an nsIDOMWindow.

getNewPrompter

Gets a newly created nsIPrompt implementation.

Syntax:

nsIPrompt nsIWindowWatcher::getNewPrompter(
	in nsIDOMWindow aParent) 

Parameters:

aParent:The parent window used for posing alerts. It can be null.

Returns:

A new nsIPrompt object.

getNewAuthPrompter

Gets a newly created nsIAuthPrompt implementation.

Syntax:

nsIAuthPrompt nsIWindowWatcher::getNewAuthPrompter(
	in nsIDOMWindow aParent) 

Parameters:

aParent:The parent window used for posing alerts. It can be null.

Returns:

A new nsIAuthPrompt object.

setWindowCreator

Sets the WindowCreator callback. It must be filled in by the application.

Syntax:

void nsIWindowWatcher::setWindowCreator(
	in nsIWindowCreator creator) 

Parameters:

creator:The callback. If it is null, the callback will be cleared and window creation capabilities lost.

nsresult:

NS_OK if successful.

getChromeForWindow

Retrieves the chrome window mapped to the given DOM window. WindowWatcher keeps a list of all top-level DOM windows currently open, along with their corresponding chrome interfaces. DOM Windows lack a (public) means of retrieving their corresponding chrome directly, so use this method.

Syntax:

nsIWebBrowserChrome nsIWindowWatcher::getChromeForWindow(
	in nsIDOMWindow aWindow) 

Parameters:

aWindow: The DOM window whose chrome window the caller needs.

Returns::

The appropriate chrome window.

getWindowByName

Retrieves an existing window (or frame).

Syntax:

nsIDOMWindow nsIWindowWatcher::getWindowByName(
	in wstring aTargetName, 
	in nsIDOMWindow aCurrentWindow) 

Parameters:

aTargetName: The window name.

aCurrentWindow: A starting point in the window hierarchy to begin the search. If null, each toplevel window will be searched.

Returns:

The desired window.

Attributes

attribute nsIDOMWindow nsIWindowWatcher::activeWindow

The WindowWatcher serves as a global storage facility for the current active (frontmost 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.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History