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.
getInnerId(window)
Returns the ID of the specified window's current inner window.
This function wraps
nsIDOMWindowUtils.currentInnerWindowID
.
The window whose inner window we are interested in.
getOuterId(window)
Returns the ID of the specified window's outer window.
This function wraps
nsIDOMWindowUtils.outerWindowID
.
The window whose outer window we are interested in.
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
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
getWindowDocShell(window)
Returns the
nsIDocShell
for the tabbrowser
element.
getWindowLoadingContext(window)
Returns the 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
});
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 of the document to be loaded into the window.
Options for the function, with the following properties:
Parent for the new window. Optional, defaults to null
.
Name that is assigned to the window. Optional, defaults to null
.
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: {}
.
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 for the function, with the following properties:
URI of the document to be loaded into the window.
Defaults to "chrome://browser/content/browser.xul"
.
Optional name that is assigned to the window. Defaults to "_blank"
.
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'}
.
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.
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.
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"
.
getWindowTitle(window)
Get the title of the document hosted by the given window
This document's title.
isXULBrowser(window)
Returns true if the given window is a XUL window.
getFocusedWindow()
Gets the child window within the topmost browser window that is focused.
See
nsIFocusManager
for more details.
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.
getFrames(window)
Get the frames contained by the given window.
Array of frames.