window-utils

The window-utils module provides helpers for accessing and tracking application windows. These windows implement the nsIDOMWindow interface.

API Reference

Classes

WindowTracker

WindowTracker objects make it easy to "monkeypatch" windows when a program is loaded and "un-monkeypatch" those windows when the program is unloaded. For example, if a Firefox add-on needs to add a status bar icon to all browser windows, it can use a single WindowTracker object to gain access to windows when they are opened and closed and also when the add-on is loaded and unloaded.

When a window is opened or closed, a WindowTracker notifies its delegate object, which is passed to the constructor. The delegate is also notified of all windows that are open at the time that the WindowTracker is created and all windows that are open at the time that the WindowTracker is unloaded. The caller can therefore use the same code to act on all windows, regardless of whether they are currently open or are opened in the future, or whether they are closed while the parent program is loaded or remain open when the program is unloaded.

When a window is opened or when a window is open at the time that the WindowTracker is created, the delegate's onTrack() method is called and passed the window.

When a window is closed or when a window is open at the time that the WindowTracker is unloaded, the delegate's onUntrack() method is called and passed the window. (The WindowTracker is unloaded when its its unload() method is called, or when its parent program is unloaded, disabled, or uninstalled, whichever comes first.)

Example

?
1
2
3
4
5
6
7
8
9
10
11
12
var delegate = {
  onTrack: function (window) {
    console.log("Tracking a window: " + window.location);
    // Modify the window!
  },
  onUntrack: function (window) {
    console.log("Untracking a window: " + window.location);
    // Undo your modifications!
  }
};
var winUtils = require("window-utils");
var tracker = new winUtils.WindowTracker(delegate);
Constructors
WindowTracker(delegate)

A WindowTracker object listens for openings and closings of application windows.

delegate : object

An object that implements onTrack() and onUntrack() methods.

onTrack : function

A function to be called when a window is open or loads, with the window as the first and only argument.

[ onUntrack : function ]

A function to be called when a window unloads, with the window as the first and only argument.

Functions

windowIterator()

An iterator for windows currently open in the application. Only windows whose document is already loaded will be dispatched.

Example

?
1
2
3
var winUtils = require("window-utils");
for (window in winUtils.windowIterator())
  console.log("An open window! " + window.location);

closeOnUnload(window)

Marks an application window to be closed when the program is unloaded.

window : window

The window to close.