Bug 882407 - Uplift addon-sdk to firefox. r=me

Author: KWierso

addon-sdk/source/doc/module-source/sdk/event/target.md

@@ -104,6 +104,14 @@ Exceptions in the listeners can be handled via `'error'` event listeners:
 If there is no listener registered for `error` event or if it also throws
 exception then such exceptions are logged into a console.
 
+## Chaining
+
+Emitters can also have their methods chained:
+
+    target.on('message', handleMessage)
+      .on('data', parseData)
+      .on('error', handleError);
+
 <api name="EventTarget">
 @class
 `EventTarget` is an exemplar for creating an objects that can be used to
@@ -131,6 +139,8 @@ specified `type` are emitted.
    The type of event.
 @param listener {Function}
    The listener function that processes the event.
+@returns {EventTarget}
+   Returns the EventTarget instance
 </api>
 
 <api name="once">
@@ -141,6 +151,8 @@ the next time an event of the specified `type` is emitted.
    The type of event.
 @param listener {Function}
    The listener function that processes the event.
+@returns {EventTarget}
+   Returns the EventTarget instance
 </api>
 
 <api name="removeListener">
@@ -150,6 +162,13 @@ Removes an event `listener` for the given event `type`.
    The type of event.
 @param listener {Function}
    The listener function that processes the event.
+@returns {EventTarget}
+   Returns the EventTarget instance
+</api>
+
+<api name="off">
+@method
+An alias for [removeListener](modules/sdk/event/target.html#removeListener(type, listener)).
 </api>
 
 </api>

addon-sdk/source/doc/module-source/sdk/lang/functional.md

@@ -286,6 +286,31 @@ of having to set a boolean flag and checking it later.
   The wrapped `fn` that can only be executed once.
 </api>
 
+<api name="chain">
+@function
+Creates a version of the input function that will return `this`.
+
+    let { chain } = require("sdk/lang/functional");
+
+    function Person (age) { this.age = age; }
+    Person.prototype.happyBirthday = chain(function () this.age++);
+
+    let person = new Person(30);
+
+    person
+      .happyBirthday()
+      .happyBirthday()
+      .happyBirthday()
+
+    console.log(person.age); // 33
+
+@param fn {function}
+  The function that will be wrapped by the chain function.
+
+@returns {function}
+  The wrapped function that executes `fn` and returns `this`.
+</api>
+
 <api name="cache">
 @function
 An alias for [once](modules/sdk/lang/functional.html#once(fn)).

addon-sdk/source/doc/module-source/sdk/panel.md

@@ -70,6 +70,13 @@ method exported by the
 
     panel.show();
 
+## Panel Positioning ##
+
+By default the panel appears in the center of the currently active browser window.
+You can position the panel by passing a `position` to the panel's
+[constructor](modules/sdk/panel.html#Panel(options)) or to
+its [`show()`](modules/sdk/panel.html#show(options)) method.
+
 ## Updating Panel Content ##
 
 You can update the panel's content simply by setting the panel's `contentURL`
@@ -425,23 +432,23 @@ Creates a panel.
     The position of the panel.
     Ignored if the panel is opened by a widget.
 
-    You can set as value an object that has one or more of the following
-    properites: `top`, `right`, `bottom` and `left`. Their values are expressed
+    This is an object that has one or more of the following
+    properties: `top`, `right`, `bottom` and `left`. Their values are expressed
     in pixels. Any other properties will be ignored.
 
-    The default alignment is centered, so for example panel can be displayed in
-    the center of the bottom corner by leaving off vertical axis:
+    The default alignment along each axis is centered: so to display a panel centred
+    along the vertical or horizontal axis, just omit that axis:
 
-        // Show the panel to the centered horizontally and aligned to the bottom
-        // of the content area
+        // Show the panel centered horizontally and
+        // aligned to the bottom of the content area
         require("sdk/panel").Panel({
           position: {
            bottom: 0
           }
         }).show();
 
-        // Show the panel to the centered vertically and aligned to the left o
-        // the content area
+        // Show the panel centered vertically and
+        // aligned to the left of the content area
         require("sdk/panel").Panel({
           position: {
             left: 0
@@ -451,23 +458,27 @@ Creates a panel.
         // Centered panel, default behavior
         require("sdk/panel").Panel({}).show();
 
-    In the same way of their CSS counterpart, setting both `top` and `bottom`,
-    or `left` and `right`, will results in calculated the `height` and `width`:
+    As with the CSS `top`, `bottom`, `left`, and `right` properties, setting
+    both `top` and `bottom` or both `left` and `right` will implicitly set the
+    panel's `height` or `width` relative to the content window:
 
-        // Show the panel centered horizontally, that is distant 40px
-        // from the top and 100px from the bottom.
+        // Show the panel centered horizontally, with:
+        // - the top edge 40px from the top of the content window
+        // - the bottom edge 100px from the bottom of the content window
         require("sdk/panel").Panel({
           position: {
             top: 40,
             bottom: 100
           }
         }).show();
 
-    Set implicitly `height` in this example, will makes the panel ignore the
-    `bottom` property, as the CSS homonym properties does:
+    If you set both `top` and `bottom`, but also set the panel's height
+    explicitly using the `height` property, then the panel will ignore
+    `bottom`, just as CSS does for its properties with the same name:
 
-        // Show the panel centered horizontally, that is distant 40px from the top
-        // and has 400px as height
+        // Show the panel centered horizontally, with:
+        // - the top edge 40px from the top of the content window
+        // - a height of 400px
         require("sdk/panel").Panel({
           position: {
             top: 40,
@@ -485,7 +496,8 @@ Creates a panel.
           height: 400
         }).show();
 
-    The same principle is applied for `width`, `left` and `right`.
+    The same principle is applied in the horizontal axis with
+    `width`, `left` and `right`.
 
   @prop [focus=true] {boolean}
     Set to `false` to prevent taking the focus away when the panel is shown.
@@ -644,8 +656,10 @@ Displays the panel.
 
 If the `options` argument is given, it will be shallow merged with the options
 provided in the constructor: the `options` passed in the `show` method takes
-the precedence.
-It's useful for temporary changes, without touching the default values.
+precedence.
+
+Passing options here is useful for making temporary changes without touching
+the default values.
 
 @param options {object}
   Showing options for the panel, with the following keys:

addon-sdk/source/examples/annotator/lib/main.js

@@ -2,12 +2,12 @@
  * 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/. */
 
-var widgets = require('widget');
-var pageMod = require('page-mod');
-var data = require('self').data;
-var panels = require('panel');
-var simpleStorage = require('simple-storage');
-var notifications = require("notifications");
+var widgets = require('sdk/widget');
+var pageMod = require('sdk/page-mod');
+var data = require('sdk/self').data;
+var panels = require('sdk/panel');
+var simpleStorage = require('sdk/simple-storage');
+var notifications = require("sdk/notifications");
 
 /*
 Global variables
@@ -188,7 +188,7 @@ in the browser.
       this.postMessage(simpleStorage.storage.annotations);
     },
     onMessage: function(message) {
-      require('tabs').open(message);
+      require('sdk/tabs').open(message);
     }
   });
 

addon-sdk/source/examples/library-detector/lib/main.js

@@ -2,11 +2,11 @@
  * 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/. */
 
-const tabs = require('tabs');
-const widgets = require('widget');
-const data = require('self').data;
-const pageMod = require('page-mod');
-const panel = require('panel');
+const tabs = require('sdk/tabs');
+const widgets = require('sdk/widget');
+const data = require('sdk/self').data;
+const pageMod = require('sdk/page-mod');
+const panel = require('sdk/panel');
 
 const ICON_WIDTH = 16;
 

addon-sdk/source/examples/reading-data/lib/main.js

@@ -2,9 +2,9 @@
  * 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/. */
 
-var self = require("self");
-var panels = require("addon-kit/panel");
-var widgets = require("addon-kit/widget");
+var self = require("sdk/self");
+var panels = require("sdk/panel");
+var widgets = require("sdk/widget");
 
 function replaceMom(html) {
   return html.replace("World", "Mom");

addon-sdk/source/examples/reading-data/tests/test-main.js

@@ -3,7 +3,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 var m = require("main");
-var self = require("self");
+var self = require("sdk/self");
 
 exports.testReplace = function(test) {
   var input = "Hello World";

addon-sdk/source/examples/reddit-panel/lib/main.js

@@ -2,9 +2,9 @@
  * 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/. */
 
-var data = require("self").data;
+var data = require("sdk/self").data;
 
-var reddit_panel = require("panel").Panel({
+var reddit_panel = require("sdk/panel").Panel({
   width: 240,
   height: 320,
   contentURL: "http://www.reddit.com/.mobile?keep_extension=True",
@@ -13,10 +13,10 @@ var reddit_panel = require("panel").Panel({
 });
 
 reddit_panel.port.on("click", function(url) {
-  require("tabs").open(url);
+  require("sdk/tabs").open(url);
 });
 
-require("widget").Widget({
+require("sdk/widget").Widget({
   id: "open-reddit-btn",
   label: "Reddit",
   contentURL: "http://www.reddit.com/static/favicon.ico",

addon-sdk/source/examples/reddit-panel/tests/test-main.js

@@ -3,7 +3,7 @@
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 var m = require("main");
-var self = require("self");
+var self = require("sdk/self");
 
 exports.testMain = function(test) {
   var callbacks = { quit: function() {

addon-sdk/source/lib/sdk/deprecated/window-utils.js

@@ -205,17 +205,17 @@ Object.defineProperties(exports, {
  */
 exports.getInnerId = deprecateFunction(getInnerId,
   'require("window-utils").getInnerId is deprecated, ' +
-  'please use require("window/utils").getInnerId instead'
+  'please use require("sdk/window/utils").getInnerId instead'
 );
 
 exports.getOuterId = deprecateFunction(getOuterId,
   'require("window-utils").getOuterId is deprecated, ' +
-  'please use require("window/utils").getOuterId instead'
+  'please use require("sdk/window/utils").getOuterId instead'
 );
 
 exports.isBrowser = deprecateFunction(isBrowser,
   'require("window-utils").isBrowser is deprecated, ' +
-  'please use require("window/utils").isBrowser instead'
+  'please use require("sdk/window/utils").isBrowser instead'
 );
 
 exports.hiddenWindow = appShellService.hiddenDOMWindow;