NsIWindowMediator: Difference between revisions

From MozillaZine Knowledge Base
Jump to navigationJump to search
No edit summary
Line 2: Line 2:
{{wrongtitle|title=nsIWindowMediator}}
{{wrongtitle|title=nsIWindowMediator}}


Window mediator is Mozilla component that keeps track of open windows. It's accessed through <code>nsIWindowMediator</code> interface. Two most common uses of nsIWindowMediator are
Window mediator is Mozilla component that keeps track of open windows. It's accessed through <code>nsIWindowMediator</code> interface. Two most common uses of <code>nsIWindowMediator</code> are:
# Getting the most recent / any window of given type.
# Getting the most recent / any window of given type.
# Enumerating all windows of given type.
# Enumerating all windows of given type.


In the examples below <code>type</code> specifies the type of windows you want to search. You can specify a type of your own window by creating an <code>windowtype</code> attribute on the <code><window></code> element.
In the examples below <code>type</code> specifies the type of windows you want to search. You can specify a type of your own window by creating an <code>windowtype</code> attribute on the document element (the top-level one, e.g. <code><window></code> or <code>dialog</code>).


Browser windows have <code>navigator:browser</code> window type. To search all windows, regardless of their type, pass an empty string, <code>""</code>.
Browser windows have <code>navigator:browser</code> window type. To search all windows, regardless of their type, pass an empty string, <code>""</code>.
Line 13: Line 13:
The following code is useful when you need any of the windows of given type, or to check if a window of a particular type (e.g. your extension's Options dialog) is already open.
The following code is useful when you need any of the windows of given type, or to check if a window of a particular type (e.g. your extension's Options dialog) is already open.


<code>getMostRecentWindow</code> returns a <code>Window</code> object, or <code>null</code>, if there are no windows with given <code>windowtype</code> open.
<code>getMostRecentWindow</code> returns a <code>ChromeWindow</code> object, or <code>null</code>, if there are no windows of given type open.
<pre>
<pre>
var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"].
var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
        getService(Components.interfaces.nsIWindowMediator);
                  .getService(Components.interfaces.nsIWindowMediator);
var win = wm.getMostRecentWindow(type);
var win = wm.getMostRecentWindow(type);
</pre>
</pre>
Line 22: Line 22:
== Enumerating windows ==
== Enumerating windows ==
<pre>
<pre>
var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"].
var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
        getService(Components.interfaces.nsIWindowMediator);
                  .getService(Components.interfaces.nsIWindowMediator);
var enumerator = wm.getEnumerator(type);
var enumerator = wm.getEnumerator(type);
while(enumerator.hasMoreElements()) {
while(enumerator.hasMoreElements()) {
   var win = enumerator.getNext();
   var win = enumerator.getNext();
   // do something with |win|
   // |win| is [Object ChromeWindow] (just like |window|), do something with it
}
}
</pre>
</pre>


Note: in <code>nsIWindowMediator</code>'s reference page the return type of <code>getMostRecentWindow</code> and the type of enumerator's elements is said to be <code>nsIDOMWindow</code>/<code>nsIDOMWindowInternal</code>. In fact, those methods usually (always?) return a <code>ChromeWindow</code> object, implementing both of those interfaces and a few others, when called from JavaScript code. The global <code>window</code> object, you're probably familiar with, is of <code>ChromeWindow</code> type.


== References ==
== References ==
* [http://xulplanet.com/references/xpcomref/ifaces/nsIWindowMediator.html nsIWindowMediator reference page on XUL Planet]
* XUL Planet:
** [http://xulplanet.com/references/xpcomref/ifaces/nsIWindowMediator.html nsIWindowMediator reference]
** [http://xulplanet.com/references/objref/ChromeWindow.html ChromeWindow object reference]


[[Category:Example code|nsIWindowMediator]] [[Category:XPCOM example code|nsIWindowMediator]]
[[Category:Example code|nsIWindowMediator]] [[Category:XPCOM example code|nsIWindowMediator]]

Revision as of 04:08, 1 August 2005

This page is part of the extension development documentation project.

Ask your questions in MozillaZine Forums. Also try browsing example code.

Note: development documentation is in process of being moved to Mozilla Development Center (MDC).

Window mediator is Mozilla component that keeps track of open windows. It's accessed through nsIWindowMediator interface. Two most common uses of nsIWindowMediator are:

  1. Getting the most recent / any window of given type.
  2. Enumerating all windows of given type.

In the examples below type specifies the type of windows you want to search. You can specify a type of your own window by creating an windowtype attribute on the document element (the top-level one, e.g. <window> or dialog).

Browser windows have navigator:browser window type. To search all windows, regardless of their type, pass an empty string, "".

Getting most recent window

The following code is useful when you need any of the windows of given type, or to check if a window of a particular type (e.g. your extension's Options dialog) is already open.

getMostRecentWindow returns a ChromeWindow object, or null, if there are no windows of given type open.

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                   .getService(Components.interfaces.nsIWindowMediator);
var win = wm.getMostRecentWindow(type);

Enumerating windows

var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                   .getService(Components.interfaces.nsIWindowMediator);
var enumerator = wm.getEnumerator(type);
while(enumerator.hasMoreElements()) {
  var win = enumerator.getNext();
  // |win| is [Object ChromeWindow] (just like |window|), do something with it
}

Note: in nsIWindowMediator's reference page the return type of getMostRecentWindow and the type of enumerator's elements is said to be nsIDOMWindow/nsIDOMWindowInternal. In fact, those methods usually (always?) return a ChromeWindow object, implementing both of those interfaces and a few others, when called from JavaScript code. The global window object, you're probably familiar with, is of ChromeWindow type.

References