Bug 589057- Document the window-utils module. r=atul, a0.7=myk (from bug 569708 comment 4)
authorDrew Willcoxon <adw@mozilla.com>
Mon, 23 Aug 2010 19:26:17 -0700
changeset 760 fd065f7b5bb649264a589bc0f504dece85e6562f
parent 759 9cc530cc79dcd8136f0c25d27f8ae4c60c874330
child 761 91db3981a6eb3722c72f95cb51d04a3d2c995747
push id284
push userdwillcoxon@mozilla.com
push dateTue, 24 Aug 2010 02:26:44 +0000
reviewersatul
bugs589057, 569708
Bug 589057- Document the window-utils module. r=atul, a0.7=myk (from bug 569708 comment 4)
packages/jetpack-core/docs/window-utils.md
new file mode 100644
--- /dev/null
+++ b/packages/jetpack-core/docs/window-utils.md
@@ -0,0 +1,81 @@
+<!-- contributed by Drew Willcoxon [adw@mozilla.com] -->
+
+The `window-utils` module provides helpers for accessing and tracking
+application windows.  These windows implement the [`nsIDOMWindow`][nsIDOMWindow]
+interface.
+
+[nsIDOMWindow]: http://mxr.mozilla.org/mozilla-central/source/dom/interfaces/base/nsIDOMWindow.idl
+
+
+Constructors
+------------
+
+<api name="WindowTracker">
+@constructor
+  A `WindowTracker` object listens for openings and closings of application
+  windows.
+@param delegate {object}
+  An object that implements `onTrack()` and `onUntrack()` methods.
+</api>
+
+`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**
+
+    var delegate = {
+      onTrack: function (window) {
+        console.log("Tracking a window: " + window.document.URL);
+        // Modify the window!
+      },
+      onUntrack: function (window) {
+        console.log("Untracking a window: " + window.document.URL);
+        // Undo your modifications!
+      }
+    };
+    var winUtils = require("window-utils");
+    var tracker = new winUtils.WindowTracker(delegate);
+
+
+Functions
+---------
+
+<api name="windowIterator">
+@function
+  An iterator for windows currently open in the application.
+</api>
+
+**Example**
+
+    var winUtils = require("window-utils");
+    for (window in winUtils.windowIterator())
+      console.log("An open window! " + window.document.URL);
+
+<api name="closeOnUnload">
+@function
+  Marks an application window to be closed when the program is unloaded.
+@param window {window}
+  The window to close.
+</api>