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 |
|
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 benull
.
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. Ifnull
, 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.
nsIObserverService
if the window did not already exist.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 annsIWebBrowserChrome
from aParent, this method will effectively act as if aParent werenull
. -
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 benull
. If a window with this name already exists, theopenWindow
call may just load aUrl in it (if aUrl is notnull
) and return it. -
aFeatures
-
Window features. See
window.open
for details. Can benull
. 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 benull
, 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 annsIArray
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
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 anobserve
method, which will be called with the following parameters:aSubject
- the window being opened or closed, sent as annsISupports
which can bensISupports.QueryInterface()
(QueryInterfaced) to annsIDOMWindow
.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 isnull
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.