diff options
Diffstat (limited to 'tools/addon-sdk-1.7/packages/addon-kit/docs')
18 files changed, 0 insertions, 5089 deletions
diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/clipboard.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/clipboard.md deleted file mode 100644 index 387766e..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/clipboard.md +++ /dev/null @@ -1,62 +0,0 @@ -<!-- 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] --> - -The `clipboard` module allows callers to interact with the system clipboard, -setting and retrieving its contents. - -You can optionally specify the type of the data to set and retrieve. -The following types are supported: - -* `text` (plain text) -* `html` (a string of HTML) - -If no data type is provided, then the module will detect it for you. - -Examples --------- - -Set and get the contents of the clipboard. - - let clipboard = require("clipboard"); - clipboard.set("Lorem ipsum dolor sit amet"); - let contents = clipboard.get(); - -Set the clipboard contents to some HTML. - - let clipboard = require("clipboard"); - clipboard.set("<blink>Lorem ipsum dolor sit amet</blink>", "html"); - -If the clipboard contains HTML content, open it in a new tab. - - let clipboard = require("clipboard"); - if (clipboard.currentFlavors.indexOf("html") != -1) - require("tabs").open("data:text/html," + clipboard.get("html")); - -<api name="set"> -@function - Replace the contents of the user's clipboard with the provided data. -@param data {string} - The data to put on the clipboard. -@param [datatype] {string} - The type of the data (optional). -</api> - -<api name="get"> -@function - Get the contents of the user's clipboard. -@param [datatype] {string} - Retrieve the clipboard contents only if matching this type (optional). - The function will return null if the contents of the clipboard do not match - the supplied type. -</api> - -<api name="currentFlavors"> -@property {array} - Data on the clipboard is sometimes available in multiple types. For example, - HTML data might be available as both a string of HTML (the `html` type) - and a string of plain text (the `text` type). This function returns an array - of all types in which the data currently on the clipboard is available. -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/context-menu.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/context-menu.md deleted file mode 100644 index 28fb35a..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/context-menu.md +++ /dev/null @@ -1,719 +0,0 @@ -<!-- 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 Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `context-menu` module lets you add items to Firefox's page context menu. - - -Introduction ------------- - -The `context-menu` API provides a simple, declarative way to add items to the -page's context menu. You can add items that perform an action when clicked, -submenus, and menu separators. - -Instead of manually adding items when particular contexts occur and then -removing them when those contexts go away, you *bind* items to contexts, and the -adding and removing is automatically handled for you. Items are bound to -contexts in much the same way that event listeners are bound to events. When -the user invokes the context menu, all of the items bound to the current context -are automatically added to the menu. If no items are bound, none are added. -Likewise, any items that were previously in the menu but are not bound to the -current context are automatically removed from the menu. You never need to -manually remove your items from the menu unless you want them to never appear -again. - -For example, if your add-on needs to add a context menu item whenever the -user visits a certain page, don't create the item when that page loads, and -don't remove it when the page unloads. Rather, create your item only once and -supply a context that matches the target URL. - - -Specifying Contexts -------------------- - -As its name implies, the context menu should be reserved for the occurrence of -specific contexts. Contexts can be related to page content or the page itself, -but they should never be external to the page. - -For example, a good use of the menu would be to show an "Edit Image" item when -the user right-clicks an image in the page. A bad use would be to show a -submenu that listed all the user's tabs, since tabs aren't related to the page -or the node the user clicked to open the menu. - -### The Page Context - -First of all, you may not need to specify a context at all. When an item does -not specify a context, the page context applies. - -The *page context* occurs when the user invokes the context menu on a -non-interactive portion of the page. Try right-clicking a blank spot in this -page, or on text. Make sure that no text is selected. The menu that appears -should contain the items "Back", "Forward", "Reload", "Stop", and so on. This -is the page context. - -The page context is appropriate when your item acts on the page as a whole. It -does not occur when the user invokes the context menu on a link, image, or other -non-text node, or while a selection exists. - -### Declarative Contexts - -You can specify some simple, declarative contexts when you create a menu item by -setting the `context` property of the options object passed to its constructor, -like this: - - var cm = require("context-menu"); - cm.Item({ - label: "My Menu Item", - context: cm.URLContext("*.mozilla.org") - }); - -These contexts may be specified by calling the following constructors. Each is -exported by the `context-menu` module. - -<table> - <tr> - <th>Constructor</th> - <th>Description</th> - </tr> - <tr> - <td><code> - PageContext() - </code></td> - <td> - The page context. - </td> - </tr> - <tr> - <td><code> - SelectionContext() - </code></td> - <td> - This context occurs when the menu is invoked on a page in which the user - has made a selection. - </td> - </tr> - <tr> - <td><code> - SelectorContext(selector) - </code></td> - <td> - This context occurs when the menu is invoked on a node that either matches - <code>selector</code>, a CSS selector, or has an ancestor that matches. - <code>selector</code> may include multiple selectors separated by commas, - e.g., <code>"a[href], img"</code>. - </td> - </tr> - <tr> - <td><code> - URLContext(matchPattern) - </code></td> - <td> - This context occurs when the menu is invoked on pages with particular - URLs. <code>matchPattern</code> is a match pattern string or an array of - match pattern strings. When <code>matchPattern</code> is an array, the - context occurs when the menu is invoked on a page whose URL matches any of - the patterns. These are the same match pattern strings that you use with - the <a href="packages/addon-kit/page-mod.html"><code>page-mod</code></a> - <code>include</code> property. - <a href="packages/api-utils/match-pattern.html">Read more about patterns</a>. - </td> - </tr> - <tr> - <td> - array - </td> - <td> - An array of any of the other types. This context occurs when all contexts - in the array occur. - </td> - </tr> -</table> - -Menu items also have a `context` property that can be used to add and remove -declarative contexts after construction. For example: - - var context = require("context-menu").SelectorContext("img"); - myMenuItem.context.add(context); - myMenuItem.context.remove(context); - -When a menu item is bound to more than one context, it appears in the menu when -all of those contexts occur. - -### In Content Scripts - -The declarative contexts are handy but not very powerful. For instance, you -might want your menu item to appear for any page that has at least one image, -but declarative contexts won't help you there. - -When you need more control control over the context in which your menu items are -shown, you can use content scripts. Like other APIs in the SDK, the -`context-menu` API uses -[content scripts](dev-guide/guides/content-scripts/index.html) to let your -add-on interact with pages in the browser. Each menu item you create in the -top-level context menu can have a content script. - -A special event named `"context"` is emitted in your content scripts whenever -the context menu is about to be shown. If you register a listener function for -this event and it returns true, the menu item associated with the listener's -content script is shown in the menu. - -For example, this item appears whenever the context menu is invoked on a page -that contains at least one image: - - require("context-menu").Item({ - label: "This Page Has Images", - contentScript: 'self.on("context", function (node) {' + - ' return !!document.querySelector("img");' + - '});' - }); - -Note that the listener function has a parameter called `node`. This is the node -in the page that the user context-clicked to invoke the menu. You can use it to -determine whether your item should be shown. - -You can both specify declarative contexts and listen for contexts in a content -script. In that case, the declarative contexts are evaluated first. If they -are not current, then your context listener is never called. - -This example takes advantage of that fact. The listener can be assured that -`node` will always be an image: - - var cm = require("context-menu"); - cm.Item({ - label: "A Mozilla Image", - context: cm.SelectorContext("img"), - contentScript: 'self.on("context", function (node) {' + - ' return /mozilla/.test(node.src);' + - '});' - }); - -Your item is shown only when all declarative contexts are current and your -context listener returns true. - - -Handling Menu Item Clicks -------------------------- - -In addition to using content scripts to listen for the `"context"` event as -described above, you can use content scripts to handle item clicks. When the -user clicks your menu item, an event named `"click"` is emitted in the item's -content script. - -Therefore, to handle an item click, listen for the `"click"` event in that -item's content script like so: - - require("context-menu").Item({ - label: "My Item", - contentScript: 'self.on("click", function (node, data) {' + - ' console.log("Item clicked!");' + - '});' - }); - -Note that the listener function has parameters called `node` and `data`. `node` -is the node that the user context-clicked to invoke the menu. You can use it -when performing some action. `data` is the `data` property of the menu item -that was clicked. Since only top-level menu items have content scripts, this -comes in handy for determining which item in a `Menu` was clicked: - - var cm = require("context-menu"); - cm.Menu({ - label: "My Menu", - contentScript: 'self.on("click", function (node, data) {' + - ' console.log("You clicked " + data);' + - '});', - items: [ - cm.Item({ label: "Item 1", data: "item1" }), - cm.Item({ label: "Item 2", data: "item2" }), - cm.Item({ label: "Item 3", data: "item3" }) - ] - }); - -Often you will need to collect some kind of information in the click listener -and perform an action unrelated to content. To communicate to the menu item -associated with the content script, the content script can call the -`postMessage` function attached to the global `self` object, passing it some -JSON-able data. The menu item's `"message"` event listener will be called with -that data. - - var cm = require("context-menu"); - cm.Item({ - label: "Edit Image", - context: cm.SelectorContext("img"), - contentScript: 'self.on("click", function (node, data) {' + - ' self.postMessage(node.src);' + - '});', - onMessage: function (imgSrc) { - openImageEditor(imgSrc); - } - }); - - -Updating a Menu Item's Label ----------------------------- - -Each menu item must be created with a label, but you can change its label later -using a couple of methods. - -The simplest method is to set the menu item's `label` property. This example -updates the item's label based on the number of times it's been clicked: - - var numClicks = 0; - var myItem = require("context-menu").Item({ - label: "Click Me: " + numClicks, - contentScript: 'self.on("click", self.postMessage);', - onMessage: function () { - numClicks++; - this.label = "Click Me: " + numClicks; - // Setting myItem.label is equivalent. - } - }); - -Sometimes you might want to update the label based on the context. For -instance, if your item performs a search with the user's selected text, it would -be nice to display the text in the item to provide feedback to the user. In -these cases you can use the second method. Recall that your content scripts can -listen for the `"context"` event and if your listeners return true, the items -associated with the content scripts are shown in the menu. In addition to -returning true, your `"context"` listeners can also return strings. When a -`"context"` listener returns a string, it becomes the item's new label. - -This item implements the aforementioned search example: - - var cm = require("context-menu"); - cm.Item({ - label: "Search Google", - context: cm.SelectionContext(), - contentScript: 'self.on("context", function () {' + - ' var text = window.getSelection().toString();' + - ' if (text.length > 20)' + - ' text = text.substr(0, 20) + "...";' + - ' return "Search Google for " + text;' + - '});' - }); - -The `"context"` listener gets the window's current selection, truncating it if -it's too long, and includes it in the returned string. When the item is shown, -its label will be "Search Google for `text`", where `text` is the truncated -selection. - - -More Examples -------------- - -For conciseness, these examples create their content scripts as strings and use -the `contentScript` property. In your own add-on, you will probably want to -create your content scripts in separate files and pass their URLs using the -`contentScriptFile` property. See -[Working with Content Scripts](dev-guide/guides/content-scripts/index.html) -for more information. - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a -static string, don't use <code>contentScript</code>: if you do, you may -have problems getting your add-on approved on AMO.</p> -<p>Instead, keep the script in a separate file and load it using -<code>contentScriptFile</code>. This makes your code easier to maintain, -secure, debug and review.</p> -</div> - -Show an "Edit Page Source" item when the user right-clicks a non-interactive -part of the page: - - require("context-menu").Item({ - label: "Edit Page Source", - contentScript: 'self.on("click", function (node, data) {' + - ' self.postMessage(document.URL);' + - '});', - onMessage: function (pageURL) { - editSource(pageURL); - } - }); - -Show an "Edit Image" item when the menu is invoked on an image: - - var cm = require("context-menu"); - cm.Item({ - label: "Edit Image", - context: cm.SelectorContext("img"), - contentScript: 'self.on("click", function (node, data) {' + - ' self.postMessage(node.src);' + - '});', - onMessage: function (imgSrc) { - openImageEditor(imgSrc); - } - }); - -Show an "Edit Mozilla Image" item when the menu is invoked on an image in a -mozilla.org or mozilla.com page: - - var cm = require("context-menu"); - cm.Item({ - label: "Edit Mozilla Image", - context: [ - cm.URLContext(["*.mozilla.org", "*.mozilla.com"]), - cm.SelectorContext("img") - ], - contentScript: 'self.on("click", function (node, data) {' + - ' self.postMessage(node.src);' + - '});', - onMessage: function (imgSrc) { - openImageEditor(imgSrc); - } - }); - -Show an "Edit Page Images" item when the page contains at least one image: - - var cm = require("context-menu"); - cm.Item({ - label: "Edit Page Images", - // This ensures the item only appears during the page context. - context: cm.PageContext(), - contentScript: 'self.on("context", function (node) {' + - ' var pageHasImgs = !!document.querySelector("img");' + - ' return pageHasImgs;' + - '});' + - 'self.on("click", function (node, data) {' + - ' var imgs = document.querySelectorAll("img");' + - ' var imgSrcs = [];' + - ' for (var i = 0 ; i < imgs.length; i++)' + - ' imgSrcs.push(imgs[i].src);' + - ' self.postMessage(imgSrcs);' + - '});', - onMessage: function (imgSrcs) { - openImageEditor(imgSrcs); - } - }); - -Show a "Search With" menu when the user right-clicks an anchor that searches -Google or Wikipedia with the text contained in the anchor: - - var cm = require("context-menu"); - var googleItem = cm.Item({ - label: "Google", - data: "http://www.google.com/search?q=" - }); - var wikipediaItem = cm.Item({ - label: "Wikipedia", - data: "http://en.wikipedia.org/wiki/Special:Search?search=" - }); - var searchMenu = cm.Menu({ - label: "Search With", - context: cm.SelectorContext("a[href]"), - contentScript: 'self.on("click", function (node, data) {' + - ' var searchURL = data + node.textContent;' + - ' window.location.href = searchURL;' + - '});', - items: [googleItem, wikipediaItem] - }); - - -<api name="Item"> -@class -A labeled menu item that can perform an action when clicked. -<api name="Item"> -@constructor - Creates a labeled menu item that can perform an action when clicked. -@param options {object} - An object with the following keys: - @prop label {string} - The item's label. It must either be a string or an object that implements - `toString()`. - @prop [image] {string} - The item's icon, a string URL. The URL can be remote, a reference to an - image in the add-on's `data` directory, or a data URI. - @prop [data] {string} - An optional arbitrary value to associate with the item. It must be either a - string or an object that implements `toString()`. It will be passed to - click listeners. - @prop [context] {value} - If the item is contained in the top-level context menu, this declaratively - specifies the context under which the item will appear; see Specifying - Contexts above. Ignored if the item is contained in a submenu. - @prop [contentScript] {string,array} - If the item is contained in the top-level context menu, this is the content - script or an array of content scripts that the item can use to interact with - the page. Ignored if the item is contained in a submenu. - @prop [contentScriptFile] {string,array} - If the item is contained in the top-level context menu, this is the local - file URL of the content script or an array of such URLs that the item can - use to interact with the page. Ignored if the item is contained in a - submenu. - @prop [onMessage] {function} - If the item is contained in the top-level context menu, this function will - be called when the content script calls `self.postMessage`. It will be - passed the data that was passed to `postMessage`. Ignored if the item is - contained in a submenu. -</api> - -<api name="label"> -@property {string} - The menu item's label. You can set this after creating the item to update its - label later. -</api> - -<api name="image"> -@property {string} - The item's icon, a string URL. The URL can be remote, a reference to an image - in the add-on's `data` directory, or a data URI. You can set this after - creating the item to update its image later. To remove the item's image, set - it to `null`. -</api> - -<api name="data"> -@property {string} - An optional arbitrary value to associate with the item. It must be either a - string or an object that implements `toString()`. It will be passed to - click listeners. You can set this after creating the item to update its data - later. -</api> - -<api name="context"> -@property {list} - A list of declarative contexts for which the menu item will appear in the - context menu. Contexts can be added by calling `context.add()` and removed by - called `context.remove()`. This property is meaningful only for items - contained in the top-level context menu. -</api> - -<api name="parentMenu"> -@property {Menu} - The item's parent `Menu`, or `null` if the item is contained in the top-level - context menu. This property is read-only. To add the item to a new menu, - call that menu's `addItem()` method. -</api> - -<api name="contentScript"> -@property {string,array} - The content script or the array of content scripts associated with the menu - item during creation. This property is meaningful only for items contained in - the top-level context menu. -</api> - -<api name="contentScriptFile"> -@property {string,array} - The URL of a content script or the array of such URLs associated with the menu - item during creation. This property is meaningful only for items contained in - the top-level context menu. -</api> - -<api name="destroy"> -@method - Permanently removes the item from its parent menu and frees its resources. - The item must not be used afterward. If you need to remove the item from its - parent menu but use it afterward, call `removeItem()` on the parent menu - instead. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this menu item. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the menu item's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -</api> - -<api name="Menu"> -@class -A labeled menu item that expands into a submenu. - -<api name="Menu"> -@constructor - Creates a labeled menu item that expands into a submenu. -@param options {object} - An object with the following keys: - @prop label {string} - The item's label. It must either be a string or an object that implements - `toString()`. - @prop items {array} - An array of menu items that the menu will contain. Each must be an `Item`, - `Menu`, or `Separator`. - @prop [image] {string} - The menu's icon, a string URL. The URL can be remote, a reference to an - image in the add-on's `data` directory, or a data URI. - @prop [context] {value} - If the menu is contained in the top-level context menu, this declaratively - specifies the context under which the menu will appear; see Specifying - Contexts above. Ignored if the menu is contained in a submenu. - @prop [contentScript] {string,array} - If the menu is contained in the top-level context menu, this is the content - script or an array of content scripts that the menu can use to interact with - the page. Ignored if the menu is contained in a submenu. - @prop [contentScriptFile] {string,array} - If the menu is contained in the top-level context menu, this is the local - file URL of the content script or an array of such URLs that the menu can - use to interact with the page. Ignored if the menu is contained in a - submenu. - @prop [onMessage] {function} - If the menu is contained in the top-level context menu, this function will - be called when the content script calls `self.postMessage`. It will be - passed the data that was passed to `postMessage`. Ignored if the item is - contained in a submenu. -</api> - -<api name="label"> -@property {string} - The menu's label. You can set this after creating the menu to update its - label later. -</api> - -<api name="items"> -@property {array} - An array containing the items in the menu. The array is read-only, meaning - that modifications to it will not affect the menu. However, setting this - property to a new array will replace all the items currently in the menu with - the items in the new array. -</api> - -<api name="image"> -@property {string} - The menu's icon, a string URL. The URL can be remote, a reference to an image - in the add-on's `data` directory, or a data URI. You can set this after - creating the menu to update its image later. To remove the menu's image, set - it to `null`. -</api> - -<api name="context"> -@property {list} - A list of declarative contexts for which the menu will appear in the context - menu. Contexts can be added by calling `context.add()` and removed by called - `context.remove()`. This property is meaningful only for menus contained in - the top-level context menu. -</api> - -<api name="parentMenu"> -@property {Menu} - The menu's parent `Menu`, or `null` if the menu is contained in the top-level - context menu. This property is read-only. To add the menu to a new menu, - call that menu's `addItem()` method. -</api> - -<api name="contentScript"> -@property {string,array} - The content script or the array of content scripts associated with the menu - during creation. This property is meaningful only for menus contained in the - top-level context menu. -</api> - -<api name="contentScriptFile"> -@property {string,array} - The URL of a content script or the array of such URLs associated with the menu - during creation. This property is meaningful only for menus contained in the - top-level context menu. -</api> - -<api name="addItem"> -@method - Appends a menu item to the end of the menu. If the item is already contained - in another menu or in the top-level context menu, it's automatically removed - first. -@param item {Item,Menu,Separator} - The `Item`, `Menu`, or `Separator` to add to the menu. -</api> - -<api name="removeItem"> -@method - Removes the given menu item from the menu. If the menu does not contain the - item, this method does nothing. -@param item {Item,Menu,Separator} - The menu item to remove from the menu. -</api> - -<api name="destroy"> -@method - Permanently removes the menu from its parent menu and frees its resources. - The menu must not be used afterward. If you need to remove the menu from its - parent menu but use it afterward, call `removeItem()` on the parent menu - instead. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this menu item. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the menu item's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -</api> - -<api name="Separator"> -@class -A menu separator. Separators can be contained only in `Menu`s, not in the -top-level context menu. - -<api name="Separator"> -@constructor - Creates a menu separator. -</api> - -<api name="parentMenu"> -@property {Menu} - The separator's parent `Menu`. This property is read-only. To add the - separator to a new menu, call that menu's `addItem()` method. -</api> - -<api name="destroy"> -@method - Permanently removes the separator from its parent menu and frees its - resources. The separator must not be used afterward. If you need to remove - the separator from its parent menu but use it afterward, call `removeItem()` - on the parent menu instead. -</api> - -</api> - -<api name="PageContext"> -@class -<api name="PageContext"> -@constructor - Creates a page context. See Specifying Contexts above. -</api> -</api> - -<api name="SelectionContext"> -@class -<api name="SelectionContext"> -@constructor - Creates a context that occurs when a page contains a selection. See - Specifying Contexts above. -</api> -</api> - -<api name="SelectorContext"> -@class -<api name="SelectorContext"> -@constructor - Creates a context that matches a given CSS selector. See Specifying Contexts - above. -@param selector {string} - A CSS selector. -</api> -</api> - -<api name="URLContext"> -@class -<api name="URLContext"> -@constructor - Creates a context that matches pages with particular URLs. See Specifying - Contexts above. -@param matchPattern {string,array} - A [match pattern](packages/api-utils/match-pattern.html) string or an array of - match pattern strings. -</api> -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/hotkeys.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/hotkeys.md deleted file mode 100644 index b12791c..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/hotkeys.md +++ /dev/null @@ -1,78 +0,0 @@ -<!-- 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 Irakli Gozalishvili [gozala@mozilla.com] --> - -Some add-ons may wish to define keyboard shortcuts for certain operations. This -module exposes an API to create those. - -<api name="Hotkey"> -@class - -Module exports `Hotkey` constructor allowing users to create a `hotkey` for the -host application. - -<api name="Hotkey"> -@constructor -Creates a hotkey who's `onPress` listener method is invoked when key combination -defined by `hotkey` is pressed. - -Please note: If more than one `hotkey` is created for the same key -combination, the listener is executed only on the last one created - -@param options {Object} - Options for the hotkey, with the following keys: - -@prop combo {String} -Any function key: `"f1, f2, ..., f24"` or key combination in the format -of `'modifier-key'`: - - "accel-s" - "meta-shift-i" - "control-alt-d" - -Modifier keynames: - -- **shift**: The Shift key. -- **alt**: The Alt key. On the Macintosh, this is the Option key. On - Macintosh this can only be used in conjunction with another modifier, - since `Alt-Letter` combinations are reserved for entering special - characters in text. -- **meta**: The Meta key. On the Macintosh, this is the Command key. -- **control**: The Control key. -- **accel**: The key used for keyboard shortcuts on the user's platform, - which is Control on Windows and Linux, and Command on Mac. Usually, this - would be the value you would use. - -@prop onPress {Function} -Function that is invoked when the key combination `hotkey` is pressed. - -</api> -<api name="destroy"> -@method -Stops this instance of `Hotkey` from reacting on the key combinations. Once -destroyed it can no longer be used. -</api> -</api> - -## Example ## - - // Define keyboard shortcuts for showing and hiding a custom panel. - var { Hotkey } = require("hotkeys"); - - var showHotKey = Hotkey({ - combo: "accel-shift-o", - onPress: function() { - showMyPanel(); - } - }); - var hideHotKey = Hotkey({ - combo: "accel-alt-shift-o", - onPress: function() { - hideMyPanel(); - } - }); - -[Mozilla keyboard planning FAQ]:http://www.mozilla.org/access/keyboard/ -[keyboard shortcuts]:https://developer.mozilla.org/en/XUL_Tutorial/Keyboard_Shortcuts diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/notifications.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/notifications.md deleted file mode 100644 index ca120ab..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/notifications.md +++ /dev/null @@ -1,64 +0,0 @@ -<!-- 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 Drew Willcoxon [adw@mozilla.com] --> - -The `notifications` module allows you to display transient, -[toaster](http://en.wikipedia.org/wiki/Toast_%28computing%29)-style -desktop messages to the user. - -This API supports desktop notifications on Windows, OS X using -[Growl](http://growl.info/), and Linux using libnotify. If the user's system -does not support desktop notifications or if its notifications service is not -running, then notifications made with this API are logged to Firefox's error -console and, if the user launched Firefox from the command line, the terminal. - -Examples --------- - -Here's a typical example. When the message is clicked, a string is logged to -the console. - - var notifications = require("notifications"); - notifications.notify({ - title: "Jabberwocky", - text: "'Twas brillig, and the slithy toves", - data: "did gyre and gimble in the wabe", - onClick: function (data) { - console.log(data); - // console.log(this.data) would produce the same result. - } - }); - -This one displays an icon that's stored in the add-on's `data` directory. (See -the [`self`](packages/addon-kit/self.html) module documentation for more information.) - - var notifications = require("notifications"); - var self = require("self"); - var myIconURL = self.data.url("myIcon.png"); - notifications.notify({ - text: "I have an icon!", - iconURL: myIconURL - }); - - -<api name="notify"> -@function - Displays a transient notification to the user. -@param options {object} - An object with the following keys. Each is optional. - @prop [title] {string} - A string to display as the message's title. - @prop [text] {string} - A string to display as the body of the message. - @prop [iconURL] {string} - The URL of an icon to display inside the message. It may be a remote URL, - a data URI, or a URL returned by the [`self`](packages/addon-kit/self.html) - module. - @prop [onClick] {function} - A function to be called when the user clicks the message. It will be passed - the value of `data`. - @prop [data] {string} - A string that will be passed to `onClick`. -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/page-mod.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/page-mod.md deleted file mode 100644 index 3b6ef6b..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/page-mod.md +++ /dev/null @@ -1,412 +0,0 @@ -<!-- 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 Nickolay Ponomarev [asqueella@gmail.com] --> -<!-- contributed by Myk Melez [myk@mozilla.org] --> -<!-- contributed by Irakli Gozalishvil [gozala@mozilla.com] --> - -Overview --------- -The page-mod module enables add-on developers to execute scripts in the context -of specific web pages. Most obviously you could use page-mod to dynamically -modify the content of certain pages. - -The module exports a constructor function `PageMod` which creates a new page -modification (or "mod" for short). - -A page mod does not modify its pages until those pages are loaded or reloaded. -In other words, if your add-on is loaded while the user's browser is open, the -user will have to reload any open pages that match the mod for the mod to affect -them. - -To stop a page mod from making any more modifications, call its `destroy` -method. - -Like all modules that interact with web content, page-mod uses content -scripts that execute in the content process and defines a messaging API to -communicate between the content scripts and the main add-on script. For more -details on content scripting see the tutorial on [interacting with web -content](dev-guide/guides/content-scripts/index.html). - -To create a PageMod the add-on developer supplies: - -* a set of rules to select the desired subset of web pages based on their URL. -Each rule is specified using the -[match-pattern](packages/api-utils/match-pattern.html) syntax. - -* a set of content scripts to execute in the context of the desired pages. - -* a value for the onAttach option: this value is a function which will be -called when a page is loaded that matches the ruleset. This is used to set up a -communication channel between the add-on code and the content script. - -All these parameters are optional except for the ruleset, which must include -at least one rule. - -The following add-on displays an alert whenever a page matching the ruleset is -loaded: - - var pageMod = require("page-mod"); - pageMod.PageMod({ - include: "*.org", - contentScript: 'window.alert("Page matches ruleset");' - }); - -If you specify a value of "ready" or "end" for `contentScriptWhen`, -as opposed to "start", -then the content script can interact with the DOM itself: - - var pageMod = require("page-mod"); - pageMod.PageMod({ - include: "*.org", - contentScriptWhen: 'end', - contentScript: 'document.body.innerHTML = ' + - ' "<h1>Page matches ruleset</h1>";' - }); - -### Using `contentScriptFile` ### - -Most of the examples in this page define content scripts as strings, -and use the `contentScript` option to assign them to page mods. - -Alternatively, you can create content scripts in separate files -under your add-on's `data` directory. Then you can use the -[`self`](packages/addon-kit/self.html) module to retrieve a URL pointing -to the file, and assign this to the page-mod's `contentScriptFile` -property. - -For example, if you save the content script -file in your `data` directory as "myScript.js", you would assign it using -code like: - - var data = require("self").data; - - var pageMod = require("page-mod"); - pageMod.PageMod({ - include: "*.org", - contentScriptWhen: 'end', - contentScriptFile: data.url("myScript.js") - }); - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a -static string, don't use <code>contentScript</code>: if you do, you may -have problems getting your add-on approved on AMO.</p> -<p>Instead, keep the script in a separate file and load it using -<code>contentScriptFile</code>. This makes your code easier to maintain, -secure, debug and review.</p> -</div> - -### Styling web pages ### - -Sometimes adding a script to web pages is not enough, you also want to styling -them. `PageMod` provides an easy way to do that through options' `contentStyle` -and `contentStyleFile` properties: - - var data = require("self").data; - var pageMod = require("page-mod"); - - pageMod.PageMod({ - include: "*.org", - - contentStyleFile: data.url("my-page-mod.css"), - contentStyle: [ - "div { padding: 10px; border: 1px solid silver}", - "img { display: none}" - ] - }) - -It's important to note that `PageMod` will add these styles as -[user style sheet](https://developer.mozilla.org/en/CSS/Getting_Started/Cascading_and_inheritance). - -## Communicating With Content Scripts ## - -When a matching page is loaded the `PageMod` will call the function that the -add-on code supplied to `onAttach`. The `PageMod` supplies one argument to -this function: a `worker` object. - -The worker can be thought of as the add-on's end of -a communication channel between the add-on code and the content scripts that -have been attached to this page. - -Thus the add-on can pass messages to the content scripts by calling the -worker's `postMessage` function and can receive messages from the content -scripts by registering a function as a listener to the worker's `on` function. - -Note that if multiple matching pages are loaded simultaneously then each page -is loaded into its own execution context with its own copy of the content -scripts. In this case `onAttach` is called once for each loaded page, and the -add-on code will have a separate worker for each page: - - - -This is demonstrated in the following example: - - var pageMod = require("page-mod"); - var tabs = require("tabs"); - - var workers = []; - - pageMod.PageMod({ - include: ["http://www.mozilla*"], - contentScriptWhen: 'end', - contentScript: "onMessage = function onMessage(message) {" + - " window.alert(message);};", - onAttach: function onAttach(worker) { - if (workers.push(worker) == 3) { - workers[0].postMessage("The first worker!"); - workers[1].postMessage("The second worker!"); - workers[2].postMessage("The third worker!"); - } - } - }); - - tabs.open("http://www.mozilla.com"); - tabs.open("http://www.mozilla.org"); - tabs.open("http://www.mozilla-europe.org"); - -Here we specify a ruleset to match any URLs starting with -"http://www.mozilla". When a page matches we add the supplied worker to -an array, and when we have three workers in the array we send a message to -each worker in turn, telling it the order in which it was attached. The -worker just displays the message in an alert box. - -This shows that separate pages execute in separate contexts and that each -context has its own communication channel with the add-on script. - -Note though that while there is a separate worker for each execution context, -the worker is shared across all the content scripts associated with a single -execution context. In the following example we pass two content scripts into -the `PageMod`: these content scripts will share a worker instance. - -In the example each content script identifies itself to the add-on script -by sending it a message using the global `postMessage` function. In the -`onAttach` function the add-on code logs the fact that a new page is -attached and registers a listener function that simply logs the message: - - - var pageMod = require("page-mod"); - var data = require("self").data; - var tabs = require("tabs"); - - pageMod.PageMod({ - include: ["http://www.mozilla*"], - contentScriptWhen: 'end', - contentScript: ["postMessage('Content script 1 is attached to '+ " + - "document.URL);", - "postMessage('Content script 2 is attached to '+ " + - "document.URL);"], - onAttach: function onAttach(worker) { - console.log("Attaching content scripts") - worker.on('message', function(data) { - console.log(data); - }); - } - }); - - tabs.open("http://www.mozilla.com"); - -The console output of this add-on is: - -<pre> - info: Attaching content scripts - info: Content script 1 is attached to http://www.mozilla.com/en-US/ - info: Content script 2 is attached to http://www.mozilla.com/en-US/ -</pre> - -### Mapping workers to tabs ### - -The [`worker`](packages/api-utils/content/worker.html) has a `tab` -property which returns the tab associated with this worker. You can use this -to access the [`tabs API`](packages/addon-kit/tabs.html) for the tab -associated with a specific page: - - var pageMod = require("page-mod"); - var tabs = require("tabs"); - - pageMod.PageMod({ - include: ["*"], - onAttach: function onAttach(worker) { - console.log(worker.tab.title); - } - }); - -### Attaching content scripts to tabs ### - -We've seen that the page mod API attaches content scripts to pages based on -their URL. Sometimes, though, we don't care about the URL: we just want -to execute a script on demand in the context of a particular tab. - -For example, we might want to run a script in the context of the currently -active tab when the user clicks a widget: to block certain content, to -change the font style, or to display the page's DOM structure. - -Using the `attach` method of the [`tab`](packages/addon-kit/tabs.html) -object, you can attach a set of content scripts to a particular tab. The -scripts are executed immediately. - -The following add-on creates a widget which, when clicked, highlights all the -`div` elements in the page loaded into the active tab: - - var widgets = require("widget"); - var tabs = require("tabs"); - - var widget = widgets.Widget({ - id: "div-show", - label: "Show divs", - contentURL: "http://www.mozilla.org/favicon.ico", - onClick: function() { - tabs.activeTab.attach({ - contentScript: - 'var divs = document.getElementsByTagName("div");' + - 'for (var i = 0; i < divs.length; ++i) {' + - 'divs[i].setAttribute("style", "border: solid red 1px;");' + - '}' - }); - } - }); - -## Destroying Workers ## - -Workers generate a `detach` event when their associated page is closed: that -is, when the tab is closed or the tab's location changes. If -you are maintaining a list of workers belonging to a page mod, you can use -this event to remove workers that are no longer valid. - -For example, if you maintain a list of workers attached to a page mod: - - var workers = []; - - var pageMod = require("page-mod").PageMod({ - include: ['*'], - contentScriptWhen: 'ready', - contentScriptFile: data.url('pagemod.js'), - onAttach: function(worker) { - workers.push(worker); - } - }); - -You can remove workers when they are no longer valid by listening to `detach`: - - var workers = []; - - function detachWorker(worker, workerArray) { - var index = workerArray.indexOf(worker); - if(index != -1) { - workerArray.splice(index, 1); - } - } - - var pageMod = require("page-mod").PageMod({ - include: ['*'], - contentScriptWhen: 'ready', - contentScriptFile: data.url('pagemod.js'), - onAttach: function(worker) { - workers.push(worker); - worker.on('detach', function () { - detachWorker(this, workers); - }); - } - }); - -<api name="PageMod"> -@class -A PageMod object. Once activated a page mod will execute the supplied content -scripts in the context of any pages matching the pattern specified by the -'include' property. -<api name="PageMod"> -@constructor -Creates a PageMod. -@param options {object} - Options for the PageMod, with the following keys: - @prop include {string,array} - A match pattern string or an array of match pattern strings. These define - the pages to which the PageMod applies. See the - [match-pattern](packages/api-utils/match-pattern.html) module for - a description of match pattern syntax. - At least one match pattern must be supplied. - - @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 [contentScriptWhen="end"] {string} - When to load the content scripts. This may take one of the following - values: - - * "start": load content scripts immediately after the document - element for the page is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the page has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - - This property is optional and defaults to "end". - - @prop [contentStyleFile] {string,array} - The local file URLs of stylesheet to load. Content style specified by this - option are loaded *before* those specified by the `contentStyle` option. - Optional. - @prop [contentStyle] {string,array} - The texts of stylesheet rules to add. Content styles specified by this - option are loaded *after* those specified by the `contentStyleFile` option. - Optional. - - @prop [onAttach] {function} -A function to call when the PageMod attaches content scripts to -a matching page. The function will be called with one argument, a `worker` -object which the add-on script can use to communicate with the content scripts -attached to the page in question. - -</api> - -<api name="include"> -@property {List} -A [list](packages/api-utils/list.html) of match pattern strings. These -define the pages to which the page mod applies. See the -[match-pattern](packages/api-utils/match-pattern.html) module for a -description of match patterns. Rules can be added to the list by calling its -`add` method and removed by calling its `remove` method. - -</api> - -<api name="destroy"> -@method -Stops the page mod from making any more modifications. Once destroyed the page -mod can no longer be used. Note that modifications already made to open pages -will not be undone, except for any stylesheet added by `contentStyle` or -`contentStyleFile`, that are unregistered immediately. -</api> - -<api name="attach"> -@event -This event is emitted this event when the page-mod's content scripts are -attached to a page whose URL matches the page-mod's `include` filter. - -@argument {Worker} -The listener function is passed a [`Worker`](packages/api-utils/content/worker.html) object that can be used to communicate -with any content scripts attached to this page. -</api> - -<api name="error"> -@event -This event is emitted when an uncaught runtime error occurs in one of the page -mod's content scripts. - -@argument {Error} -Listeners are passed a single argument, the -[Error](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error) -object. -</api> - -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/page-worker.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/page-worker.md deleted file mode 100644 index 5539c25..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/page-worker.md +++ /dev/null @@ -1,325 +0,0 @@ -<!-- 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 Felipe Gomes [felipc@gmail.com] --> - -The `page-worker` module provides a way to create a permanent, invisible page -and access its DOM. - -The module exports a constructor function `Page`, which constructs a new page -worker. A page worker may be destroyed, after which its memory is freed, and -you must create a new instance to load another page. - -You specify the page to load using the `contentURL` option to the -[`Page()` constructor](packages/addon-kit/page-worker.html#Page(options)). -This can point to a remote file: - - pageWorker = require("page-worker").Page({ - contentScript: "console.log(document.body.innerHTML);", - contentURL: "http://en.wikipedia.org/wiki/Internet" - }); - -It can also point to an HTML file which you've packaged with your add-on. -To do this, save the file in your add-on's `data` directory and create the -URL using the `data.url()` method of the -[`self`](packages/addon-kit/self.html) module: - - pageWorker = require("page-worker").Page({ - contentScript: "console.log(document.body.innerHTML);", - contentURL: require("self").data.url("myFile.html") - }); - -You can load a new page by setting the page worker's `contentURL` property. -In this example we fetch the first paragraph of a page from Wikipedia, then -the first paragraph of a different page: - - var getFirstParagraph = "var paras = document.getElementsByTagName('p');" + - "console.log(paras[0].textContent);" + - "self.port.emit('loaded');" - - pageWorker = require("page-worker").Page({ - contentScript: getFirstParagraph, - contentURL: "http://en.wikipedia.org/wiki/Chalk" - }); - - pageWorker.port.on("loaded", function() { - pageWorker.contentURL = "http://en.wikipedia.org/wiki/Cheese" - }); - -## Scripting Page-Worker Content ## - -To access the page's DOM you need to attach a script to it. In the SDK these -scripts are called "content scripts" because they're explicitly used for -interacting with web content. - -You can specify one or more content scripts to load into the page using the -`contentScript` or `contentScriptFile` options to the -[`Page()` constructor](packages/addon-kit/page-worker.html#Page(options)). -With `contentScript` you pass the script as a string, as in the examples -above. With `contentScriptFile` you pass a URL which points to a script -saved under your add-on's `data` directory. You construct the URL using -the `data.url()` method of the -[`self`](packages/addon-kit/self.html) module. - -While content scripts can access DOM content, they can't access any of the SDK -APIs, so in many cases you'll need to exchange messages between the content -script and your main add-on code for a complete solution. - -For example, the content script might read some content and send it back to -the main add-on, which could store it using the -[`simple-storage`](packages/addon-kit/simple-storage.html) API. You can -communicate with the script using either the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or (preferably, usually) the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. - -For example, this add-on loads a page from Wikipedia, and runs a content script -in it to send all the headers back to the main add-on code: - - var pageWorkers = require("page-worker"); - - // This content script sends header titles from the page to the add-on: - var script = "var elements = document.querySelectorAll('h2 > span'); " + - "for (var i = 0; i < elements.length; i++) { " + - " postMessage(elements[i].textContent) " + - "}"; - - // Create a page worker that loads Wikipedia: - pageWorkers.Page({ - contentURL: "http://en.wikipedia.org/wiki/Internet", - contentScript: script, - contentScriptWhen: "ready", - onMessage: function(message) { - console.log(message); - } - }); - -For conciseness, this example creates the content script as a string and uses -the `contentScript` property. In your own add-ons, you will probably want to -create your content scripts in separate files and pass their URLs using the -`contentScriptFile` property. - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a -static string, don't use <code>contentScript</code>: if you do, you may -have problems getting your add-on approved on AMO.</p> -<p>Instead, keep the script in a separate file and load it using -<code>contentScriptFile</code>. This makes your code easier to maintain, -secure, debug and review.</p> -</div> - -To learn much more about content scripts, see the -[Working with Content Scripts](dev-guide/guides/content-scripts/index.html) -guide. - -<div class="experimental"> -<h3>Scripting Trusted Page Content</h3> - -**Note that the feature described in this section is experimental: we'll -very probably continue to support it, but the name of the `addon` -property might change in a future release.** - -We've already seen that you can package HTML files in your add-on's `data` -directory and load them using `page-worker`. We can call this "trusted" -content, because unlike content loaded from a source outside the -add-on, the add-on author knows exactly what it's doing. To -interact with trusted content you don't need to use content scripts: -you can just include a script from the HTML file in the normal way, using -`<script>` tags. - -Like a content script, these scripts can communicate with the add-on code -using the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. -The crucial difference is that these scripts access the `postMessage` -and `port` objects through the `addon` object, whereas content scripts -access them through the `self` object. - -So given an add-on that loads trusted content and uses content scripts -to access it, there are typically three changes you have to make, if you -want to use normal page scripts instead: - -* **in the content script**: change occurrences of `self` to `addon`. -For example, `self.port.emit("my-event")` becomes -`addon.port.emit("my-event")`. - -* **in the HTML page itself**: add a `<script>` tag to load the script. So -if your content script is saved under `data` as "my-script.js", you need -a line like `<script src="my-script.js"></script>` in the page header. - -* **in the "main.js" file**: remove the `contentScriptFile` option in -the `Page()` constructor. - -</div> - -<api name="Page"> -@class -A `Page` object loads the page specified by its `contentURL` option and -executes any content scripts that have been supplied to it in the -`contentScript` and `contentScriptFile` options. - -The page is not displayed to the user. - -The page worker is loaded as soon as the `Page` object is created and stays -loaded until its `destroy` method is called or the add-on is unloaded. - -<api name="Page"> -@constructor - Creates an uninitialized page worker instance. -@param [options] {object} - The *`options`* parameter is optional, and if given it should be an object - with any of the following keys: - @prop [contentURL] {string} - The URL of the content to load in the panel. - @prop [allow] {object} - An object with keys to configure the permissions on the page worker. The - boolean key `script` controls if scripts from the page are allowed to run. - `script` defaults to true. - @prop [contentScriptFile] {string,array} - A local file URL or an array of local file URLs of content scripts to load. - Content scripts specified by this option are loaded *before* those specified - by the `contentScript` option. See - [Working with Content Scripts](dev-guide/guides/content-scripts/index.html) - for help on setting this property. - @prop [contentScript] {string,array} - A string or an array of strings containing the texts of content scripts to - load. Content scripts specified by this option are loaded *after* those - specified by the `contentScriptFile` option. - @prop [contentScriptWhen="end"] {string} - When to load the content scripts. This may take one of the following - values: - - * "start": load content scripts immediately after the document - element for the page is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the page has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - - This property is optional and defaults to "end". - - @prop [onMessage] {function} - Use this to add a listener to the page worker's `message` event. -</api> - -<api name="port"> -@property {EventEmitter} -[EventEmitter](packages/api-utils/events.html) object that allows you to: - -* send events to the content script using the `port.emit` function -* receive events from the content script using the `port.on` function - -See the guide to -<a href="dev-guide/guides/content-scripts/using-port.html"> -communicating using <code>port</code></a> for details. -</api> - -<api name="contentURL"> -@property {string} -The URL of content to load. This can point to -local content loaded from your add-on's "data" directory or remote content. -Setting it loads the content immediately. -</api> - -<api name="allow"> -@property {object} - A object describing permissions for the content. It contains a single key - named `script` whose value is a boolean that indicates whether or not to - execute script in the content. `script` defaults to true. -</api> - -<api name="contentScriptFile"> -@property {string,array} -A local file URL or an array of local file URLs of content scripts to load. -</api> - -<api name="contentScript"> -@property {string,array} -A string or an array of strings containing the texts of content scripts to -load. -</api> - -<api name="contentScriptWhen"> -@property {string} - When to load the content scripts. This may have one of the following - values: - - * "start": load content scripts immediately after the document - element for the page is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the page has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - -</api> - -<api name="destroy"> -@method -Unloads the page worker. After you destroy a page worker, its memory is freed -and you must create a new instance if you need to load another page. -</api> - -<api name="postMessage"> -@method -Sends a message to the content scripts. -@param message {value} -The message to send. Must be JSON-able. -</api> - -<api name="on"> -@method -Registers an event listener with the page worker. See -[Working with Events](dev-guide/guides/events.html) for help with -events. -@param type {string} -The type of event to listen for. -@param listener {function} -The listener function that handles the event. -</api> - -<api name="removeListener"> -@method -Unregisters an event listener from the page worker. -@param type {string} -The type of event for which `listener` was registered. -@param listener {function} -The listener function that was registered. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this page worker. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the page worker's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a> -</api> - -<api name="error"> -@event -This event is emitted when an uncaught runtime error occurs in one of the -page worker's content scripts. - -@argument {Error} -Listeners are passed a single argument, the -[Error](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error) -object. -</api> - -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/panel.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/panel.md deleted file mode 100644 index 0a85db9..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/panel.md +++ /dev/null @@ -1,607 +0,0 @@ -<!-- 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 Myk Melez [myk@mozilla.org] --> -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -This module exports a single constructor function `Panel` which constructs a -new panel. - -A panel is a dialog. Its content is specified as HTML and you can -execute scripts in it, so the appearance and behaviour of the panel -is limited only by what you can do using HTML, CSS and JavaScript. - -The screenshot below shows a panel whose content is built from the -list of currently open tabs: - -<img class="image-center" src="static-files/media/screenshots/panel-tabs-osx.png" -alt="Simple panel example"> - -Panels are useful for presenting temporary interfaces to users in a way that is -easier for users to ignore and dismiss than a modal dialog, since panels are -hidden the moment users interact with parts of the application interface outside -them. - -A panel's content is loaded as soon as it is created, before the panel is shown, -and the content remains loaded when a panel is hidden, so it is possible -to keep a panel around in the background, updating its content as appropriate -in preparation for the next time it is shown. - -Your add-on can receive notifications when a panel is shown or hidden by -listening to its `show` and `hide` events. - -## Panel Content ## - -The panel's content is specified as HTML, which is loaded from the URL -supplied in the `contentURL` option to the panel's constructor. - -You can load remote HTML into the panel: - - var panel = require("panel").Panel({ - width: 180, - height: 180, - contentURL: "https://en.wikipedia.org/w/index.php?title=Jetpack&useformat=mobile" - }); - - panel.show(); - -<img class="image-center" src="static-files/media/screenshots/wikipedia-jetpack-panel.png" -alt="Wikipedia Jetpack panel"> - -You can also load HTML that's been packaged with your add-on, and this is -most probably how you will create dialogs. To do this, save -the HTML in your add-on's `data` directory and load it using the `data.url()` -method exported by the -[`self`](packages/addon-kit/self.html) module, like this: - - var panel = require("panel").Panel({ - contentURL: require("self").data.url("myFile.html") - }); - - panel.show(); - -## Updating Panel Content ## - -You can update the panel's content simply by setting the panel's `contentURL` -property. - -Here's an add-on that adds two widgets to the add-on bar, one which -shows Google's mobile site and one which shows Bing's mobile site. The widgets -share a panel object, and switch between the two sites by updating the panel's -`contentURL` property: - - var panel = require("panel").Panel({ - contentURL: "about:blank", - onHide: function () { - panel.contentURL = "about:blank"; - } - }); - - require("widget").Widget({ - id: "bing", - label: "Bing", - contentURL: "http://www.bing.com/favicon.ico", - panel: panel, - onClick: function() { - panel.contentURL = "http://m.bing.com/"; - } - }); - - require("widget").Widget({ - id: "google", - label: "Google", - contentURL: "http://www.google.com/favicon.ico", - panel: panel, - onClick: function() { - panel.contentURL = "http://www.google.com/xhtml"; - } - }); - -## Scripting Panel Content ## - -You can't directly access your panel's content from your main add-on code. -To access the panel's content, you need to load a script into the panel. -In the SDK these scripts are called "content scripts" because they're -explicitly used for interacting with web content. - -While content scripts can access the content they're attached to, they can't -use the SDK's APIs. So implementing a complete solution usually means you -have to send messages between the content script and the main add-on code. - -* You can specify one or more content scripts to load into a panel using the -`contentScript` or `contentScriptFile` options to the -[`Panel()` constructor](packages/addon-kit/panel.html#Panel%28options%29). - -* You can communicate with the script using either the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or (preferably, usually) the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. - -For example, here's an add-on whose content script intercepts mouse clicks -on links inside the panel, and sends the target URL to the main add-on -code. The content script sends messages using `self.port.emit()` and the -add-on script receives them using `panel.port.on()`. - - var myScript = "window.addEventListener('click', function(event) {" + - " var t = event.target;" + - " if (t.nodeName == 'A')" + - " self.port.emit('click-link', t.toString());" + - "}, false);" - - var panel = require("panel").Panel({ - contentURL: "http://www.bbc.co.uk/mobile/index.html", - contentScript: myScript - }); - - panel.port.on("click-link", function(url) { - console.log(url); - }); - - panel.show(); - -This example uses `contentScript` to supply the script as a string. It's -usually better practice to use `contentScriptFile`, which is a URL pointing -to a script file saved under your add-on's `data` directory. - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a -static string, don't use <code>contentScript</code>: if you do, you may -have problems getting your add-on approved on AMO.</p> -<p>Instead, keep the script in a separate file and load it using -<code>contentScriptFile</code>. This makes your code easier to maintain, -secure, debug and review.</p> -</div> - -<img class="image-right" src="static-files/media/screenshots/text-entry-panel.png" -alt="Text entry panel"> - -### Getting User Input ### - -The following add-on adds a widget which displays a panel when -clicked. The panel just contains a `<textarea>` element: when the user -presses the `return` key, the contents of the `<textarea>` is sent to the -main add-on code. - -The add-on consists of three files: - -* **`main.js`**: the main add-on code, that creates the widget and panel -* **`get-text.js`**: the content script that interacts with the panel content -* **`text-entry.html`**: the panel content itself, specified as HTML - -"main.js" is saved in your add-on's `lib` directory, and the other two files -go in your add-on's `data` directory: - -<pre> -my-addon/ - data/ - get-text.js - text-entry.html - lib/ - main.js -</pre> - -The "main.js" looks like this: - - var data = require("self").data; - - // Create a panel whose content is defined in "text-entry.html". - // Attach a content script called "get-text.js". - var text_entry = require("panel").Panel({ - width: 212, - height: 200, - contentURL: data.url("text-entry.html"), - contentScriptFile: data.url("get-text.js") - }); - - // Send the content script a message called "show" when - // the panel is shown. - text_entry.on("show", function() { - text_entry.port.emit("show"); - }); - - // Listen for messages called "text-entered" coming from - // the content script. The message payload is the text the user - // entered. - // In this implementation we'll just log the text to the console. - text_entry.port.on("text-entered", function (text) { - console.log(text); - text_entry.hide(); - }); - - // Create a widget, and attach the panel to it, so the panel is - // shown when the user clicks the widget. - require("widget").Widget({ - label: "Text entry", - id: "text-entry", - contentURL: "http://www.mozilla.org/favicon.ico", - panel: text_entry - }); - -The content script "get-text.js" looks like this: - - self.port.on("show", function (arg) { - var textArea = document.getElementById('edit-box'); - textArea.focus(); - // When the user hits return, send a message to main.js. - // The message payload is the contents of the edit box. - textArea.onkeyup = function(event) { - if (event.keyCode == 13) { - // Remove the newline. - text = textArea.value.replace(/(\r\n|\n|\r)/gm,""); - self.port.emit("text-entered", text); - textArea.value = ''; - } - }; - }); - -Finally, the "text-entry.html" file defines the `<textarea>` element: - -<pre class="brush: html"> - -<html> - -<head> - <style type="text/css" media="all"> - textarea { - margin: 10px; - } - </style> -</head> - -<body> - <textarea rows="10" cols="20" id="edit-box"></textarea> -</body> - -</html> -</pre> - -To learn much more about content scripts, see the -[Working with Content Scripts](dev-guide/guides/content-scripts/index.html) -guide. - -<div class="experimental"> -<h3>Scripting Trusted Panel Content</h3> - -**Note that the feature described in this section is experimental: we'll -very probably continue to support it, but the name of the `addon` -property might change in a future release.** - -We've already seen that you can package HTML files in your add-on's `data` -directory and use them to define the panel's content. We can call this -"trusted" content, because unlike content loaded from a source outside the -add-on, the add-on author knows exactly what it's doing. To -interact with trusted content you don't need to use content scripts: -you can just include a script from the HTML file in the normal way, using -`script` tags. - -Like a content script, these scripts can communicate with the add-on code -using the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. -The crucial difference is that these scripts access the `postMessage` -and `port` objects through the `addon` object, whereas content scripts -access them through the `self` object. - -To show the difference, we can easily convert the `text-entry` add-on above -to use normal page scripts instead of content scripts. - -The main add-on code is exactly the same as the main add-on code in the -previous example, except that we don't attach a content script: - - var data = require("self").data; - - // Create a panel whose content is defined in "text-entry.html". - var text_entry = require("panel").Panel({ - width: 212, - height: 200, - contentURL: data.url("text-entry.html"), - }); - - // Send the page script a message called "show" when - // the panel is shown. - text_entry.on("show", function() { - text_entry.port.emit("show"); - }); - - // Listen for messages called "text-entered" coming from - // the page script. The message payload is the text the user - // entered. - // In this implementation we'll just log the text to the console. - text_entry.port.on("text-entered", function (text) { - console.log(text); - text_entry.hide(); - }); - - // Create a widget, and attach the panel to it, so the panel is - // shown when the user clicks the widget. - require("widget").Widget({ - label: "Text entry", - id: "text-entry", - contentURL: "http://www.mozilla.org/favicon.ico", - panel: text_entry - }); - -The page script is exactly the same as the content script above, except -that instead of `self`, we use `addon` to access the messaging APIs: - - addon.port.on("show", function (arg) { - var textArea = document.getElementById('edit-box'); - textArea.focus(); - // When the user hits return, send a message to main.js. - // The message payload is the contents of the edit box. - textArea.onkeyup = function(event) { - if (event.keyCode == 13) { - // Remove the newline. - text = textArea.value.replace(/(\r\n|\n|\r)/gm,""); - addon.port.emit("text-entered", text); - textArea.value = ''; - } - }; - }); - -Finally, the HTML file now references "get-text.js" inside a `script` tag: - -<pre class="brush: html"> - -<html> - -<head> - <style type="text/css" media="all"> - textarea { - margin: 10px; - } - </style> - <script src="get-text.js"></script> -</head> - -<body> - <textarea rows="10" cols="20" id="edit-box"></textarea> -</body> - -</html> -</pre> -</div> - -## Styling Trusted Panel Content ## - -When the panel's content is specified using an HTML file in your `data` -directory, you can style it using CSS, either embedding the CSS directly -in the file or referencing a CSS file stored under `data`. - -The panel's default style is different for each operating system: - -<img class="image-center" src="static-files/media/screenshots/panel-default-style.png" -alt="OS X panel default style"> - -This helps to ensure that the panel's style is consistent with the dialogs -displayed by Firefox and other applications, but means you need to take care -when applying your own styles. For example, if you set the panel's -`background-color` property to `white` and do not set the `color` property, -then the panel's text will be invisible on OS X although it looks fine on Ubuntu. - -<api name="Panel"> -@class -The Panel object represents a floating modal dialog that can by an add-on to -present user interface content. - -Once a panel object has been created it can be shown and hidden using its -`show()` and `hide()` methods. Once a panel is no longer needed it can be -deactivated using `destroy()`. - -The content of a panel is specified using the `contentURL` option. An add-on -can interact with the content of a panel using content scripts which it -supplies in the `contentScript` and/or `contentScriptFile` options. For example, -a content script could create a menu and send the user's selection to the -add-on. - -<api name="Panel"> -@constructor -Creates a panel. -@param options {object} - Options for the panel, with the following keys: - @prop [width] {number} - The width of the panel in pixels. Optional. - @prop [height] {number} - The height of the panel in pixels. Optional. - @prop [contentURL] {string} - The URL of the content to load in the panel. - @prop [allow] {object} - An optional object describing permissions for the content. It should - contain a single key named `script` whose value is a boolean that indicates - whether or not to execute script in the content. `script` defaults to true. - @prop [contentScriptFile] {string,array} - A local file URL or an array of local file URLs of content scripts to load. - Content scripts specified by this property are loaded *before* those - specified by the `contentScript` property. - @prop [contentScript] {string,array} - A string or an array of strings containing the texts of content scripts to - load. Content scripts specified by this property are loaded *after* those - specified by the `contentScriptFile` property. - @prop [contentScriptWhen="end"] {string} - When to load the content scripts. This may take one of the following - values: - - * "start": load content scripts immediately after the document - element for the panel is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the panel has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - - This property is optional and defaults to "end". - - @prop [onMessage] {function} - Include this to listen to the panel's `message` event. - @prop [onShow] {function} - Include this to listen to the panel's `show` event. - @prop [onHide] {function} - Include this to listen to the panel's `hide` event. -</api> - -<api name="port"> -@property {EventEmitter} -[EventEmitter](packages/api-utils/events.html) object that allows you to: - -* send events to the content script using the `port.emit` function -* receive events from the content script using the `port.on` function - -See the guide to -<a href="dev-guide/guides/content-scripts/using-port.html"> -communicating using <code>port</code></a> for details. -</api> - -<api name="isShowing"> -@property {boolean} -Tells if the panel is currently shown or not. This property is read-only. -</api> - -<api name="height"> -@property {number} -The height of the panel in pixels. -</api> - -<api name="width"> -@property {number} -The width of the panel in pixels. -</api> - -<api name="contentURL"> -@property {string} -The URL of content loaded into the panel. This can point to -local content loaded from your add-on's "data" directory or remote content. -Setting it updates the panel's content immediately. -</api> - -<api name="allow"> -@property {object} -An object describing permissions for the content. It contains a single key -named `script` whose value is a boolean that indicates whether or not to execute -script in the content. -</api> - -<api name="contentScriptFile"> -@property {string,array} -A local file URL or an array of local file URLs of content scripts to load. -Content scripts specified by this property are loaded *before* those -specified by the `contentScript` property. -</api> - -<api name="contentScript"> -@property {string,array} -A string or an array of strings containing the texts of content scripts to -load. Content scripts specified by this property are loaded *after* those -specified by the `contentScriptFile` property. -</api> - -<api name="contentScriptWhen"> -@property {string} -When to load the content scripts. This may have one of the following -values: - -* "start": load content scripts immediately after the document -element for the panel is inserted into the DOM, but before the DOM content -itself has been loaded -* "ready": load content scripts once DOM content has been loaded, -corresponding to the -[DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) -event -* "end": load content scripts once all the content (DOM, JS, CSS, -images) for the panel has been loaded, at the time the -[window.onload event](https://developer.mozilla.org/en/DOM/window.onload) -fires - -</api> - -<api name="destroy"> -@method -Destroys the panel, unloading any content that was loaded in it. Once -destroyed, the panel can no longer be used. If you just want to hide -the panel and might show it later, use `hide` instead. -</api> - -<api name="postMessage"> -@method -Sends a message to the content scripts. -@param message {value} -The message to send. Must be stringifiable to JSON. -</api> - -<api name="show"> -@method -Displays the panel. -</api> - -<api name="hide"> -@method -Stops displaying the panel. -</api> - -<api name="resize"> -@method -Resizes the panel. -@param width {number} -The new width of the panel in pixels. -@param height {number} -The new height of the panel in pixels. -</api> - -<api name="on"> -@method - Registers an event listener with the panel. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. -</api> - -<api name="removeListener"> -@method - Unregisters an event listener from the panel. -@param type {string} - The type of event for which `listener` was registered. -@param listener {function} - The listener function that was registered. -</api> - -<api name="show"> -@event -This event is emitted when the panel is shown. -</api> - -<api name="hide"> -@event -This event is emitted when the panel is hidden. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this panel. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the panel's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="error"> -@event -This event is emitted when an uncaught runtime error occurs in one of the -panel's content scripts. - -@argument {Error} -Listeners are passed a single argument, the -[Error](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Error) -object. -</api> - -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/passwords.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/passwords.md deleted file mode 100644 index 8ee6109..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/passwords.md +++ /dev/null @@ -1,568 +0,0 @@ -<!-- 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 Irakli Gozalishvili [gozala@mozilla.com] --> - -The `passwords` module allows add-ons to interact with Firefox's -[Password Manager](http://support.mozilla.com/en-US/kb/Remembering%20passwords) -to add, retrieve and remove stored credentials. - -A _credential_ is the set of information a user supplies to authenticate -herself with a service. Typically a credential consists of a username and a -password. - -Using this module you can: - -1. **Search** for credentials which have been stored in the Password Manager. - You can then use the credentials to access their related service (for - example, by logging into a web site). - -2. **Store** credentials in the Password Manager. You can store different sorts - of credentials, as outlined in the "Credentials" section below. - -3. **Remove** stored credentials from the Password Manager. - -## Credentials ## - -In this API, credentials are represented by objects. - -You create credential objects to pass into the API, and the API also returns -credential objects to you. The sections below explain both the properties you -should define on credential objects and the properties you can expect on -credential objects returned by the API. - -All credential objects include `username` and `password` properties. Different -sorts of stored credentials include various additional properties, as -outlined in this section. - -You can use the Passwords API with three sorts of credentials: - -* Add-on credentials -* HTML form credentials -* HTTP Authentication credentials - -### Add-on Credential ### - -These are associated with your add-on rather than a particular web site. -They contain the following properties: - -<table> -<colgroup> -<col width="25%"> -</colgroup> -<tr> - <td> - <code>username</code> - </td> - <td> - The username. - </td> -</tr> - -<tr> - <td> - <code>password</code> - </td> - <td> - The password. - </td> -</tr> - -<tr> - <td> - <code>url</code> - </td> - <td> - <p>For an add-on credential, this property is of the form:<br><code> - addon:<addon-id></code>, where <code><addon-id></code> - is the add-on's - <a href="dev-guide/guides/program-id.html"> - Program ID</a>.</p> - <p>You don't supply this value when storing an add-on credential: it is - automatically generated for you. However, you can use it to work out - which stored credentials belong to your add-on by comparing it with the - <code>uri</code> property of the - <a href="packages/addon-kit/self.html"><code>self</code></a> - module.</p> - </td> -</tr> - -<tr> - <td> - <code>realm</code> - </td> - <td> - <p>You can use this as a name for the credential, to distinguish - it from any other credentials you've stored.</p> - <p>The realm is displayed - in Firefox's Password Manager, under "Site", in brackets after the URL. - For example, if the realm for a credential is "User Registration", then - its "Site" field will look something like:</p> - <code>addon:jid0-01mBBFyu0ZAXCFuB1JYKooSTKIc (User Registration)</code> - </td> -</tr> - -</table> - -### HTML Form Credential ### - -If a web service uses HTML forms to authenticate its users, then the -corresponding credential is an HTML Form credential. - -It contains the following properties: - -<table> -<colgroup> -<col width="25%"> -</colgroup> -<tr> - <td> - <code>username</code> - </td> - <td> - The username. - </td> -</tr> - -<tr> - <td> - <code>password</code> - </td> - <td> - The password. - </td> -</tr> - -<tr> - <td> - <code>url</code> - </td> - <td> - The URL for the web service which requires the credential. - You should omit anything after the hostname and (optional) port. - </td> -</tr> - -<tr> - <td> - <code>formSubmitURL</code> - </td> - <td> - The value of the form's "action" attribute. - You should omit anything after the hostname and (optional) port. - If the form doesn't contain an "action" attribute, this property should - match the <code>url</code> property. - </td> -</tr> - -<tr> - <td> - <code>usernameField</code> - </td> - <td> - The value of the "name" attribute for the form's username field. - </td> -</tr> - -<tr> - <td> - <code>passwordField</code> - </td> - <td> - The value of the "name" attribute for the form's password field. - </td> -</tr> - -</table> - -So: given a form at `http://www.example.com/login` -with the following HTML: - -<script type="syntaxhighlighter" class="brush: html"><![CDATA[ -<form action="http://login.example.com/foo/authenticate.cgi"> - <div>Please log in.</div> - <label>Username:</label> <input type="text" name="uname"> - <label>Password:</label> <input type="password" name="pword"> -</form> -]]> -</script> - -The corresponding values for the credential (excluding username and password) -should be: - -<pre> - url: "http://www.example.com" - formSubmitURL: "http://login.example.com" - usernameField: "uname" - passwordField: "pword" -</pre> - -Note that for both `url` and `formSubmitURL`, the portion of the URL after the -hostname is omitted. - -### HTTP Authentication Credential ### - -These are used to authenticate the user to a web site -which uses HTTP Authentication, as detailed in -[RFC 2617](http://tools.ietf.org/html/rfc2617). -They contain the following properties: - -<table> -<colgroup> -<col width="25%"> -</colgroup> -<tr> - <td> - <code>username</code> - </td> - <td> - The username. - </td> -</tr> - -<tr> - <td> - <code>password</code> - </td> - <td> - The password. - </td> -</tr> - -<tr> - <td> - <code>url</code> - </td> - <td> - The URL for the web service which requires the credential. - You should omit anything after the hostname and (optional) port. - </td> -</tr> - -<tr> - <td> - <code>realm</code> - </td> - <td> - <p>The WWW-Authenticate response header sent by the server may include a - "realm" field as detailed in - <a href="http://tools.ietf.org/html/rfc2617">RFC 2617</a>. If it does, - this property contains the value for the "realm" field. Otherwise, it is - omitted.</p> - <p>The realm is displayed in Firefox's Password Manager, under "Site", - in brackets after the URL.</p> - </td> -</tr> - -</table> - -So: if a web server at `http://www.example.com` requested authentication with -a response code like this: - -<pre> - HTTP/1.0 401 Authorization Required - Server: Apache/1.3.27 - WWW-Authenticate: Basic realm="ExampleCo Login" -</pre> - -The corresponding values for the credential (excluding username and password) -should be: - -<pre> - url: "http://www.example.com" - realm: "ExampleCo Login" -</pre> - -## onComplete and onError ## - -This API is explicitly asynchronous, so all its functions take two callback -functions as additional options: `onComplete` and `onError`. - -`onComplete` is called when the operation has completed successfully and -`onError` is called when the function encounters an error. - -Because the `search` function is expected to return a list of matching -credentials, its `onComplete` option is mandatory. Because the other functions -don't return a value in case of success their `onComplete` options are -optional. - -For all functions, `onError` is optional. - -<api name="search"> -@function - -This function is used to retrieve a credential, or a list of credentials, -stored in the Password Manager. - -You pass it any subset of the possible properties a credential can contain. -Credentials which match all the properties you supplied are returned as an -argument to the `onComplete` callback. - -So if you pass in an empty set of properties, all stored credentials are -returned: - - function show_all_passwords() { - require("passwords").search({ - onComplete: function onComplete(credentials) { - credentials.forEach(function(credential) { - console.log(credential.username); - console.log(credential.password); - }); - } - }); - } - -If you pass it a single property, only credentials matching that property are -returned: - - function show_passwords_for_joe() { - require("passwords").search({ - username: "joe", - onComplete: function onComplete(credentials) { - credentials.forEach(function(credential) { - console.log(credential.username); - console.log(credential.password); - }); - } - }); - } - -If you pass more than one property, returned credentials must match all of -them: - - function show_google_password_for_joe() { - require("passwords").search({ - username: "joe", - url: "https://www.google.com", - onComplete: function onComplete(credentials) { - credentials.forEach(function(credential) { - console.log(credential.username); - console.log(credential.password); - }); - } - }); - } - -To retrieve only credentials associated with your add-on, use the `url` -property, initialized from `self.uri`: - - function show_my_addon_passwords() { - require("passwords").search({ - url: require("self").uri, - onComplete: function onComplete(credentials) { - credentials.forEach(function(credential) { - console.log(credential.username); - console.log(credential.password); - }); - } - }); - } - -@param options {object} -The `options` object may contain any credential properties. It is used to -restrict the set of credentials returned by the `search` function. - -See "Credentials" above for details on what these properties should be. - -Additionally, `options` must contain a function assigned to its `onComplete` -property: this is called when the function completes and is passed the set of -credentials retrieved. - -`options` may contain a function assigned to its `onError` property, which is -called if the function encounters an error. `onError` is passed the error as an -[nsIException](https://developer.mozilla.org/en/nsIException) object. - -@prop [username] {string} -The username for the credential. - -@prop [password] {string} -The password for the credential. - -@prop [url] {string} -The URL associated with the credential. - -@prop [formSubmitURL] {string} -The URL an HTML form credential is submitted to. - -@prop [realm] {string} -For HTTP Authentication credentials, the realm for which the credential was -requested. For add-on credentials, a name for the credential. - -@prop [usernameField] {string} -The value of the `name` attribute for the user name input field in a form. - -@prop [passwordField] {string} -The value of the `name` attribute for the password input field in a form. - -@prop onComplete {function} -The callback function that is called once the function completes successfully. -It is passed all the matching credentials as a list. This is the only -mandatory option. - -@prop [onError] {function} -The callback function that is called if the function failed. The -callback is passed an `error` containing a reason of a failure: this is an -[nsIException](https://developer.mozilla.org/en/nsIException) object. - -</api> - -<api name="store"> -@function - -This function is used to store a credential in the Password Manager. - -It takes an `options` object as an argument: this contains all the properties -for the new credential. - -As different sorts of credentials contain different properties, the -appropriate options differ depending on the sort of credential being stored. - -To store an add-on credential: - - require("passwords").store({ - realm: "User Registration", - username: "joe", - password: "SeCrEt123", - }); - -To store an HTML form credential: - - require("passwords").store({ - url: "http://www.example.com", - formSubmitURL: "http://login.example.com", - username: "joe", - usernameField: "uname", - password: "SeCrEt123", - passwordField: "pword" - }); - -To store an HTTP Authentication credential: - - require("passwords").store({ - url: "http://www.example.com", - realm: "ExampleCo Login", - username: "joe", - password: "SeCrEt123", - }); - -See "Credentials" above for more details on how to set these properties. - -The options parameter may also include `onComplete` and `onError` -callback functions, which are called when the function has completed -successfully and when it encounters an error, respectively. These options -are both optional. - -@param options {object} -An object containing the properties of the credential to be stored, and -optional `onComplete` and `onError` callback functions. - -@prop username {string} -The username for the credential. - -@prop password {string} -The password for the credential. - -@prop [url] {string} -The URL to which the credential applies. Omitted for add-on -credentials. - -@prop [formSubmitURL] {string} -The URL a form-based credential was submitted to. Omitted for add-on -credentials and HTTP Authentication credentials. - -@prop [realm] {string} -For HTTP Authentication credentials, the realm for which the credential was -requested. For add-on credentials, a name for the credential. - -@prop [usernameField] {string} -The value of the `name` attribute for the username input in a form. -Omitted for add-on credentials and HTTP Authentication credentials. - -@prop [passwordField] {string} -The value of the `name` attribute for the password input in a form. -Omitted for add-on credentials and HTTP Authentication credentials. - -@prop [onComplete] {function} -The callback function that is called once the function completes successfully. - -@prop [onError] {function} -The callback function that is called if the function failed. The -callback is passed an `error` argument: this is an -[nsIException](https://developer.mozilla.org/en/nsIException) object. - -</api> - -<api name="remove"> -@function - -Removes a stored credential. You supply it all the properties of the credential -to remove, along with optional `onComplete` and `onError` callbacks. - -Because you must supply all the credential's properties, it may be convenient -to call `search` first, and use its output as the input to `remove`. For -example, to remove all of joe's stored credentials: - - require("passwords").search({ - username: "joe", - onComplete: function onComplete(credentials) { - credentials.forEach(require("passwords").remove); - }) - }); - -To change an existing credential just call `store` after `remove` succeeds: - - require("passwords").remove({ - realm: "User Registration", - username: "joe", - password: "SeCrEt123" - onComplete: function onComplete() { - require("passwords").store({ - realm: "User Registration", - username: "joe", - password: "{{new password}}" - }) - } - }); - -@param options {object} - -An object containing all the properties of the credential to be removed, -and optional `onComplete` and `onError` callback functions. - -@prop username {string} -The username for the credential. - -@prop password {string} -The password for the credential. - -@prop [url] {string} -The URL to which the credential applies. Omitted for add-on -credentials. - -@prop [formSubmitURL] {string} -The URL a form-based credential was submitted to. Omitted for add-on -credentials and HTTP Authentication credentials. - -@prop [realm] {string} -For HTTP Authentication credentials, the realm for which the credential was -requested. For add-on credentials, a name for the credential. - -@prop [usernameField] {string} -The value of the `name` attribute for the username input in a form. -Omitted for add-on credentials and HTTP Authentication credentials. - -@prop [passwordField] {string} -The value of the `name` attribute for the password input in a form. -Omitted for add-on credentials and HTTP Authentication credentials. - -@prop [onComplete] {function} -The callback function that is called once the function has completed -successfully. - -@prop [onError] {function} -The callback function that is called if the function failed. The -callback is passed an `error` argument: this is an -[nsIException](https://developer.mozilla.org/en/nsIException) object. - -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/private-browsing.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/private-browsing.md deleted file mode 100644 index e553357..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/private-browsing.md +++ /dev/null @@ -1,50 +0,0 @@ -<!-- 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 Paul O'Shannessy [paul@oshannessy.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -The `private-browsing` module allows you to access Firefox's private browsing -mode, detecting if it is active and when its state changes. - -This module is available in all applications. However, only Firefox will ever -transition into or out of private browsing mode. For all other applications, -`pb.isActive` will always be `false`, and none of the events will be emitted. - -<api name="isActive"> -@property {boolean} - This read-only boolean is true if private browsing mode is turned on. -</api> - -<api name="activate"> -@function - Turns on private browsing mode. -</api> - -<api name="deactivate"> -@function - Turns off private browsing mode. -</api> - -<api name="start"> -@event -Emitted immediately after the browser enters private browsing mode. - - var pb = require("private-browsing"); - pb.on("start", function() { - // Do something when the browser starts private browsing mode. - }); - -</api> - -<api name="stop"> -@event -Emitted immediately after the browser exits private browsing mode. - - var pb = require("private-browsing"); - pb.on("stop", function() { - // Do something when the browser stops private browsing mode. - }); -</api>
\ No newline at end of file diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/request.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/request.md deleted file mode 100644 index af37ecf..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/request.md +++ /dev/null @@ -1,203 +0,0 @@ -<!-- 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/. --> - -The `request` module lets you make simple yet powerful network requests. - -<api name="Request"> -@class -The `Request` object is used to make `GET`, `POST` or `PUT` network requests. -It is constructed with a URL to which the request is sent. Optionally the user -may specify a collection of headers and content to send alongside the request -and a callback which will be executed once the request completes. - -Once a `Request` object has been created a `GET` request can be executed by -calling its `get()` method, a `POST` request by calling its `post()` method, -or a `PUT` request by calling its `put()` method. - -When the server completes the request, the `Request` object emits a "complete" -event. Registered event listeners are passed a `Response` object. - -Each `Request` object is designed to be used once. Once `GET`, `POST` or `PUT` -are called, attempting to call either will throw an error. - -Since the request is not being made by any particular website, requests made -here are not subject to the same-domain restriction that requests made in web -pages are subject to. - -With the exception of `response`, all of a `Request` object's properties -correspond with the options in the constructor. Each can be set by simply -performing an assignment. However, keep in mind that the same validation rules -that apply to `options` in the constructor will apply during assignment. Thus, -each can throw if given an invalid value. - -The example below shows how to use Request to get the most recent public tweet. - - var Request = require("request").Request; - var latestTweetRequest = Request({ - url: "http://api.twitter.com/1/statuses/public_timeline.json", - onComplete: function (response) { - var tweet = response.json[0]; - console.log("User: " + tweet.user.screen_name); - console.log("Tweet: " + tweet.text); - } - }); - - // Be a good consumer and check for rate limiting before doing more. - Request({ - url: "http://api.twitter.com/1/account/rate_limit_status.json", - onComplete: function (response) { - if (response.json.remaining_hits) { - latestTweetRequest.get(); - } else { - console.log("You have been rate limited!"); - } - } - }).get(); - -<api name="Request"> -@constructor -This constructor creates a request object that can be used to make network -requests. The constructor takes a single parameter `options` which is used to -set several properties on the resulting `Request`. -@param options {object} - @prop url {string} - This is the url to which the request will be made. - - @prop [onComplete] {function} - This function will be called when the request has received a response (or in - terms of XHR, when `readyState == 4`). The function is passed a `Response` - object. - - @prop [headers] {object} - An unordered collection of name/value pairs representing headers to send - with the request. - - @prop [content] {string,object} - The content to send to the server. If `content` is a string, it should be - URL-encoded (use `encodeURIComponent`). If `content` is an object, it - should be a collection of name/value pairs. Nested objects & arrays should - encode safely. - - For `GET` requests, the query string (`content`) will be appended to the - URL. For `POST` and `PUT` requests, the query string will be sent as the body - of the request. - - @prop [contentType] {string} - The type of content to send to the server. This explicitly sets the - `Content-Type` header. The default value is `application/x-www-form-urlencoded`. - - @prop [overrideMimeType] {string} - Use this string to override the MIME type returned by the server in the - response's Content-Type header. You can use this to treat the content as a - different MIME type, or to force text to be interpreted using a specific - character. - - For example, if you're retrieving text content which was encoded as - ISO-8859-1 (Latin 1), it will be given a content type of "utf-8" and - certain characters will not display correctly. To force the response to - be interpreted as Latin-1, use `overrideMimeType`: - - var Request = require("request").Request; - var quijote = Request({ - url: "http://www.latin1files.org/quijote.txt", - overrideMimeType: "text/plain; charset=latin1", - onComplete: function (response) { - console.log(response.text); - } - }); - - quijote.get(); - -</api> - -<api name="url"> -@property {string} -</api> - -<api name="headers"> -@property {object} -</api> - -<api name="content"> -@property {string,object} -</api> - -<api name="contentType"> -@property {string} -</api> - -<api name="response"> -@property {Response} -</api> - -<api name="get"> -@method -Make a `GET` request. -@returns {Request} -</api> - -<api name="post"> -@method -Make a `POST` request. -@returns {Request} -</api> - -<api name="put"> -@method -Make a `PUT` request. -@returns {Request} -</api> - -<api name="complete"> -@event -The `Request` object emits this event when the request has completed and a -response has been received. - -@argument {Response} -Listener functions are passed the response to the request as a `Response` object. -</api> - -</api> - - -<api name="Response"> -@class -The Response object contains the response to a network request issued using a -`Request` object. It is returned by the `get()`, `post()` or `put()` method of a -`Request` object. - -All members of a `Response` object are read-only. -<api name="text"> -@property {string} -The content of the response as plain text. -</api> - -<api name="json"> -@property {object} -The content of the response as a JavaScript object. The value will be `null` -if the document cannot be processed by `JSON.parse`. -</api> - -<api name="status"> -@property {string} -The HTTP response status code (e.g. *200*). -</api> - -<api name="statusText"> -@property {string} -The HTTP response status line (e.g. *OK*). -</api> - -<api name="headers"> -@property {object} -The HTTP response headers represented as key/value pairs. - -To print all the headers you can do something like this: - - for (var headerName in response.headers) { - console.log(headerName + " : " + response.headers[headerName]); - } - -</api> -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/selection.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/selection.md deleted file mode 100644 index f2d4ca5..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/selection.md +++ /dev/null @@ -1,90 +0,0 @@ -<!-- 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 Eric H. Jung [eric.jung@yahoo.com] --> -<!-- contributed by Irakli Gozalishvili [gozala@mozilla.com] --> - -The `selection` module provides a means to get and set text and HTML selections -in the current Firefox page. It can also observe new selections. - -Registering for Selection Notifications ---------------------------------------- - -To be notified when the user makes a selection, register a listener for the -"select" event. Each listener will be called after a selection is made. - - function myListener() { - console.log("A selection has been made."); - } - var selection = require("selection"); - selection.on('select', myListener); - - // You can remove listeners too. - selection.removeListener('select', myListener); - -Iterating Over Discontiguous Selections ---------------------------------------- - -Discontiguous selections can be accessed by iterating over the `selection` -module itself. Each iteration yields a `Selection` object from which `text`, -`html`, and `isContiguous` properties can be accessed. - - -Examples --------- - -Log the current contiguous selection as text: - - var selection = require("selection"); - if (selection.text) - console.log(selection.text); - -Log the current discontiguous selections as HTML: - - var selection = require("selection"); - if (!selection.isContiguous) { - for (var subselection in selection) { - console.log(subselection.html); - } - } - -Surround HTML selections with delimiters: - - var selection = require("selection"); - selection.on('select', function () { - selection.html = "\\\" + selection.html + "///"; - }); - -<api name="text"> -@property {string} - Gets or sets the current selection as plain text. Setting the selection - removes all current selections, inserts the specified text at the location of - the first selection, and selects the new text. Getting the selection when - there is no current selection returns `null`. Setting the selection when there - is no current selection throws an exception. Getting the selection when - `isContiguous` is `true` returns the text of the first selection. -</api> - -<api name="html"> -@property {string} - Gets or sets the current selection as HTML. Setting the selection removes all - current selections, inserts the specified text at the location of the first - selection, and selects the new text. Getting the selection when there is no - current selection returns `null`. Setting the selection when there is no - current selection throws an exception. Getting the selection when - `isContiguous` is `true` returns the text of the first selection. -</api> - -<api name="isContiguous"> -@property {boolean} - `true` if the current selection is a single, contiguous selection, and `false` - if there are two or more discrete selections, each of which may or may not be - spatially adjacent. (Discontiguous selections can be created by the user with - Ctrl+click-and-drag.) -</api> - -<api name="select"> -@event - This event is emitted whenever the user makes a new selection in a page. -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/self.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/self.md deleted file mode 100644 index 8ccdb01..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/self.md +++ /dev/null @@ -1,79 +0,0 @@ -<!-- 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/. --> - -<!-- edited by Erik Vold [erikvvold@gmail.com] --> - -The `self` module provides access to data that is bundled with the add-on -as a whole. It also provides access to the -[Program ID](dev-guide/guides/program-id.html), a value which is -unique for each add-on. - -Note that the `self` module is completely different from the global `self` -object accessible to content scripts, which is used by a content script to -[communicate with the add-on code](dev-guide/guides/content-scripts/using-port.html). - -<api name="id"> -@property {string} -This property is a printable string that is unique for each add-on. It comes -from the `id` property set in the `package.json` file in the main package -(i.e. the package in which you run `cfx xpi`). While not generally of use to -add-on code directly, it can be used by internal API code to index local -storage and other resources that are associated with a particular add-on. -Eventually, this ID will be unspoofable (see -[JEP 118](https://wiki.mozilla.org/Labs/Jetpack/Reboot/JEP/118) for details). -</api> - -<api name="name"> -@property {string} -This property contains the add-on's short name. It comes from the `name` -property in the main package's `package.json` file. -</api> - -<api name="version"> -@property {string} -This property contains the add-on's version string. It comes from the -`version` property set in the `package.json` file in the main package. -</api> - -<api name="data"> -@property {object} -The `data` object is used to access data that was bundled with the add-on. -This data lives in the main package's `data/` directory, immediately below -the `package.json` file. All files in this directory will be copied into the -XPI and made available through the `data` object. - -The [Package Specification](dev-guide/package-spec.html) -section explains the `package.json` file. - -<api name="data.load"> -@method -The `data.load(NAME)` method returns the contents of an embedded data file, -as a string. It is most useful for data that will be modified or parsed in -some way, such as JSON, XML, plain text, or perhaps an HTML template. For -data that can be displayed directly in a content frame, use `data.url(NAME)`. -@param name {string} The filename to be read, relative to the - package's `data` directory. Each package that uses the `self` module - will see its own `data` directory. -@returns {string} -</api> - -<api name="data.url"> -@method -The `data.url(NAME)` method returns a url that points at an embedded -data file. It is most useful for data that can be displayed directly in a -content frame. The url can be passed to a content frame constructor, such -as the Panel: - - var self = require("self"); - var myPanel = require("panel").Panel({ - contentURL: self.data.url("my-panel-content.html") - }); - myPanel.show(); - -@param name {string} The filename to be read, relative to the - package's `data` directory. Each package that uses the `self` module - will see its own `data` directory. -@returns {String} -</api> -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-prefs.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-prefs.md deleted file mode 100644 index b3cd076..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-prefs.md +++ /dev/null @@ -1,75 +0,0 @@ -<!-- 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 Erik Vold [erikvvold@gmail.com] --> - -#### *Experimental* - -The `simple-prefs` module lets you easily and persistently store preferences -across application restarts, which can be configured by users in the -Add-ons Manager. - -Introduction ------------- - -With the simple preferences module you can store booleans, integers, and string -values. - - -Inline Options & Default Values -------------------------------- - -In order to have a `options.xul` (for inline options) generated, or a -`defaults/preferences/prefs.js` for default preferences, you will need to -define the preferences in your `package.json`, like so: - - { - "fullName": "Example Add-on", - ... - "preferences": [{ - "name": "somePreference", - "title": "Some preference title", - "description": "Some short description for the preference", - "type": "string", - "value": "this is the default string value" - }] - } - - -<api name="prefs"> -@property {object} - *experimental* A persistent object private to your add-on. Properties with boolean, - number, and string values will be persisted in the Mozilla preferences system. -</api> - - -<api name="on"> -@function - *experimental* Registers an event `listener` that will be called when a preference is changed. - -**Example:** - - function onPrefChange(prefName) { - console.log("The " + prefName + " preference changed."); - } - require("simple-prefs").on("somePreference", onPrefChange); - require("simple-prefs").on("someOtherPreference", onPrefChange); - - -@param prefName {String} - The name of the preference to watch for changes. -@param listener {Function} - The listener function that processes the event. -</api> - -<api name="removeListener"> -@function - *experimental* Unregisters an event `listener` for the specified preference. - -@param prefName {String} - The name of the preference to watch for changes. -@param listener {Function} - The listener function that processes the event. -</api> - diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-storage.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-storage.md deleted file mode 100644 index bbe9cbe..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/simple-storage.md +++ /dev/null @@ -1,220 +0,0 @@ -<!-- 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/. --> - -The `simple-storage` module lets you easily and persistently store data across -Firefox restarts. If you're familiar with [DOM storage][] on the Web, it's -kind of like that, but for add-ons. - -[DOM storage]: https://developer.mozilla.org/en/DOM/Storage - -The simple storage module exports an object called `storage` that is persistent -and private to your add-on. It's a normal JavaScript object, and you can treat -it as you would any other. - -To store a value, just assign it to a property on `storage`: - - var ss = require("simple-storage"); - ss.storage.myArray = [1, 1, 2, 3, 5, 8, 13]; - ss.storage.myBoolean = true; - ss.storage.myNull = null; - ss.storage.myNumber = 3.1337; - ss.storage.myObject = { a: "foo", b: { c: true }, d: null }; - ss.storage.myString = "O frabjous day!"; - -You can store array, boolean, number, object, null, and string values. -If you'd like to store other types of values, you'll first have to convert -them to strings or another one of these types. - -Be careful to set properties on the `storage` object and not the module itself: - - // This is no good! - var ss = require("simple-storage"); - ss.foo = "I will not be saved! :("; - -Simple Storage and "cfx run" ----------------------------- -The simple storage module stores its data in your profile. -Because `cfx run` by default uses a fresh profile each time it runs, -simple storage won't work with add-ons executed using `cfx run` - that -is, stored data will not persist from one run to the next. - -The easiest solution to this problem is to use the -[`--profiledir` option to `cfx run`](dev-guide/cfx-tool.html#profiledir). - -If you use this method, you must end your debugging session by -quitting Firefox normally, not by cancelling the shell command. -If you don't close Firefox normally, then simple storage will -not be notified that the session is finished, and will not write -your data to the backing store. - -Constructing Arrays -------------------- -Be careful to construct array objects conditionally in your code, or you may -zero them each time the construction code runs. For example, this add-on -tries to store the URLs of pages the user visits: - -<pre><code> -var ss = require("simple-storage"); -ss.storage.pages = []; - -require("tabs").on("ready", function(tab) { - ss.storage.pages.push(tab.url); -}); - -var widget = require("widget").Widget({ - id: "log_history", - label: "Log History", - width: 30, - content: "Log", - onClick: function() { - console.log(ss.storage.pages); - } -}); -</code></pre> - -But this isn't going to work, because it empties the array each time the -add-on runs (for example, each time Firefox is started). Line 2 needs -to be made conditional, so the array is only constructed if it does -not already exist: - -<pre><code> -if (!ss.storage.pages) - ss.storage.pages = []; -</code></pre> - -Deleting Data -------------- -You can delete properties using the `delete` operator. Here's an add-on -that adds three widgets to write, read, and delete a value: - -<pre><code> -var widgets = require("widget"); -var ss = require("simple-storage"); - -var widget = widgets.Widget({ - id: "write", - label: "Write", - width: 50, - content: "Write", - onClick: function() { - ss.storage.value = 1; - console.log("Setting value"); - } -}); - -var widget = widgets.Widget({ - id: "read", - label: "Read", - width: 50, - content: "Read", - onClick: function() { - console.log(ss.storage.value); - } -}); - -var widget = widgets.Widget({ - id: "delete", - label: "Delete", - width: 50, - content: "Delete", - onClick: function() { - delete ss.storage.value; - console.log("Deleting value"); - } -}); -</pre></code> - -If you run it, you'll see that after clicking "Read" after clicking -"Delete" gives you the expected output: - -<pre> -info: undefined -</pre> - -Quotas ------- -The simple storage available to your add-on is limited. Currently this limit is -about five megabytes (5,242,880 bytes). You can choose to be notified when you -go over quota, and you should respond by reducing the amount of data in storage. -If the user quits the application while you are over quota, all data stored -since the last time you were under quota will not be persisted. You should not -let that happen. - -To listen for quota notifications, register a listener for the `"OverQuota"` -event. It will be called when your storage goes over quota. - - function myOnOverQuotaListener() { - console.log("Uh oh."); - } - ss.on("OverQuota", myOnOverQuotaListener); - -Listeners can also be removed: - - ss.removeListener("OverQuota", myOnOverQuotaListener); - -To find out how much of your quota you're using, check the module's `quotaUsage` -property. It indicates the percentage of quota your storage occupies. If -you're within your quota, it's a number from 0 to 1, inclusive, and if you're -over, it's a number greater than 1. - -Therefore, when you're notified that you're over quota, respond by removing -storage until your `quotaUsage` is less than or equal to 1. Which particular -data you remove is up to you. For example: - - ss.storage.myList = [ /* some long array */ ]; - ss.on("OverQuota", function () { - while (ss.quotaUsage > 1) - ss.storage.myList.pop(); - }); - - -Private Browsing ----------------- -If your storage is related to your users' Web history, personal information, or -other sensitive data, your add-on should respect [private browsing mode][SUMO]. -While private browsing mode is active, you should not store any sensitive data. - -Because any kind of data can be placed into simple storage, support for private -browsing is not built into the module. Instead, use the -[`private-browsing`](packages/addon-kit/private-browsing.html) module to -check private browsing status and respond accordingly. - -For example, the URLs your users visit should not be stored during private -browsing. If your add-on records the URL of the selected tab, here's how you -might handle that: - - ss.storage.history = []; - var privateBrowsing = require("private-browsing"); - if (!privateBrowsing.isActive) { - var url = getSelectedTabURL(); - ss.storage.history.push(url); - } - -For more information on supporting private browsing, see its [Mozilla Developer -Network documentation][MDN]. While that page does not apply specifically to -SDK-based add-ons (and its code samples don't apply at all), you should follow -its guidance on best practices and policies. - -[SUMO]: http://support.mozilla.com/en-US/kb/Private+Browsing -[MDN]: https://developer.mozilla.org/En/Supporting_private_browsing_mode - - -<api name="storage"> -@property {object} - A persistent object private to your add-on. Properties with array, boolean, - number, object, null, and string values will be persisted. -</api> - -<api name="quotaUsage"> -@property {number} - A number in the range [0, Infinity) that indicates the percentage of quota - occupied by storage. A value in the range [0, 1] indicates that the storage - is within quota. A value greater than 1 indicates that the storage exceeds - quota. -</api> - -<api name="OverQuota"> -@event -The module emits this event when your add-on's storage goes over its quota. -</api> 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 deleted file mode 100644 index f1e44df..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/tabs.md +++ /dev/null @@ -1,385 +0,0 @@ -<!-- 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> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/timers.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/timers.md deleted file mode 100644 index 192663a..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/timers.md +++ /dev/null @@ -1,52 +0,0 @@ -<!-- 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 Drew Willcoxon [adw@mozilla.com] --> -<!-- contributed by Atul Varma [atul@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> -<!-- contributed by Irakli Gozalishvil [gozala@mozilla.com] --> - -The `timers` module provides access to web-like timing functionality. - -<api name="setTimeout"> -@function - Schedules `callback` to be called in `ms` milliseconds. Any additional - arguments are passed straight through to the callback. -@returns {integer} - An ID that can later be used to undo this scheduling, if `callback` hasn't yet - been called. -@param callback {function} - Function to be called. -@param ms {integer} - Interval in milliseconds after which the function will be called. -</api> - -<api name="clearTimeout"> -@function - Given an ID returned from `setTimeout()`, prevents the callback with the ID - from being called (if it hasn't yet been called). -@param ID {integer} - An ID returned from `setTimeout()`. -</api> - -<api name="setInterval"> -@function - Schedules `callback` to be called repeatedly every `ms` milliseconds. Any - additional arguments are passed straight through to the callback. -@returns {integer} - An ID that can later be used to unschedule the callback. -@param callback {function} - Function to be called. -@param ms {integer} - Interval in milliseconds at which the function will be called. -</api> - -<api name="clearInterval"> -@function - Given an ID returned from `setInterval()`, prevents the callback with the ID - from being called again. -@param ID {integer} - An ID returned from `setInterval()`. -</api> - diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/widget.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/widget.md deleted file mode 100644 index 815a085..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/widget.md +++ /dev/null @@ -1,909 +0,0 @@ -<!-- 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] --> -<!-- contributed by Drew Willcoxon [adw@mozilla.com] --> -<!-- edited by Noelle Murata [fiveinchpixie@gmail.com] --> - -The `widget` module provides your add-on with a simple user interface that is -consistent with other add-ons and blends in well with Firefox. - -"Widgets" are small pieces of content that live in the Firefox 4 -[add-on bar](https://developer.mozilla.org/en/The_add-on_bar). -They can be simple icons or complex web pages. You can attach -[panels](packages/addon-kit/panel.html) to them that open when they're -clicked, or you can define a custom click handler to perform some other action, -like opening a web page in a tab. - -There are a few advantages to using widgets over an ad hoc user interface. -First, your users will be accustomed to interacting with add-ons via widgets and -the add-on bar. Second, it allows Firefox to treat your interface as a -first-class citizen. For example, in the future Firefox may allow the user to -drag widgets from the add-on bar to other toolbars. By exposing your interface -as a widget, your add-on would automatically inherit such functionality. - -## Creation and Content ## - -Widgets can contain images or arbitrary web content. You can include this -content inline as a string by using the `content` property, or point to content -using a URL with the `contentURL` property. - -Upon creation, the widget is automatically added to the add-on bar. -You can set the width of a widget, but the height is fixed so as to fit in the -add-on bar. If the content is an image, it is automatically scaled to be 16x16 -pixels. - -For example, this widget contains an image, so it looks like a simple icon: - - require("widget").Widget({ - id: "mozilla-icon", - label: "My Mozilla Widget", - contentURL: "http://www.mozilla.org/favicon.ico" - }); - -<img class="image-center" src="static-files/media/screenshots/widget-mozilla-icon.png" -alt="Widget displaying an icon"> - -You can make `contentURL` point to an HTML or icon file which you have -packaged inside your add-on. Just save the file in your add-on's `data` -directory, and reference it using the `data.url()` method of the -[`self`](packages/addon-kit/self.html) module: - - var data = require("self").data; - - require("widget").Widget({ - id: "my-widget", - label: "My Widget", - contentURL: data.url("my-content.html") - }); - -This widget contains an entire web page: - - require("widget").Widget({ - id: "hello-display", - label: "My Hello Widget", - content: "Hello!", - width: 50 - }); - -<img class="image-center" src="static-files/media/screenshots/widget-hello-text.png" -alt="Widget displaying 'hello'"> - -Widgets are quite small by default, so this example used the `width` property to -grow it in order to show all the text. - -## Scripting Widget Content ## - -To interact with the widget's content you need to load a separate script into -the panel. In the SDK these scripts are called "content scripts" because -they're explicitly used for interacting with web content. - -While content scripts can access the content they're attached to, they can't -use the SDK's APIs. So implementing a complete solution usually means you -have to send messages between the content script and the main add-on code. - -* You can specify one or more content scripts to load into the widget using the -`contentScript` or `contentScriptFile` options to the -[`Widget()` constructor](packages/addon-kit/widget.html#Widget(options)). - -* You can communicate with the script using either the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or (preferably, usually) the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. - -<div class="warning"> -<p>Unless your content script is extremely simple and consists only of a -static string, don't use <code>contentScript</code>: if you do, you may -have problems getting your add-on approved on AMO.</p> -<p>Instead, keep the script in a separate file and load it using -<code>contentScriptFile</code>. This makes your code easier to maintain, -secure, debug and review.</p> -</div> - -<!-- The icons this widget displays, shown in the screenshot, is taken from the -Glossy Buttons icon set created by IconEden which is made freely available for -commercial and non-commercial use. -See: http://www.iconeden.com/icon/category/free --> - -<img class="image-right" src="static-files/media/screenshots/widget-player-buttons.png" -alt="Media player UI implemented as a widget"> - -For example, suppose we want to implement a media player as an add-on. -We could implement the main user interface as a widget hosting an array -of buttons to control play/pause/stop functions. - -We can then use a content script to listen for clicks on those buttons. -But because content scripts can't use the SDK's APIs, we'll want the -content script to send messages to the main add-on code, which can then -implement the media player functions using the SDK. - -The widget's content is specified using HTML like this: - -<pre class="brush: html"> -<html> - <body> - <img src="play.png" id="play-button"> - <img src="pause.png" id="pause-button"> - <img src="stop.png" id="stop-button"> - </body> -</html> -</pre> - -We just include three icons, and assign an ID to each one. This HTML file, -and the icon files it references, are saved in the add-on's `data` -directory. - -Next, we write a content script that listens for click events on each icon -and sends the corresponding message to the main add-on code: - - var play_button = document.getElementById("play-button"); - play_button.onclick = function() { - self.port.emit("play"); - } - - var pause_button = document.getElementById("pause-button"); - pause_button.onclick = function() { - self.port.emit("pause"); - } - - var stop_button = document.getElementById("stop-button"); - stop_button.onclick = function() { - self.port.emit("stop"); - } - -We save this file in the add-on's `data` directory as "button-script.js". -Finally. in the add-on's "main.js" file, we create the widget, assign it -the HTML file and the content script, and listen for events from the content -script: - - const widgets = require("widget"); - const data = require("self").data; - - var player = widgets.Widget({ - id: "player", - width: 72, - label: "Player", - contentURL: data.url("buttons.html"), - contentScriptFile: data.url("button-script.js") - }); - - player.port.on("play", function() { - console.log("playing"); - }); - - player.port.on("pause", function() { - console.log("pausing"); - }); - - player.port.on("stop", function() { - console.log("stopping"); - }); - -To learn much more about content scripts, see the -[Working with Content Scripts](dev-guide/guides/content-scripts/index.html) -guide. - -<div class="experimental"> -<h3>Scripting Trusted Widget Content</h3> - -**Note that the feature described in this section is experimental: we'll -very probably continue to support it, but the name of the `addon` -property might change in a future release.** - -We've already seen that you can package HTML files in your add-on's `data` -directory and use them to define the widget's content. We can call this -"trusted" content, because unlike content loaded from a source outside the -add-on, the add-on author knows exactly what it's doing. To -interact with trusted content you don't need to use content scripts: -you can just include a script from the HTML file in the normal way, using -`script` tags. - -Like a content script, these scripts can communicate with the add-on code -using the -[`postMessage()`](dev-guide/guides/content-scripts/using-postmessage.html) -API or the -[`port`](dev-guide/guides/content-scripts/using-port.html) API. -The crucial difference is that these scripts access the `postMessage` -and `port` objects through the `addon` object, whereas content scripts -access them through the `self` object. - -To show the difference, convert the `player` add-on above -to use normal page scripts instead of content scripts. - -First, in the content script, change `self` to `addon`, and wrap it in a -function: - - function init() { - var play_button = document.getElementById("play-button"); - play_button.onclick = function() { - addon.port.emit("play"); - } - - var pause_button = document.getElementById("pause-button"); - pause_button.onclick = function() { - addon.port.emit("pause"); - } - - var stop_button = document.getElementById("stop-button"); - stop_button.onclick = function() { - addon.port.emit("stop"); - } - } - -Next, add a `script` tag to reference "button-script.js", and -call its `init()` function on load: - -<pre class="brush: html"> -<html> - <head> - <script src="button-script.js"></script> - </head> - <body onLoad="init()"> - <img src="play.png" id="play-button"> - <img src="pause.png" id="pause-button"> - <img src="stop.png" id="stop-button"> - </body> -</html> -</pre> - -Finally, remove the line attaching the content script from "main.js": - - const widgets = require("widget"); - const data = require("self").data; - - var player = widgets.Widget({ - id: "player", - width: 72, - label: "Player", - contentURL: data.url("buttons.html") - }); - - player.port.emit("init"); - - player.port.on("play", function() { - console.log("playing"); - }); - - player.port.on("pause", function() { - console.log("pausing"); - }); - - player.port.on("stop", function() { - console.log("stopping"); - }); -</div> - -## Attaching Panels to Widgets ## - -You can supply a [panel](packages/addon-kit/panel.html) to the widget's -constructor: if you do this, the panel is automatically displayed when the -user clicks the widget. - -<!-- The icon the widget displays, shown in the screenshot, is taken from the -Circular icon set, http://prothemedesign.com/circular-icons/ which is made -available under the Creative Commons Attribution 2.5 Generic License: -http://creativecommons.org/licenses/by/2.5/ --> - -<img class="image-right" src="static-files/media/screenshots/widget-panel-clock.png" -alt="Panel attached to a widget"> - - data = require("self").data - - var clockPanel = require("panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") - }); - - require("widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png"), - panel: clockPanel - }); - -Note that this is, at the moment, the only way you can attach a panel to a widget. - -You must supply the panel in the widget's constructor for it to work. If you -assign the panel to the widget after construction, the panel can still be shown -but will not be anchored to the widget: - - data = require("self").data - - var clockPanel = require("panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") - }); - - widget = require("widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png") - }); - - widget.panel = clockPanel; - - // Will not be anchored - widget.panel.show(); - -Also, if you try to call `panel.show()` inside your widget's `click` event -listener, the panel will not be anchored: - - data = require("self").data - - var clockPanel = require("panel").Panel({ - width:215, - height:160, - contentURL: data.url("clock.html") - }); - - require("widget").Widget({ - id: "open-clock-btn", - label: "Clock", - contentURL: data.url("History.png"), - panel: clockPanel, - onClick: function() { - // Will not be anchored - this.panel.show(); - } - }); - -See [bug 638142](https://bugzilla.mozilla.org/show_bug.cgi?id=638142). - -## Examples ## - -For conciseness, these examples create their content scripts as strings and use -the `contentScript` property. In your own add-ons, you will probably want to -create your content scripts in separate files and pass their URLs using the -`contentScriptFile` property. See -[Working with Content Scripts](dev-guide/guides/content-scripts/index.html) for more -information. - - var widgets = require("widget"); - - // A basic click-able image widget. - widgets.Widget({ - id: "google-link", - label: "Widget with an image and a click handler", - contentURL: "http://www.google.com/favicon.ico", - onClick: function() { - require("tabs").activeTab.url = "http://www.google.com/"; - } - }); -<br> - - // A widget that changes display on mouseover. - widgets.Widget({ - id: "mouseover-effect", - label: "Widget with changing image on mouseover", - contentURL: "http://www.yahoo.com/favicon.ico", - onMouseover: function() { - this.contentURL = "http://www.bing.com/favicon.ico"; - }, - onMouseout: function() { - this.contentURL = "http://www.yahoo.com/favicon.ico"; - } - }); -<br> - - // A widget that updates content on a timer. - widgets.Widget({ - id: "auto-update-widget", - label: "Widget that updates content on a timer", - content: "0", - contentScript: 'setTimeout(function() {' + - ' document.body.innerHTML++;' + - '}, 2000)', - contentScriptWhen: "ready" - }); -<br> - - // A widget that loads a random Flickr photo every 5 minutes. - widgets.Widget({ - id: "random-flickr", - label: "Random Flickr Photo Widget", - contentURL: "http://www.flickr.com/explore/", - contentScriptWhen: "ready", - contentScript: 'postMessage(document.querySelector(".pc_img").src);' + - 'setTimeout(function() {' + - ' document.location = "http://www.flickr.com/explore/";' + - '}, 5 * 60 * 1000);', - onMessage: function(imgSrc) { - this.contentURL = imgSrc; - }, - onClick: function() { - require("tabs").activeTab.url = this.contentURL; - } - }); -<br> - - // A widget created with a specified width, that grows. - let myWidget = widgets.Widget({ - id: "widget-effect", - label: "Wide widget that grows wider on a timer", - content: "I'm getting longer.", - width: 50, - }); - require("timers").setInterval(function() { - myWidget.width += 10; - }, 1000); -<br> - - // A widget communicating bi-directionally with a content script. - let widget = widgets.Widget({ - id: "message-test", - label: "Bi-directional communication!", - content: "<foo>bar</foo>", - contentScriptWhen: "ready", - contentScript: 'on("message", function(message) {' + - ' alert("Got message: " + message);' + - '});' + - 'postMessage("ready");', - onMessage: function(message) { - if (message == "ready") - widget.postMessage("me too"); - } - }); - -<api-name="Widget"> -@class -Represents a widget object. - -<api name="Widget"> -@constructor {options} - Creates a new widget. The widget is immediately added to the add-on bar. - -@param options {object} - An object with the following keys: - - @prop label {string} - A required string description of the widget used for accessibility, - title bars, and error reporting. - - @prop id {string} - Mandatory string used to identify your widget in order to save its - location when the user moves it in the browser. - This string has to be unique and must not be changed over time. - - @prop [content] {string} - An optional string value containing the displayed content of the widget. - It may contain HTML. Widgets must have either the `content` property or the - `contentURL` property set. - - If the content is an image, it is automatically scaled to be 16x16 pixels. - - @prop [contentURL] {string} - An optional string URL to content to load into the widget. This can be - [local content](dev-guide/guides/content-scripts/index.html) or remote - content, an image or web content. Widgets must have either the `content` - property or the `contentURL` property set. - - If the content is an image, it is automatically scaled to be 16x16 pixels. - - @prop [panel] {Panel} - An optional [panel](packages/addon-kit/panel.html) to open when the - user clicks on the widget. Note: If you also register a "click" listener, - it will be called instead of the panel being opened. However, you can show - the panel from the listener by calling `this.panel.show()`. - - @prop [width] {integer} - Optional width in pixels of the widget. If not given, a default width is - used. - - @prop [onClick] {function} - Include this to listen to the widget's `click` event. - - @prop [onMessage] {function} - Include this to listen to the widget's `message` event. - - @prop [onMouseover] {function} - Include this to listen to the widget's `mouseover` event. - - @prop [onMouseout] {function} - Include this to listen to the widget's `mouseout` event. - - @prop [onAttach] {function} - Include this to listen to the widget's `attach` event. - - @prop [tooltip] {string} - Optional text to show when the user's mouse hovers over the widget. If not - given, the `label` is used. - - @prop [allow] {object} - An optional object describing permissions for the content. It should - contain a single key named `script` whose value is a boolean that indicates - whether or not to execute script in the content. `script` defaults to true. - - @prop [contentScriptFile] {string,array} - A local file URL or an array of local file URLs of content scripts to load. - Content scripts specified by this property are loaded *before* those - specified by the `contentScript` property. - - @prop [contentScript] {string,array} - A string or an array of strings containing the texts of content scripts to - load. Content scripts specified by this property are loaded *after* those - specified by the `contentScriptFile` property. - - @prop [contentScriptWhen="end"] {string} - When to load the content scripts. This may take one of the following - values: - - * "start": load content scripts immediately after the document - element for the widget is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the widget has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - - This property is optional and defaults to "end". - -</api> - -<api name="destroy"> -@method - Removes the widget from the add-on bar. -</api> - -<api name="postMessage"> -@method - Sends a message to the widget's content scripts. -@param data {value} - The message to send. - The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="on"> -@method - Registers an event listener with the widget. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. -</api> - -<api name="removeListener"> -@method - Unregisters an event listener from the widget. -@param type {string} - The type of event for which `listener` was registered. -@param listener {function} - The listener function that was registered. -</api> - -<api name="getView"> -@method - Retrieve a `WidgetView` instance of this widget relative to a browser window. -@param window {BrowserWindow} - The [BrowserWindow](packages/addon-kit/windows.html) instance to match. -@returns {WidgetView} - A `WidgetView` instance associated with the browser window. Any changes - subsequently applied to this object will only be applied to the widget - attached to that window. -</api> - -<api name="label"> -@property {string} - The widget's label. Read-only. -</api> - -<api name="content"> -@property {string} - A string containing the widget's content. It can contain HTML. Setting it - updates the widget's appearance immediately. However, if the widget was - created using `contentURL`, then this property is meaningless, and setting it - has no effect. -</api> - -<api name="contentURL"> -@property {string} - The URL of content to load into the widget. This can point to - local content loaded from your add-on's "data" directory or remote - content, an image or web content. Setting it updates the widget's appearance - immediately. However, if the widget was created using `content`, then this - property is meaningless, and setting it has no effect. -</api> - -<api name="panel"> -@property {Panel} - A [panel](packages/addon-kit/panel.html) to open when the user clicks on - the widget. -</api> - -<api name="width"> -@property {number} - The widget's width in pixels. Setting it updates the widget's appearance - immediately. -</api> - -<api name="tooltip"> -@property {string} - The text of the tooltip that appears when the user hovers over the widget. -</api> - -<api name="allow"> -@property {object} - A object describing permissions for the content. It contains a single key - named `script` whose value is a boolean that indicates whether or not to - execute script in the content. -</api> - -<api name="contentScriptFile"> -@property {string,array} - A local file URL or an array of local file URLs of content scripts to load. -</api> - -<api name="contentScript"> -@property {string,array} - A string or an array of strings containing the texts of content scripts to - load. -</api> - -<api name="contentScriptWhen"> -@property {string} - When to load the content scripts. This may have one of the following - values: - - * "start": load content scripts immediately after the document - element for the widget is inserted into the DOM, but before the DOM content - itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the widget has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - -</api> - -<api name="port"> -@property {EventEmitter} -[EventEmitter](packages/api-utils/events.html) object that allows you to: - -* send events to the content script using the `port.emit` function -* receive events from the content script using the `port.on` function - -See the guide to -<a href="dev-guide/guides/content-scripts/using-port.html"> -communicating using <code>port</code></a> for details. -</api> - -<api name="attach"> -@event -This event is emitted when a new `WidgetView` object is created using the -`getView()` function. -</api> - -<api name="click"> -@event -This event is emitted when the widget is clicked. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this widget. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the widget's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="mouseover"> -@event -This event is emitted when the user moves the mouse over the widget. -</api> - -<api name="mouseout"> -@event -This event is emitted when the user moves the mouse away from the widget. -</api> - -</api> - - -<api-name="WidgetView"> -@class -Represents a widget instance specific to one browser window. - -Anything you do to an instance of this object will only be applied to the -instance attached to its browser window: widget instances attached to other -browser windows will be unaffected. - -By contrast, any changes you make to an instance of the normal `Widget` class -will be applied across all browser windows. - -This class has all the same methods, attributes and events as the `Widget` -class except for the `getView` method and the `attach` event. - -In this example `WidgetView` is used to display different content for -`http` and `https` schemes: - - // A widget that update its content specifically to each window. - let tabs = require("tabs"); - let windows = require("windows").browserWindows; - let widget = widgets.Widget({ - id: "window-specific-test", - label: "Widget with content specific to each window", - content: " ", - width: 50 - }); - // Observe tab switch or document changes in each existing tab: - function updateWidgetState(tab) { - let view = widget.getView(tab.window); - if (!view) return; - // Update widget displayed text: - view.content = tab.url.match(/^https/) ? "Secured" : "Unsafe"; - } - tabs.on('ready', updateWidgetState); - tabs.on('activate', updateWidgetState); - -<api name="destroy"> -@method - Removes the widget view from the add-on bar. -</api> - -<api name="postMessage"> -@method - Sends a message to the widget view's content scripts. -@param data {value} - The message to send. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="on"> -@method - Registers an event listener with the widget view. -@param type {string} - The type of event to listen for. -@param listener {function} - The listener function that handles the event. -</api> - -<api name="removeListener"> -@method - Unregisters an event listener from the widget view. -@param type {string} - The type of event for which `listener` was registered. -@param listener {function} - The listener function that was registered. -</api> - -<api name="label"> -@property {string} - The widget view's label. Read-only. -</api> - -<api name="content"> -@property {string} - A string containing the widget view's content. It can contain HTML. - Setting it updates the widget view's appearance immediately. However, - if the widget view was created using `contentURL`, then this property - is meaningless, and setting it has no effect. -</api> - -<api name="contentURL"> -@property {string} - The URL of content to load into the widget. This can point to - local content loaded from your add-on's "data" directory or remote - content, an image or web content. Setting it updates the widget's appearance - immediately. However, if the widget was created using `content`, then this - property is meaningless, and setting it has no effect. -</api> - -<api name="panel"> -@property {Panel} - A [panel](packages/addon-kit/panel.html) to open when the user clicks on - the widget view. -</api> - -<api name="width"> -@property {number} - The widget view's width in pixels. Setting it updates the widget view's - appearance immediately. -</api> - -<api name="tooltip"> -@property {string} - The text of the tooltip that appears when the user hovers over the widget - view. -</api> - -<api name="allow"> -@property {object} - A object describing permissions for the content. It contains a single key - named `script` whose value is a boolean that indicates whether or not to - execute script in the content. -</api> - -<api name="contentScriptFile"> -@property {string,array} - A local file URL or an array of local file URLs of content scripts to load. -</api> - -<api name="contentScript"> -@property {string,array} - A string or an array of strings containing the texts of content scripts to - load. -</api> - -<api name="contentScriptWhen"> -@property {string} - When to load the content scripts. This may have one of the following - values: - - * "start": load content scripts immediately after the document - element for the widget view is inserted into the DOM, but before the DOM - content itself has been loaded - * "ready": load content scripts once DOM content has been loaded, - corresponding to the - [DOMContentLoaded](https://developer.mozilla.org/en/Gecko-Specific_DOM_Events) - event - * "end": load content scripts once all the content (DOM, JS, CSS, - images) for the widget view has been loaded, at the time the - [window.onload event](https://developer.mozilla.org/en/DOM/window.onload) - fires - -</api> - -<api name="port"> -@property {EventEmitter} -[EventEmitter](packages/api-utils/events.html) object that allows you to: - -* send events to the content script using the `port.emit` function -* receive events from the content script using the `port.on` - -See the guide to -<a href="dev-guide/guides/content-scripts/using-port.html"> -communicating using <code>port</code></a> for details. -</api> - -<api name="detach"> -@event -The `detach` event is fired when the widget view is removed from its related -window. -This can occur if the window is closed, Firefox exits, or the add-on is -disabled. -</api> - -<api name="click"> -@event -This event is emitted when the widget view is clicked. -</api> - -<api name="message"> -@event -If you listen to this event you can receive message events from content -scripts associated with this widget view. When a content script posts a -message using `self.postMessage()`, the message is delivered to the add-on -code in the widget view's `message` event. - -@argument {value} -Listeners are passed a single argument which is the message posted -from the content script. The message can be any -<a href = "dev-guide/guides/content-scripts/using-port.html#json_serializable">JSON-serializable value</a>. -</api> - -<api name="mouseover"> -@event -This event is emitted when the user moves the mouse over the widget view. -</api> - -<api name="mouseout"> -@event -This event is emitted when the user moves the mouse away from the widget view. -</api> - -</api> diff --git a/tools/addon-sdk-1.7/packages/addon-kit/docs/windows.md b/tools/addon-sdk-1.7/packages/addon-kit/docs/windows.md deleted file mode 100644 index f44817e..0000000 --- a/tools/addon-sdk-1.7/packages/addon-kit/docs/windows.md +++ /dev/null @@ -1,191 +0,0 @@ -<!-- 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 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/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> |