1 files changed, 385 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/tabs.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/tabs.md
new file mode 100644
index 0000000..f1e44df
--- /dev/null
+++ b/tools/addon-sdk-1.7/packages/addon-kit/docs/tabs.md
@@ -0,0 +1,385 @@
+<!-- This Source Code Form is subject to the terms of the Mozilla Public
+   - License, v. 2.0. If a copy of the MPL was not distributed with this
+   - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
+
+<!-- contributed by Dietrich Ayala [dietrich@mozilla.com]  -->
+<!-- edited by Noelle Murata [fiveinchpixie@gmail.com]  -->
+
+The `tabs` module provides easy access to tabs and tab-related events.
+
+The module itself can be used like a basic list of all opened
+tabs across all windows. In particular, you can enumerate it:
+
+    var tabs = require('tabs');
+    for each (var tab in tabs)
+      console.log(tab.title);
+
+You can also access individual tabs by index:
+
+    var tabs = require('tabs');
+
+    tabs.on('ready', function () {
+      console.log('first: ' + tabs[0].title);
+      console.log('last: ' + tabs[tabs.length-1].title);
+    });
+
+You can open a new tab, specifying various properties including location:
+
+    var tabs = require("tabs");
+    tabs.open("http://www.example.com");
+
+You can register event listeners to be notified when tabs open, close, finish
+loading DOM content, or are made active or inactive:
+
+    var tabs = require("tabs");
+
+    // Listen for tab openings.
+    tabs.on('open', function onOpen(tab) {
+      myOpenTabs.push(tab);
+    });
+
+    // Listen for tab content loads.
+    tabs.on('ready', function(tab) {
+      console.log('tab is loaded', tab.title, tab.url)
+    });
+
+You can get and set various properties of tabs (but note that properties
+ relating to the tab's content, such as the URL, will not contain valid
+values until after the tab's `ready` event fires). By setting the `url`
+property you can load a new page in the tab:
+
+    var tabs = require("tabs");
+    tabs.on('activate', function(tab) {
+      tab.url = "http://www.example.com";
+    });
+
+You can attach a [content script](dev-guide/guides/content-scripts/index.html)
+to the page hosted in a tab, and use that to access and manipulate the page's
+content:
+
+    var tabs = require("tabs");
+
+    tabs.on('activate', function(tab) {
+      tab.attach({
+        contentScript: 'self.postMessage(document.body.innerHTML);',
+        onMessage: function (message) {
+          console.log(message);
+        }
+      });
+    });
+
+<api name="activeTab">
+@property {Tab}
+
+The currently active tab in the active window. This property is read-only. To
+activate a `Tab` object, call its `activate` method.
+
+**Example**
+
+    // Get the active tab's title.
+    var tabs = require("tabs");
+    console.log("title of active tab is " + tabs.activeTab.title);
+</api>
+
+<api name="length">
+@property {number}
+The number of open tabs across all windows.
+</api>
+
+<api name="open">
+@function
+Opens a new tab. The new tab will open in the active window or in a new window,
+depending on the `inNewWindow` option.
+
+**Example**
+
+    var tabs = require("tabs");
+
+    // Open a new tab on active window and make tab active.
+    tabs.open("http://www.mysite.com");
+
+    // Open a new tab in a new window and make it active.
+    tabs.open({
+      url: "http://www.mysite.com",
+      inNewWindow: true
+    });
+
+    // Open a new tab on active window in the background.
+    tabs.open({
+      url: "http://www.mysite.com",
+      inBackground: true
+    });
+
+    // Open a new tab as an app tab and do something once it's open.
+    tabs.open({
+      url: "http://www.mysite.com",
+      isPinned: true,
+      onOpen: function onOpen(tab) {
+        // do stuff like listen for content
+        // loading.
+      }
+    });
+
+@param options {object}
+An object containing configurable options for how and where the tab will be
+opened, as well as a listeners for the tab events.
+
+If the only option being used is `url`, then a bare string URL can be passed to
+`open` instead of adding at a property of the `options` object.
+
+@prop [url] {string}
+String URL to be opened in the new tab.
+This is a required property.
+
+@prop [inNewWindow] {boolean}
+If present and true, a new browser window will be opened and the URL will be
+opened in the first tab in that window. This is an optional property.
+
+@prop [inBackground] {boolean}
+If present and true, the new tab will be opened to the right of the active tab
+and will not be active. This is an optional property.
+
+@prop [isPinned] {boolean}
+If present and true, then the new tab will be pinned as an
+[app tab](http://support.mozilla.com/en-US/kb/what-are-app-tabs).
+
+@prop [onOpen] {function}
+A callback function that will be registered for 'open' event.
+This is an optional property.
+@prop [onClose] {function}
+A callback function that will be registered for 'close' event.
+This is an optional property.
+@prop [onReady] {function}
+A callback function that will be registered for 'ready' event.
+This is an optional property.
+@prop [onActivate] {function}
+A callback function that will be registered for 'activate' event.
+This is an optional property.
+@prop [onDeactivate] {function}
+A callback function that will be registered for 'deactivate' event.
+This is an optional property.
+</api>
+
+<api name="Tab">
+@class
+A `Tab` instance represents a single open tab. It contains various tab
+properties, several methods for manipulation, as well as per-tab event
+registration.
+
+Tabs emit all the events described in the Events section. Listeners are
+passed the `Tab` object that triggered the event.
+
+<api name="title">
+@property {string}
+The title of the page currently loaded in the tab.
+This property can be set to change the tab title.
+</api>
+
+<api name="url">
+@property {String}
+The URL of the page currently loaded in the tab.
+This property can be set to load a different URL in the tab.
+</api>
+
+<api name="favicon">
+@property {string}
+The URL of the favicon for the page currently loaded in the tab.
+This property is read-only.
+</api>
+
+<api name="index">
+@property {integer}
+The index of the tab relative to other tabs in the application window.
+This property can be set to change its relative position.
+</api>
+
+<api name="isPinned">
+@property {boolean}
+Whether or not tab is pinned as an [app tab][].
+This property is read-only.
+[app tab]:http://support.mozilla.com/en-US/kb/what-are-app-tabs
+</api>
+
+<api name="getThumbnail">
+@property {method}
+Returns thumbnail data URI of the page currently loaded in this tab.
+</api>
+
+<api name="pin">
+@method
+Pins this tab as an [app tab][].
+[app tab]:http://support.mozilla.com/en-US/kb/what-are-app-tabs
+</api>
+
+<api name="unpin">
+@method
+Unpins this tab.
+</api>
+
+<api name="close">
+@method
+Closes this tab.
+
+@param [callback] {function}
+A function to be called when the tab finishes its closing process.
+This is an optional argument.
+</api>
+
+<api name="reload">
+@method
+Reloads this tab.
+</api>
+
+<api name="activate">
+@method
+Makes this tab active, which will bring this tab to the foreground.
+</api>
+
+<api name="attach">
+@method
+  Create a page mod and attach it to the document in the tab.
+
+**Example**
+
+    var tabs = require("tabs");
+
+    tabs.on('ready', function(tab) {
+      tab.attach({
+          contentScript:
+            'document.body.style.border = "5px solid red";'
+      });
+    });
+
+@param options {object}
+  Options for the page mod, with the following keys:
+
+@prop [contentScriptFile] {string,array}
+    The local file URLs of content scripts to load.  Content scripts specified
+    by this option are loaded *before* those specified by the `contentScript`
+    option. Optional.
+@prop [contentScript] {string,array}
+    The texts of content scripts to load.  Content scripts specified by this
+    option are loaded *after* those specified by the `contentScriptFile` option.
+    Optional.
+@prop [onMessage] {function}
+    A function called when the page mod receives a message from content scripts.
+    Listeners are passed a single argument, the message posted from the
+    content script. Optional.
+
+@returns {Worker}
+  See [Content Scripts guide](dev-guide/guides/content-scripts/index.html)
+  to learn how to use the `Worker` object to communicate with the content script.
+
+</api>
+
+<api name="close">
+@event
+
+This event is emitted when the tab is closed.  It's also emitted when the
+tab's window is closed.
+
+@argument {Tab}
+Listeners are passed the tab object.
+</api>
+
+<api name="ready">
+@event
+
+This event is emitted when the DOM for the tab's content is ready. It is
+equivalent to the `DOMContentLoaded` event for the given content page.
+
+A single tab will emit this event every time the DOM is loaded: so it will be
+emitted again if the tab's location changes or the content is reloaded.
+
+After this event has been emitted, all properties relating to the tab's
+content can be used.
+
+@argument {Tab}
+Listeners are passed the tab object.
+</api>
+
+<api name="activate">
+@event
+
+This event is emitted when the tab is made active.
+
+@argument {Tab}
+Listeners are passed the tab object.
+</api>
+
+<api name="deactivate">
+@event
+
+This event is emitted when the tab is made inactive.
+
+@argument {Tab}
+Listeners are passed the tab object.
+</api>
+
+</api>
+
+<api name="open">
+@event
+
+This event is emitted when a new tab is opened. This does not mean that
+the content has loaded, only that the browser tab itself is fully visible
+to the user.
+
+Properties relating to the tab's content (for example: `title`, `favicon`,
+and `url`) will not be correct at this point. If you need to access these
+properties, listen for the `ready` event:
+
+    var tabs = require("tabs");
+    tabs.on('open', function(tab){
+      tab.on('ready', function(tab){
+        console.log(tab.url);
+      });
+    });
+
+@argument {Tab}
+Listeners are passed the tab object that just opened.
+</api>
+
+<api name="close">
+@event
+
+This event is emitted when a tab is closed. When a window is closed
+this event will be emitted for each of the open tabs in that window.
+
+@argument {Tab}
+Listeners are passed the tab object that has closed.
+</api>
+
+<api name="ready">
+@event
+
+This event is emitted when the DOM for a tab's content is ready.
+It is equivalent to the `DOMContentLoaded` event for the given content page.
+
+A single tab will emit this event every time the DOM is loaded: so it will be
+emitted again if the tab's location changes or the content is reloaded.
+
+After this event has been emitted, all properties relating to the tab's
+content can be used.
+
+@argument {Tab}
+Listeners are passed the tab object that has loaded.
+</api>
+
+<api name="activate">
+@event
+
+This event is emitted when an inactive tab is made active.
+
+@argument {Tab}
+Listeners are passed the tab object that has become active.
+</api>
+
+<api name="deactivate">
+@event
+
+This event is emitted when the active tab is made inactive.
+
+@argument {Tab}
+Listeners are passed the tab object that has become inactive.
+</api>