diff options
Diffstat (limited to 'tools/addon-sdk-1.3/packages/addon-kit/docs/windows.md')
-rw-r--r-- | tools/addon-sdk-1.3/packages/addon-kit/docs/windows.md | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.3/packages/addon-kit/docs/windows.md b/tools/addon-sdk-1.3/packages/addon-kit/docs/windows.md new file mode 100644 index 0000000..a5bed95 --- /dev/null +++ b/tools/addon-sdk-1.3/packages/addon-kit/docs/windows.md @@ -0,0 +1,187 @@ +<!-- contributed by Felipe Gomes [felipc@gmail.com] --> + + +The `windows` module provides easy access to browser windows, their +tabs, and open/close related functions and events. + +This module currently only supports browser windows and does not provide +access to non-browser windows such as the Bookmarks Library, preferences +or other non-browser windows created via add-ons. + +<api name="browserWindows"> +@property {List} +An object that contains various properties and methods to access +functionality from browser windows, such as opening new windows, accessing +their tabs or switching the current active window. + +`browserWindows` provides access to all the currently open browser windows: + + var windows = require("windows"); + for each (var window in windows.browserWindows) { + console.log(window.title); + } + + console.log(windows.browserWindows.length); + +Object emits all the events listed under "Events" section. + +####Examples#### + + var windows = require("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."); + }); + +<api name="activeWindow"> +@property {BrowserWindow} + +The currently active window. This property is read-only. + +**Example** + + // get + var windows = require("windows"); + console.log("title of active window is " + + windows.browserWindows.activeWindow.title); + + anotherWindow.activate(); + // set + windows.activeWindow == anotherWindow // true +</api> + +</api> + +<api name="open"> +@function +Open a new window. + + var windows = require("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 widgets = require("widget"); + var windows = require("windows").browserWindows; + + var example = windows.open("http://www.example.com"); + + var widget = widgets.Widget({ + id: "close-window", + label: "Close window", + contentURL: "http://www.mozilla.org/favicon.ico", + onClick: function() { + example.close(); + } + }); + +@param options {object} +An object containing configurable options for how this window will be opened, +as well as a callback for being notified when the window has fully opened. + +If the only option being used is `url`, then a bare string URL can be passed to +`open` instead of specifying it as a property of the `options` object. + +@prop url {string} +String URL to be opened in the new window. +This is a required property. + +@prop [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. + +@prop [onClose] {function} +A callback function that is called when the window will be called. +This is an optional property. + +@returns {BrowserWindow} +</api> + +<api name="BrowserWindow"> +@class +A `BrowserWindow` instance represents a single open window. They can be +retrieved from the `browserWindows` property exported by this module. + + var windows = require("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 each (var window in windows) { + console.log(window.title); + } + + // close the active window + windows.activeWindow.close(); + + windows.activeWindow.close(function() { + console.log("The active window was closed"); + }); + +<api name="title"> +@property {string} +The current title of the window. Usually the title of the active tab, +plus an app identifier. +This property is read-only. +</api> + +<api name="tabs"> +@property {TabList} +A live list of tabs in this window. This object has the same interface as the +[`tabs` API](packages/addon-kit/docs/tabs.html), except it contains only the +tabs in this window, not all tabs in all windows. This property is read-only. +</api> + +<api name="activate"> +@method +Makes window active, which will focus that window and bring it to the +foreground. +</api> + +<api name="close"> +@method +Close the window. + +@param [callback] {function} +A function to be called when the window finishes its closing process. +This is an optional argument. +</api> + +</api> + +<api name="open"> +@event +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. +@argument {Window} +Listeners are passed the `window` object that triggered the event. +</api> + +<api name="close"> +@event +Event emitted when a window is closed. +@argument {Window} +Listeners are passed the `window` object that triggered the event. +</api> |