The two most common uses of nsIWindowMediator are, enumerating all windows of a given type and getting the most recent / any window of a given type.

Implemented by: @mozilla.org/appshell/window-mediator;1 as a service:

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

Method overview

Constants

Methods

addListener()

Register a listener for window status changes.

void addListener(
  in nsIWindowMediatorListener aListener
);

Parameters

aListener

The listener to register.

var {Cc: classes, Ci: interfaces} = Components;

var windowListener = {
    onOpenWindow: function (aWindow) {
        // Wait for the window to finish loading
        let domWindow = aWindow.QueryInterface(Ci.nsIInterfaceRequestor).getInterface(Ci.nsIDOMWindowInternal || Ci.nsIDOMWindow);
        domWindow.addEventListener("load", function () {
            domWindow.removeEventListener("load", arguments.callee, false); //this removes this load function from the window
            //window has now loaded now do stuff to it
            //as example this will add a function to listen to tab select and will fire alert in that window
            if (domWindow.gBrowser && domWindow.gBrowser.tabContainer) {
                domWindow.gBrowser.tabContainer.addEventListener('TabSelect', function () {
                    domWindow.alert('tab was selected')
                }, false);
            }
        }, false);
    },
    onCloseWindow: function (aWindow) {},
    onWindowTitleChange: function (aWindow, aTitle) {}
};

//to register
Services.wm.addListener(windowListener);

//Services.wm.removeListener(windowListener); //once you want to remove this listener execute removeListener, currently its commented out so you can copy paste this code in scratchpad and see it work

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.

boolean calculateZPosition(
  in nsIXULWindow inWindow,
  in unsigned long inPosition,
  in nsIWidget inBelow,
  out unsigned long outPosition,
  out nsIWidget outBelow
);

Parameters

inWindow

The window in question.

inPosition

Requested position one of the zLevel constants. zLevelTop send the window to the top window, zLevelBottom to the bottom. If set to zLevelBelow the window will be placed below ioBelow. The value of inBelow will be ignored for zLevelTop and zLevelBottom.)

inBelow

If inPosition is set to zLevelBelow, the window below which inWindow wants to be placed. Otherwise this variable is ignored.

outPosition

Constrained position, values like inPosition.

outBelow

The window below which inWindow should be placed, if outPosition equals zLevelBelow. Otherwise this value will be null.

Return value

PR_TRUE if the position returned is different from the position given.

getEnumerator()

Return an enumerator which iterates over all windows of type aWindowType from the oldest window to the youngest.

nsISimpleEnumerator getEnumerator(
  in wstring aWindowType
);

Parameters

aWindowType

The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML <window> element.) If null, all windows will be enumerated.

Return value

An enumerator of nsIDOMWindows.

getMostRecentWindow()

This is a shortcut for simply fetching the first window in front to back order.

nsIDOMWindow getMostRecentWindow(
  in wstring aWindowType
);

Parameters

aWindowType

Return the topmost window of this type. ("type" is the |windowtype| attribute of the XML <window> element.) If null, return the topmost window of any type.

Return value

The topmost window.

getOuterWindowWithId()

Return the outer window with the given ID, if any.

nsIDOMWindow getOuterWindowWithId(
  in unsigned long long aOuterWindowID
);

Parameters

aOuterWindowID

The id of the outer window, e.g., as obtained by nsIDOMWindowUtils.outerWindowID.

Return value

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: Inner and outer windows.

windowMediator = Components.classes["@mozilla.org/appshell/window-mediator;1"]
    .getService(Components.interfaces.nsIWindowMediator);

if (!windowMediator.getOuterWindowWithId) {

  windowMediator.getOuterWindowWithId = function (aOuterWindowID) {

     let win = this.getMostRecentWindow();
     let winUtil = win.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
         .getInterface(Components.interfaces.nsIDOMWindowUtils);

     return winUtil.getOuterWindowWithId(aOuterWindowID);
  }

}

getXULWindowEnumerator()

Identical to getEnumerator() except it returns nsIXULWindow instead of nsIDOMWindow.

nsISimpleEnumerator getXULWindowEnumerator(
  in wstring aWindowType
);

Parameters

aWindowType

The returned enumerator will enumerate only windows of this type; that is, the windowtype attribute of the XUL window element. If null, all windows are enumerated.

Return value

An enumerator of nsIXULWindows.

Return the window's Z level (as defined in nsIXULWindow).

PRUint32 getZLevel(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window in question.

Return value

aWindow's z level.

getZOrderDOMWindowEnumerator()

Return an enumerator which iterates over all windows of type aWindowType 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.

nsISimpleEnumerator getZOrderDOMWindowEnumerator(
  in wstring aWindowType,
  in boolean aFrontToBack
);

Parameters

aWindowType

The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML <window> element.) If null, all windows will be enumerated.

aFrontToBack

If true, the enumerator enumerates windows in order from front to back. Back to front if false.

Return value

An enumerator of nsIDOMWindows.

getZOrderXULWindowEnumerator()

Identical to getZOrderDOMWindowEnumerator() except returns an enumerator of nsIXULWindow.

nsISimpleEnumerator getZOrderXULWindowEnumerator(
  in wstring aWindowType,
  in boolean aFrontToBack
);

Parameters

aWindowType

The returned enumerator will enumerate only windows of this type. ("type" is the |windowtype| attribute of the XML <window> element.) If null, all windows will be enumerated.

aFrontToBack

If true, the enumerator enumerates windows in order from front to back. Back to front if false.

Return value

An enumerator of nsIXULWindows.

Add the window to the list of known windows. Listeners (see addListener()) will be notified through their onOpenWindow method.

void registerWindow(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window to add.

removeListener()

Unregister a listener of window status changes.

void removeListener(
  in nsIWindowMediatorListener aListener
);

Parameters

aListener

The listener to unregister.

Set the window's Z level (as defined in 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 nsIXULWindow.normalZ until it has been informed of a different level.

void setZLevel(
  in nsIXULWindow aWindow,
  in PRUint32 aZLevel
);

Parameters

aWindow

The window in question.

aZLevel

The window's new Z level.

A window has been positioned behind another. Inform WindowMediator.

void setZPosition(
  in nsIXULWindow inWindow,
  in unsigned long inPosition,
  in nsIXULWindow inBelow
);

Parameters

inWindow

The window in question.

inPosition

Requested position one of the zLevel constants. zLevelTop send the window to the top window, zLevelBottom to the bottom. If set to zLevelBelow the window will be placed below ioBelow. The value of inBelow will be ignored for zLevelTop and zLevelBottom.)

inBelow

The window inWindow is behind, if zLevelBelow.

Remove the window from the list of known windows. Listeners (see addListener()) will be be notified through their onCloseWindow method.

void unregisterWindow(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window to remove.

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.

void updateWindowTimeStamp(
  in nsIXULWindow aWindow
);

Parameters

aWindow

The window which has gained focus.

Call this method when a window's title changes. Listeners (see addListener()) will be notified through their onWindowTitleChange method.

void updateWindowTitle(
  in nsIXULWindow aWindow,
  in wstring inTitle
);

Parameters

aWindow

The window whose title has changed.

inTitle

The window's new title.

Examples

In the examples below, type specifies the type of windows you want to search. You can specify the type of your window by putting a windowtype attribute on the top-level element, like <window> or <dialog>.

Browser windows have a window type of navigator:browser. 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 (for example your extension's Options dialog) is already open.

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

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

Changing an nsIDOMWindow to an nsIXULWindow

If you need an nsIXULWindow, you should use getXULWindowEnumerator(). However, if you are looking for the most recent nsIXULWindow, it can be helpful to get the corresponding nsIXULWindow from the nsIDOMWindow returned by getMostRecentWindow().

win.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
      .getInterface(Components.interfaces.nsIWebNavigation)
      .QueryInterface(Components.interfaces.nsIDocShellTreeItem).treeOwner
      .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
      .getInterface(Components.interfaces.nsIXULWindow)

Enumerating windows

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.

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
}

This code iterates over all windows of the specified type, where type 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 null.

See also

• Working with windows in chrome code