You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.


TOC PREV NEXT INDEX

Embedding Gecko API


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.


Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX