windows

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Stable

Enumerate and examine open browser windows, open new windows, and listen for window events.

Usage

The windows module provides basic functions for working with browser windows. With this module, you can:

Private windows

If your add-on has not opted into private browsing, then you won't see any private browser windows. Private browser windows won't appear in the browserWindows property, you won't receive any window events, and you won't be able to open private windows.

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.

Converting to chrome windows

To convert from the BrowserWindow objects used in this API to the chrome window objects used in the window/utils API, use the viewFor() function exported by the viewFor module.

To convert back the other way, from a chrome window to a BrowserWindow object, use the modelFor() function, exported by the modelFor module.

Here's an example converting from a high-level BrowserWindow to a chrome window, and then back the other way:

var { modelFor } = require("sdk/model/core");
var { viewFor } = require("sdk/view/core");
var browserWindows = require("sdk/windows").browserWindows;
function convertToChromeAndBack(browserWindow) {
  // get the chrome window for this BrowserWindow
  var chromeWindow = viewFor(browserWindow);
  // now we can use the chrome window API
  console.log(chromeWindow.document.location.href);
  // -> "chrome://browser/content/browser.xul"
  // convert back to the high-level window
  var highLevelWindow = modelFor(chromeWindow);
  // now we can use the SDK's high-level window API
  console.log(highLevelWindow.title);
}
browserWindows.on("open", convertToChromeAndBack);

Note that directly accessing low-level chrome objects like this means you're no longer protected by the compatibility guarantees made by the SDK's high-level APIs. In particular, depending on what you do with these objects, your code might not work with multiprocess Firefox.

Globals

Functions

open(options)

Open a new window.

var windows = require("sdk/windows").browserWindows;
// Open a new window.
windows.open("http://www.example.com");
// Open a new window and set a listener for "open" event.
windows.open({
  url: "http://www.example.com",
  onOpen: function(window) {
    // do stuff like listen for content
    // loading.
  }
});

Returns the window that was opened:

var windows = require("sdk/windows").browserWindows;
var example = windows.open("http://www.example.com");
require("sdk/ui/button/action").ActionButton({
  id: "read",
  label: "Read",
  icon: "./read.png",
  onClick: function() {
    example.close();
  }
});

This example uses the action button API, which is only available from Firefox 29 onwards.

Parameters

options : object
Required options:

Name Type  
url string

String URL to be opened in the new window. This is a required property.

isPrivate boolean

Boolean which will determine whether the new window should be private or not. If your add-on does not support private browsing this will have no effect. See the private-browsing documentation for more information.

Optional options:

Name Type  
onOpen function

A callback function that is called when the window has opened. This does not mean that the URL content has loaded, only that the window itself is fully functional and its properties can be accessed. This is an optional property.

onClose function

A callback function that is called when the window will be called. This is an optional property.

onActivate function

A callback function that is called when the window is made active. This is an optional property.

onDeactivate function

A callback function that is called when the window is made inactive. This is an optional property.

Returns

BrowserWindow :

Properties

browserWindows

browserWindows provides access to all the currently open browser windows as BrowserWindow objects.

var windows = require("sdk/windows");
for (let window of windows.browserWindows) {
  console.log(window.title);
}
console.log(windows.browserWindows.length);

The currently active window is given by BrowserWindows.activeWindow:

var windows = require("sdk/windows").browserWindows;
windows.on('activate', function(window) {
  console.log("A window was activated.");
  var activeWindowTitle = windows.activeWindow.title;
  console.log("Active window title is: " + activeWindowTitle);
});

Events

The browserWindows property emits the following events which can be listened to using its on function.

var windows = require("sdk/windows").browserWindows;
// add a listener to the 'open' event
windows.on('open', function(window) {
  myOpenWindows.push(window);
});
// add a listener to the 'close' event
windows.on('close', function(window) {
  console.log("A window was closed.");
});
// add a listener to the 'activate' event
windows.on('activate', function(window) {
  console.log("A window was activated.");
});
// add a listener to the 'deactivate' event
windows.on('deactivate', function(window) {
  console.log("A window was deactivated.");
});

open

Event emitted when a new window is open. This does not mean that the content has loaded, only that the browser window itself is fully visible to the user.

Arguments

Window : Listeners are passed the window object that triggered the event.

close

Event emitted when a window is closed. You can't always rely on receiving the close event for every open window. In particular, if the user quits the browser then it's possible that your add-on will be unloaded before all windows are closed.

Arguments

Window : Listeners are passed the window object that triggered the event.

activate

Event emitted when an inactive window is made active.

Arguments

Window : Listeners are passed the window object that has become active.

deactivate

Event emitted when the active window is made inactive.

Arguments

Window : Listeners are passed the window object that has become inactive.

BrowserWindow

A BrowserWindow instance represents a single open window. They can be retrieved from the browserWindows property exported by this module.

var windows = require("sdk/windows").browserWindows;
//Print how many tabs the current window has
console.log("The active window has " +
            windows.activeWindow.tabs.length +
            " tabs.");
// Print the title of all browser windows
for (let window of windows) {
  console.log(window.title);
}
// close the active window
windows.activeWindow.close(function() {
  console.log("The active window was closed");
});

Methods

activate()

Makes window active, which will focus that window and bring it to the foreground.

close(callback)

Close the window.

Parameters

callback : function
A function to be called when the window finishes its closing process. This is an optional argument.

Properties

title

The current title of the window. Usually the title of the active tab, plus an app identifier. This property is read-only.

tabs

A live list of tabs in this window. This object has the same interface as the tabs API, except it contains only the tabs in this window, not all tabs in all windows. This property is read-only.

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, carlin-scott, XrXrXr, freaktechnik
 Last updated by: wbamberg,