Revision 448707 of nsIWindowMediator

<p>{{ IFSummary("xpfe/appshell/public/nsIWindowMediator.idl", "nsISupports", "Scriptable", "8.0", "The window mediator is a Mozilla component that keeps track of open windows.") }}</p>
<p>The two most common uses of <code>nsIWindowMediator</code> are, enumerating all windows of a given type and getting the most recent / any window of a given type.</p>
<p>Implemented by: <code>@mozilla.org/appshell/window-mediator;1</code> as a service:</p>
<pre class="eval">
var windowMediator = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                     .getService(Components.interfaces.nsIWindowMediator);
</pre>
<h2 id="Method_overview" name="Method_overview">Method overview</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td><code>void <a href="#addListener()">addListener</a>(in nsIWindowMediatorListener aListener);</code></td>
    </tr>
    <tr>
      <td><code>boolean <a href="#calculateZPosition()">calculateZPosition</a>(in nsIXULWindow inWindow, in unsigned long inPosition, in nsIWidget inBelow, out unsigned long outPosition, out nsIWidget outBelow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>nsISimpleEnumerator <a href="#getEnumerator()">getEnumerator</a>(in wstring aWindowType);</code></td>
    </tr>
    <tr>
      <td><code>nsIDOMWindow <a href="#getMostRecentWindow()">getMostRecentWindow</a>(in wstring aWindowType);</code></td>
    </tr>
    <tr>
      <td><code>nsIDOMWindow <a href="#getOuterWindowWithId()">getOuterWindowWithId</a>(in unsigned long long aOuterWindowID);</code></td>
    </tr>
    <tr>
      <td><code>nsISimpleEnumerator <a href="#getXULWindowEnumerator()">getXULWindowEnumerator</a>(in wstring aWindowType);</code></td>
    </tr>
    <tr>
      <td><code>PRUint32 <a href="#getZLevel()">getZLevel</a>(in nsIXULWindow aWindow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>nsISimpleEnumerator <a href="#getZOrderDOMWindowEnumerator()">getZOrderDOMWindowEnumerator</a>(in wstring aWindowType, in boolean aFrontToBack);</code></td>
    </tr>
    <tr>
      <td><code>nsISimpleEnumerator <a href="#getZOrderXULWindowEnumerator()">getZOrderXULWindowEnumerator</a>(in wstring aWindowType, in boolean aFrontToBack);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="#registerWindow()">registerWindow</a>(in nsIXULWindow aWindow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>void <a href="#removeListener()">removeListener</a>(in nsIWindowMediatorListener aListener);</code></td>
    </tr>
    <tr>
      <td><code>void <a href="#setZLevel()">setZLevel</a>(in nsIXULWindow aWindow, in PRUint32 aZLevel);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>void <a href="#setZPosition()">setZPosition</a>(in nsIXULWindow inWindow, in unsigned long inPosition, in nsIXULWindow inBelow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>void <a href="#unregisterWindow()">unregisterWindow</a>(in nsIXULWindow aWindow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>void <a href="#updateWindowTimeStamp()">updateWindowTimeStamp</a>(in nsIXULWindow aWindow);</code> {{ noscript_inline() }}</td>
    </tr>
    <tr>
      <td><code>void <a href="#updateWindowTitle()">updateWindowTitle</a>(in nsIXULWindow aWindow, in wstring inTitle );</code> {{ noscript_inline() }}</td>
    </tr>
  </tbody>
</table>
<h2 id="Constants" name="Constants">Constants</h2>
<table class="standard-table">
  <tbody>
    <tr>
      <td class="header">Constant</td>
      <td class="header">Value</td>
      <td class="header">Description</td>
    </tr>
    <tr>
      <td><code>zLevelTop</code></td>
      <td><code>1</code></td>
      <td>Send window to top.</td>
    </tr>
    <tr>
      <td><code>zLevelBottom</code></td>
      <td><code>2</code></td>
      <td>Send window to bottom.</td>
    </tr>
    <tr>
      <td><code>zLevelBelow</code></td>
      <td><code>3</code></td>
      <td>Place window below some window.</td>
    </tr>
  </tbody>
</table>
<h2 id="Methods" name="Methods">Methods</h2>
<h3 id="addListener()" name="addListener()">addListener()</h3>
<p>Register a listener for window status changes.</p>
<pre class="eval">
void addListener(
  in nsIWindowMediatorListener aListener
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aListener</code></dt>
  <dd>
    The listener to register.</dd>
</dl>
<p>{{ method_noscript("calculateZPosition") }}</p>
<p>A window wants to be moved in z-order. Calculate whether and how it should be constrained. Note this method is advisory only: it changes nothing either in WindowMediator's internal state or with the window.</p>
<p>{{ NoteStart() }}It compares the {{ interface("nsIXULWindow") }} to {{ interface("nsIWidgets") }}. A pure interface would use all {{ interface("nsIXULWindows") }}. But we expect this to be called from callbacks originating in native window code. They are expected to hand us comparison values which are pulled from general storage in the native widget, and may not correspond to an {{ interface("nsIWidget") }} at all. For that reason this interface requires only objects one step removed from the native window ({{ interface("nsIWidgets") }}), and its implementation must be very understanding of what may be completely invalid pointers in those parameters.{{ NoteEnd() }}</p>
<pre class="eval">
boolean calculateZPosition(
  in nsIXULWindow inWindow,
  in unsigned long inPosition,
  in nsIWidget inBelow,
  out unsigned long outPosition,
  out nsIWidget outBelow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>inWindow</code></dt>
  <dd>
    The window in question.</dd>
  <dt>
    <code>inPosition</code></dt>
  <dd>
    Requested position one of the zLevel constants. <code>zLevelTop</code> send the window to the top window, <code>zLevelBottom</code> to the bottom. If set to <code>zLevelBelow</code> the window will be placed below ioBelow. The value of inBelow will be ignored for <code>zLevelTop</code> and <code>zLevelBottom</code>.)</dd>
  <dt>
    <code>inBelow</code></dt>
  <dd>
    If inPosition is set to <code>zLevelBelow</code>, the window below which inWindow wants to be placed. Otherwise this variable is ignored.</dd>
  <dt>
    <code>outPosition</code></dt>
  <dd>
    Constrained position, values like inPosition.</dd>
  <dt>
    <code>outBelow</code></dt>
  <dd>
    The window below which <code>inWindow</code> should be placed, if outPosition equals <code>zLevelBelow</code>. Otherwise this value will be <code>null</code>.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>PR_TRUE if the position returned is different from the position given.</p>
<h3 id="getEnumerator()" name="getEnumerator()">getEnumerator()</h3>
<p>Return an enumerator which iterates over all windows of type <code>aWindowType</code> from the oldest window to the youngest.</p>
<pre class="eval">
nsISimpleEnumerator getEnumerator(
  in wstring aWindowType
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindowType</code></dt>
  <dd>
    The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML &lt;{{ XULElem("window") }}&gt; element.) If <code>null</code>, all windows will be enumerated.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>An enumerator of {{ interface("nsIDOMWindow") }}s.</p>
<h3 id="getMostRecentWindow()" name="getMostRecentWindow()">getMostRecentWindow()</h3>
<p>This is a shortcut for simply fetching the first window in front to back order.</p>
<pre class="eval">
nsIDOMWindow getMostRecentWindow(
  in wstring aWindowType
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindowType</code></dt>
  <dd>
    Return the topmost window of this type. ("type" is the |windowtype| attribute of the XML &lt;{{ XULElem("window") }}&gt; element.) If <code>null</code>, return the topmost window of any type.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>The topmost window.</p>
<div class="geckoVersionNote" style="undefined">
  <p>{{ gecko_callout_heading("8.0") }}</p>
  <p>Starting in Gecko 8.0 {{ geckoRelease("8.0") }}, the returned value is an {{ interface("nsIDOMWindow") }}; previously, it was an {{ interface("nsIDOMWindowInternal") }}. You may need to update your code or recompile binary components, if they use this method.</p>
</div>
<h3 id="getOuterWindowWithId()" name="getOuterWindowWithId()">getOuterWindowWithId()</h3>
<p>Return the outer window with the given ID, if any.</p>
<pre class="eval">
nsIDOMWindow getOuterWindowWithId(
  in unsigned long long aOuterWindowID
);
</pre>
<h4 id="Parameters" name="Parameters">Parameters</h4>
<dl>
  <dt>
    <code>aOuterWindowID</code></dt>
  <dd>
    The id of the outer window, e.g., as obtained by <code><a href="/en-US/docs/XPCOM_Interface_Reference/nsIDOMWindowUtils#outerWindowID" title="/en-US/docs/XPCOM_Interface_Reference/nsIDOMWindowUtils#outerWindowID">nsIDOMWindowUtils.outerWindowID</a></code>.</dd>
</dl>
<h4 id="Return_value" name="Return_value">Return value</h4>
<p>The DOM window with the given ID. If no window with the ID exists, or the window exists but it is an inner window, null is returned instead. See also: <a href="/en-US/docs/Inner_and_outer_windows" title="/en-US/docs/Inner_and_outer_windows">Inner and outer windows</a>.</p>
<h3 id="getXULWindowEnumerator()" name="getXULWindowEnumerator()">getXULWindowEnumerator()</h3>
<p>Identical to {{ manch("getEnumerator") }} except it returns <code>{{ Interface("nsIXULWindow") }}</code> instead of <code>{{ Interface("nsIDOMWindow") }}</code>.</p>
<pre class="eval">
nsISimpleEnumerator getXULWindowEnumerator(
  in wstring aWindowType
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindowType</code></dt>
  <dd>
    The returned enumerator will enumerate only windows of this type; that is, the {{ XULAttr("windowtype") }} attribute of the XUL {{ XULElem("window") }} element. If <code>null</code>, all windows are enumerated.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>An enumerator of {{ interface("nsIXULWindow") }}s.</p>
<p>{{ method_noscript("getZLevel") }}</p>
<p>Return the window's Z level (as defined in {{ interface("nsIXULWindow") }}).</p>
<pre class="eval">
PRUint32 getZLevel(
  in nsIXULWindow aWindow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window in question.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p><code>aWindow</code>'s z level.</p>
<h3 id="getZOrderDOMWindowEnumerator()" name="getZOrderDOMWindowEnumerator()">getZOrderDOMWindowEnumerator()</h3>
<p>Return an enumerator which iterates over all windows of type <code>aWindowType</code> in their z (front-to-back) order. Note this interface makes no requirement that a window couldn't be revisited if windows are re-ordered while z-order enumerators are active.</p>
<pre class="eval">
nsISimpleEnumerator getZOrderDOMWindowEnumerator(
  in wstring aWindowType,
  in boolean aFrontToBack
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindowType</code></dt>
  <dd>
    The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML &lt;{{ XULElem("window") }}&gt; element.) If <code>null</code>, all windows will be enumerated.</dd>
  <dt>
    <code>aFrontToBack</code></dt>
  <dd>
    If <code>true</code>, the enumerator enumerates windows in order from front to back. Back to front if <code>false</code>.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>An enumerator of {{ interface("nsIDOMWindow") }}s.</p>
<div class="warning">
  <p>This method may not work on Linux or Mac (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=462222">bug 462222</a>) nor on OS2 (<a href="https://bugzilla.mozilla.org/show_bug.cgi?id=370134">bug 370134</a>) - please check those bugs before relying on it.&nbsp; More information can be found by searching mxr for <code>BROKEN_WM_Z_ORDER</code>)</p>
</div>
<h3 id="getZOrderXULWindowEnumerator()" name="getZOrderXULWindowEnumerator()">getZOrderXULWindowEnumerator()</h3>
<p>Identical to {{ manch("getZOrderDOMWindowEnumerator") }} except returns an enumerator of <code>{{ Interface("nsIXULWindow") }}</code>.</p>
<pre class="eval">
nsISimpleEnumerator getZOrderXULWindowEnumerator(
  in wstring aWindowType,
  in boolean aFrontToBack
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindowType</code></dt>
  <dd>
    The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML &lt;{{ XULElem("window") }}&gt; element.) If <code>null</code>, all windows will be enumerated.</dd>
  <dt>
    <code>aFrontToBack</code></dt>
  <dd>
    If <code>true</code>, the enumerator enumerates windows in order from front to back. Back to front if <code>false</code>.</dd>
</dl>
<h6 id="Return_value" name="Return_value">Return value</h6>
<p>An enumerator of {{ interface("nsIXULWindow") }}s.</p>
<p>{{ method_noscript("registerWindow") }}</p>
<p>Add the window to the list of known windows. Listeners (see {{ manch("addListener") }}) will be notified through their onOpenWindow method.</p>
<pre class="eval">
void registerWindow(
  in nsIXULWindow aWindow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window to add.</dd>
</dl>
<h3 id="removeListener()" name="removeListener()">removeListener()</h3>
<p>Unregister a listener of window status changes.</p>
<pre class="eval">
void removeListener(
  in nsIWindowMediatorListener aListener
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aListener</code></dt>
  <dd>
    The listener to unregister.</dd>
</dl>
<p>{{ method_noscript("setZLevel") }}</p>
<p>Set the window's Z level (as defined in {{ interface("nsIXULWindow") }}). The implementation will reposition the window as necessary to match its new Z level. The implementation will assume a window's Z level to be {{ interface("nsIXULWindow") }}.normalZ until it has been informed of a different level.</p>
<pre class="eval">
void setZLevel(
  in nsIXULWindow aWindow,
  in PRUint32 aZLevel
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window in question.</dd>
  <dt>
    <code>aZLevel</code></dt>
  <dd>
    The window's new Z level.</dd>
</dl>
<p>{{ method_noscript("setZPosition") }}</p>
<p>A window has been positioned behind another. Inform WindowMediator.</p>
<pre class="eval">
void setZPosition(
  in nsIXULWindow inWindow,
  in unsigned long inPosition,
  in nsIXULWindow inBelow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>inWindow</code></dt>
  <dd>
    The window in question.</dd>
  <dt>
    <code>inPosition</code></dt>
  <dd>
    Requested position one of the zLevel constants. <code>zLevelTop</code> send the window to the top window, <code>zLevelBottom</code> to the bottom. If set to <code>zLevelBelow</code> the window will be placed below ioBelow. The value of inBelow will be ignored for <code>zLevelTop</code> and <code>zLevelBottom</code>.)</dd>
  <dt>
    <code>inBelow</code></dt>
  <dd>
    The window inWindow is behind, if <code>zLevelBelow</code>.</dd>
</dl>
<p>{{ method_noscript("unregisterWindow") }}</p>
<p>Remove the window from the list of known windows. Listeners (see {{ manch("addListener") }}) will be be notified through their onCloseWindow method.</p>
<pre class="eval">
void unregisterWindow(
  in nsIXULWindow aWindow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window to remove.</dd>
</dl>
<p>{{ method_noscript("updateWindowTimeStamp") }}</p>
<p>Call this method when a window gains focus. It's a primitive means of determining the most recent window. It's no longer necessary and it really should be removed.</p>
<pre class="eval">
void updateWindowTimeStamp(
  in nsIXULWindow aWindow
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window which has gained focus.</dd>
</dl>
<p>{{ method_noscript("updateWindowTitle") }}</p>
<p>Call this method when a window's title changes. Listeners (see {{ manch("addListener") }}) will be notified through their onWindowTitleChange method.</p>
<pre class="eval">
void updateWindowTitle(
  in nsIXULWindow aWindow,
  in wstring inTitle 
);
</pre>
<h6 id="Parameters" name="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>aWindow</code></dt>
  <dd>
    The window whose title has changed.</dd>
  <dt>
    <code>inTitle</code></dt>
  <dd>
    The window's new title.</dd>
</dl>
<h2 id="Examples" name="Examples">Examples</h2>
<p>In the examples below, <code>type</code> specifies the type of windows you want to search. You can specify the type of your window by putting a <code>{{ XULAttr("windowtype") }}</code> attribute on the top-level element, like <code>&lt;{{ XULElem("window") }}&gt;</code> or <code>&lt;{{ XULElem("dialog") }}&gt;</code>.</p>
<p>Browser windows have a window type of <code>navigator:browser</code>. To search all windows, regardless of their type, pass an empty string, <code>""</code>.</p>
<h3 id="Getting_most_recent_window" name="Getting_most_recent_window">Getting most recent window</h3>
<p>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 (for example your extension's Options dialog) is already open.</p>
<p><code>getMostRecentWindow</code> returns a <code>ChromeWindow</code> object, or <code>null</code>, if there are no windows of a given type open.</p>
<pre class="brush: js">
var wm = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                   .getService(Components.interfaces.nsIWindowMediator);
var win = wm.getMostRecentWindow(type);
</pre>
<h3 id="Changing_an_nsIDOMWindow_to_an_nsIXULWindow">Changing an nsIDOMWindow to an nsIXULWindow</h3>
<p>If you need an {{ interface("nsIXULWindow") }}, you should use {{ manch("getXULWindowEnumerator") }}. However, if you are looking for the <em>most recent</em> {{ interface("nsIXULWindow") }}, it can be helpful to get the corresponding {{ interface("nsIXULWindow") }} from the {{ interface("nsIDOMWindow") }} returned by {{ manch("getMostRecentWindow") }}.</p>
<pre class="brush: js">
win.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
      .getInterface(Components.interfaces.nsIWebNavigation)
      .QueryInterface(Components.interfaces.nsIDocShellTreeItem).treeOwner
      .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
      .getInterface(Components.interfaces.nsIXULWindow) 
</pre>
<h3 id="Enumerating_windows" name="Enumerating_windows">Enumerating windows</h3>
<p>The following code can be used if you need to do something for each open window of a particular type. For example, you could use it in the "OK" handler of your Options dialog to apply the new settings to each open browser window.</p>
<pre class="brush: js">
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();
  // <code>win</code> is [Object ChromeWindow] (just like <code>window</code>), do something with it
}
</pre>
<p>This code iterates over all windows of the specified type, where <var>type</var> you specify is the window type. If, for example, you wish to enumerate all browser windows, you would specify "navigator:browser". If you want to enumerate all windows regardless of type, specify <code>null</code>.</p>
<div class="note">
  <strong>Note:</strong> 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.</div>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="/en/Working_with_windows_in_chrome_code" title="en/Working_with_windows_in_chrome_code">Working with windows in chrome code</a></li>
</ul>
<p>{{ languages( { "ja": "ja/NsIWindowMediator" } ) }}</p>