unstable

window/utils

The window/utils module provides helper functions for working with application windows.

Private Windows

With this module your add-on will see private browser windows even if it has not explicitly opted into private browsing, so you need to take care not to store any user data derived from private browser windows.

The exception is the windows() function which returns an array of currently opened windows. Private windows will not be included in this list if your add-on has not opted into private browsing.

To learn more about private windows, how to opt into private browsing, and how to support private browsing, refer to the documentation for the private-browsing module.

API Reference

Functions

getMostRecentBrowserWindow()

Get the topmost browser window, as an nsIDOMWindow instance.

Returns: nsIDOMWindow

getInnerId(window)

Returns the ID of the specified window's current inner window. This function wraps nsIDOMWindowUtils.currentInnerWindowID.

window : nsIDOMWindow

The window whose inner window we are interested in.

Returns: ID

getOuterId(window)

Returns the ID of the specified window's outer window. This function wraps nsIDOMWindowUtils.outerWindowID.

window : nsIDOMWindow

The window whose outer window we are interested in.

Returns: ID

getXULWindow(window)

Returns the nsIXULWindow for the given nsIDOMWindow:

var { Ci } = require('chrome');
var utils = require('sdk/window/utils');
var active = utils.getMostRecentBrowserWindow();
active instanceof Ci.nsIXULWindow // => false
utils.getXULWindow(active) instanceof Ci.nsIXULWindow // => true
window : nsIDOMWindow
Returns: nsIXULWindow

getBaseWindow(window)

Returns the nsIBaseWindow for the given nsIDOMWindow:

var { Ci } = require('chrome');
var utils = require('sdk/window/utils');
var active = utils.getMostRecentBrowserWindow();
active instanceof Ci.nsIBaseWindow // => false
utils.getBaseWindow(active) instanceof Ci.nsIBaseWindow // => true
window : nsIDOMWindow
Returns: nsIBaseWindow

getWindowDocShell(window)

Returns the nsIDocShell for the tabbrowser element.

window : nsIDOMWindow
Returns: nsIDocShell

getWindowLoadingContext(window)

Returns the nsILoadContext.

window : nsIDOMWindow
Returns: nsILoadContext

backgroundify(window, options)

This function takes the specified nsIDOMWindow and removes it from the application's window registry, so it won't appear in the OS specific window lists for the application.

var { backgroundify, open } = require('sdk/window/utils');
var bgwin = backgroundify(open('data:text/html,Hello backgroundy'));

Optionally more configuration options may be passed via a second options argument. If options.close is false, the unregistered window won't automatically be closed on application quit, preventing the application from quitting. You should make sure to close all such windows manually.

var { backgroundify, open } = require('sdk/window/utils');
var bgwin = backgroundify(open('data:text/html,Foo'), {
  close: false
});
window : nsIDOMWindow
options : object
close : boolean

Whether to close the window on application exit. Defaults to true.

open(uri, options)

This function is used to open top level (application) windows. It takes the uri of the window document as its first argument and an optional hash of options as its second argument.

var { open } = require('sdk/window/utils');
var window = open('data:text/html,Hello Window');

This function wraps nsIWindowWatcher.openWindow.

uri : string

URI of the document to be loaded into the window.

options : object

Options for the function, with the following properties:

parent : nsIDOMWindow

Parent for the new window. Optional, defaults to null.

name : String

Name that is assigned to the window. Optional, defaults to null.

features : Object

Map of features to set for the window, defined like this: { width: 10, height: 15, chrome: true }. See the window.open features documentation for more details.

var { open } = require('sdk/window/utils');
var window = open('data:text/html,Hello Window', {
  name: 'jetpack window',
  features: {
    width: 200,
    height: 50,
    popup: true
  }
});

Optional, defaults to an empty map: {}.

Returns: nsIDOMWindow

openDialog(options)

Opens a top level window and returns its nsIDOMWindow representation. This is the same as open, but you can supply more features. It wraps window.openDialog.

options : object

Options for the function, with the following properties:

url : String

URI of the document to be loaded into the window. Defaults to "chrome://browser/content/browser.xul".

name : String

Optional name that is assigned to the window. Defaults to "_blank".

features : Object

Map of features to set for the window, defined like: { width: 10, height: 15, chrome: true }. For the set of features you can set, see the window.openDialog documentation. Optional, defaults to: {'chrome,all,dialog=no'}.

Returns: nsIDOMWindow

windows()

Returns an array of all currently opened windows. Note that these windows may still be loading.

If your add-on has not opted into private browsing, any private browser windows will not be included in the array.

Returns: Array

Array of nsIDOMWindow instances.

isDocumentLoaded(window)

Check if the given window's document is completely loaded. This means that its "load" event has been fired and all content is loaded, including the whole DOM document, images, and any other sub-resources.

window : nsIDOMWindow
Returns: boolean

true if the document is completely loaded.

isBrowser(window)

Returns true if the given window is a Firefox browser window: that is, its document has a "windowtype" of "chrome://browser/content/browser.xul".

window : nsIDOMWindow
Returns: boolean

getWindowTitle(window)

Get the title of the document hosted by the given window

window : nsIDOMWindow
Returns: String

This document's title.

isXULBrowser(window)

Returns true if the given window is a XUL window.

window : nsIDOMWindow
Returns: boolean

getFocusedWindow()

Gets the child window within the topmost browser window that is focused. See nsIFocusManager for more details.

Returns: nsIDOMWindow

getFocusedElement()

Get the element that is currently focused. This will always be an element within the document loaded in the focused window, or null if no element in that document is focused.

Returns: nsIDOMElement

getFrames(window)

Get the frames contained by the given window.

window : nsIDOMWindow
Returns: Array

Array of frames.