Permalink
Browse files

add 1.10rc2 docset

  • Loading branch information...
1 parent 5511ccc commit ea922e24b4af3754059f308ddc9b3fb32edb2ed7 @wbamberg wbamberg committed Sep 12, 2012
Showing with 1,662 additions and 290 deletions.
  1. +1 −1 dev-guide-source/cfx-tool.md
  2. +1 −0 dev-guide-source/credits.md
  3. +273 −0 dev-guide-source/tutorials/event-targets.md
  4. +11 −0 dev-guide-source/tutorials/index.md
  5. +2 −0 dev-guide-source/tutorials/mobile.md
  6. +2 −2 dev-guide/cfx-tool.html
  7. +1 −1 dev-guide/console.html
  8. +2 −1 dev-guide/credits.html
  9. +1 −1 dev-guide/glossary.html
  10. +1 −1 dev-guide/guides/commonjs.html
  11. +1 −1 dev-guide/guides/content-scripts/accessing-the-dom.html
  12. +1 −1 dev-guide/guides/content-scripts/communicating-with-other-scripts.html
  13. +1 −1 dev-guide/guides/content-scripts/index.html
  14. +1 −1 dev-guide/guides/content-scripts/loading.html
  15. +1 −1 dev-guide/guides/content-scripts/reddit-example.html
  16. +1 −1 dev-guide/guides/content-scripts/using-port.html
  17. +1 −1 dev-guide/guides/content-scripts/using-postmessage.html
  18. +1 −1 dev-guide/guides/events.html
  19. +1 −1 dev-guide/guides/firefox-compatibility.html
  20. +1 −1 dev-guide/guides/index.html
  21. +1 −1 dev-guide/guides/library-detector.html
  22. +1 −1 dev-guide/guides/module-search.html
  23. +1 −1 dev-guide/guides/program-id.html
  24. +1 −1 dev-guide/guides/sdk-vs-xul.html
  25. +1 −1 dev-guide/guides/two-types-of-scripts.html
  26. +1 −1 dev-guide/guides/xul-migration.html
  27. +1 −1 dev-guide/high-level-apis.html
  28. +1 −1 dev-guide/index.html
  29. +1 −1 dev-guide/low-level-apis.html
  30. +1 −1 dev-guide/package-spec.html
  31. +1 −1 dev-guide/third-party-apis.html
  32. +1 −1 dev-guide/tutorials/add-a-context-menu-item.html
  33. +1 −1 dev-guide/tutorials/adding-menus.html
  34. +1 −1 dev-guide/tutorials/adding-toolbar-button.html
  35. +1 −1 dev-guide/tutorials/annotator/creating.html
  36. +1 −1 dev-guide/tutorials/annotator/displaying.html
  37. +1 −1 dev-guide/tutorials/annotator/index.html
  38. +1 −1 dev-guide/tutorials/annotator/overview.html
  39. +1 −1 dev-guide/tutorials/annotator/storing.html
  40. +1 −1 dev-guide/tutorials/annotator/widget.html
  41. +1 −1 dev-guide/tutorials/chrome.html
  42. +1 −1 dev-guide/tutorials/display-a-popup.html
  43. +579 −0 dev-guide/tutorials/event-targets.html
  44. +1 −1 dev-guide/tutorials/getting-started-with-cfx.html
  45. +12 −1 dev-guide/tutorials/index.html
  46. +1 −1 dev-guide/tutorials/installation.html
  47. +1 −1 dev-guide/tutorials/l10n.html
  48. +1 −1 dev-guide/tutorials/list-open-tabs.html
  49. +1 −1 dev-guide/tutorials/listen-for-page-load.html
  50. +1 −1 dev-guide/tutorials/load-and-unload.html
  51. +1 −1 dev-guide/tutorials/logging.html
  52. +3 −1 dev-guide/tutorials/mobile.html
  53. +1 −1 dev-guide/tutorials/modifying-web-pages-tab.html
  54. +1 −1 dev-guide/tutorials/modifying-web-pages-url.html
  55. +1 −1 dev-guide/tutorials/open-a-web-page.html
  56. +1 −1 dev-guide/tutorials/reusable-modules.html
  57. +1 −1 dev-guide/tutorials/troubleshooting.html
  58. +1 −1 dev-guide/tutorials/unit-testing.html
  59. +1 −1 index.html
  60. +1 −1 packages/addon-kit/addon-page.html
  61. +1 −1 packages/addon-kit/clipboard.html
  62. +6 −1 packages/addon-kit/context-menu.html
  63. +1 −1 packages/addon-kit/hotkeys.html
  64. +1 −1 packages/addon-kit/index.html
  65. +1 −1 packages/addon-kit/l10n.html
  66. +1 −1 packages/addon-kit/notifications.html
  67. +1 −1 packages/addon-kit/page-mod.html
  68. +1 −1 packages/addon-kit/page-worker.html
  69. +1 −1 packages/addon-kit/panel.html
  70. +1 −1 packages/addon-kit/passwords.html
  71. +1 −1 packages/addon-kit/private-browsing.html
  72. +1 −1 packages/addon-kit/request.html
  73. +1 −1 packages/addon-kit/selection.html
  74. +1 −1 packages/addon-kit/self.html
  75. +1 −1 packages/addon-kit/simple-prefs.html
  76. +1 −1 packages/addon-kit/simple-storage.html
  77. +24 −7 packages/addon-kit/tabs.html
  78. +1 −1 packages/addon-kit/timers.html
  79. +1 −1 packages/addon-kit/widget.html
  80. +6 −1 packages/addon-kit/windows.html
  81. +1 −1 packages/api-utils/api-utils.html
  82. +1 −1 packages/api-utils/app-strings.html
  83. +1 −1 packages/api-utils/base64.html
  84. +1 −1 packages/api-utils/byte-streams.html
  85. +1 −1 packages/api-utils/collection.html
  86. +1 −1 packages/api-utils/content.html
  87. +1 −1 packages/api-utils/content/loader.html
  88. +1 −1 packages/api-utils/content/proxy.html
  89. +1 −1 packages/api-utils/content/symbiont.html
  90. +1 −1 packages/api-utils/content/worker.html
  91. +1 −1 packages/api-utils/cortex.html
  92. +1 −1 packages/api-utils/cuddlefish.html
  93. +1 −1 packages/api-utils/environment.html
  94. +1 −1 packages/api-utils/errors.html
  95. +1 −1 packages/api-utils/event/core.html
  96. +1 −1 packages/api-utils/event/target.html
  97. +1 −1 packages/api-utils/events.html
  98. +1 −1 packages/api-utils/file.html
  99. +1 −1 packages/api-utils/frame/utils.html
  100. +1 −1 packages/api-utils/globals.html
  101. +1 −1 packages/api-utils/heritage.html
  102. +1 −1 packages/api-utils/hidden-frame.html
  103. +5 −3 packages/api-utils/httpd.html
  104. +1 −1 packages/api-utils/index.html
  105. +1 −1 packages/api-utils/light-traits.html
  106. +1 −1 packages/api-utils/list.html
  107. +1 −1 packages/api-utils/loader.html
  108. +1 −1 packages/api-utils/match-pattern.html
  109. +1 −1 packages/api-utils/memory.html
  110. +1 −1 packages/api-utils/message-manager.html
  111. +1 −1 packages/api-utils/namespace.html
  112. +1 −1 packages/api-utils/observer-service.html
  113. +1 −1 packages/api-utils/plain-text-console.html
  114. +1 −1 packages/api-utils/preferences-service.html
  115. +1 −1 packages/api-utils/promise.html
  116. +1 −1 packages/api-utils/querystring.html
  117. +1 −1 packages/api-utils/runtime.html
  118. +1 −1 packages/api-utils/sandbox.html
  119. +1 −1 packages/api-utils/tab-browser.html
  120. +1 −1 packages/api-utils/test/assert.html
  121. +1 −1 packages/api-utils/text-streams.html
  122. +1 −1 packages/api-utils/traceback.html
  123. +1 −1 packages/api-utils/traits.html
  124. +1 −1 packages/api-utils/unload.html
  125. +1 −1 packages/api-utils/url.html
  126. +1 −1 packages/api-utils/uuid.html
  127. +1 −1 packages/api-utils/window-utils.html
  128. +1 −1 packages/api-utils/window/utils.html
  129. +1 −1 packages/api-utils/xhr.html
  130. +604 −150 packages/api-utils/xpcom.html
  131. +11 −2 packages/api-utils/xul-app.html
  132. +1 −1 packages/index.json
  133. +1 −1 packages/test-harness/harness.html
  134. +1 −1 packages/test-harness/index.html
  135. +1 −1 packages/test-harness/run-tests.html
  136. +1 −1 status.md5
@@ -816,7 +816,7 @@ will create a profile there for you. So you just have to make up
a path and name the first time, and keep using it:
<pre>
-cfx run --profile-dir="~/addon-dev/profiles/boogaloo"
+cfx run --profiledir="~/addon-dev/profiles/boogaloo"
</pre>
The path must contain at least one "/" (although you may specify
@@ -19,6 +19,7 @@ We'd like to thank our many Jetpack project contributors! They include:
* [Shane Caraveo](https://github.com/mixedpuppy)
* [Matěj Cepl](https://github.com/mcepl)
* Hernán Rodriguez Colmeiro
+* [David Creswick](https://github.com/dcrewi)
* dexter
* [Matteo Ferretti (ZER0)](https://github.com/ZER0)
* fuzzykiller
@@ -0,0 +1,273 @@
+<!-- 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/. -->
+
+# Creating Event Targets #
+
+<span class="aside">This tutorial describes the use of low-level APIs.
+These APIs are still in active development, and we expect to make
+incompatible changes to them in future releases.</span>
+
+The [guide to event-driven programming with the SDK](dev-guide/guides/events.html)
+describes how to consume events: that is, how to listen to events generated
+by event targets. For example, you can listen to [`private-browsing`'s `start` event](packages/addon-kit/private-browsing.html#start) or the
+[`Panel` object's `show` event](packages/addon-kit/panel.html#show).
+
+With the SDK, it's also simple to implement your own event targets.
+This is especially useful if you want to
+[build your own modules](dev-guide/tutorials/reusable-modules.html),
+either to organize your add-on better or to enable other developers to
+reuse your code. If you use the SDK's event framework for your
+event targets, users of your module can listen for events using the SDK's
+standard event API.
+
+In this tutorial we'll create part of a module to access the browser's
+[Places API](https://developer.mozilla.org/en/Places). It will emit events
+when the user adds and visits bookmarks, enabling users of the module
+to listen for these events using the SDK's standard event API.
+
+## Using the Places API ##
+
+First, let's write some code using Places API that logs the URIs of
+bookmarks the user adds.
+
+Create a new directory called "bookmarks", navigate to it, and run `cfx init`.
+Then open "lib/main.js" and add the following code:
+
+ var {Cc, Ci, Cu} = require("chrome");
+ Cu.import("resource://gre/modules/XPCOMUtils.jsm", this);
+ var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+ .getService(Ci.nsINavBookmarksService);
+
+ var bookmarkObserver = {
+ onItemAdded: function(aItemId, aFolder, aIndex) {
+ console.log("added ", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ onItemVisited: function(aItemId, aVisitID, time) {
+ console.log("visited ", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ QueryInterface: XPCOMUtils.generateQI([Components.interfaces.nsINavBookmarkObserver])
+ };
+
+ exports.main = function() {
+ bookmarkService.addObserver(bookmarkObserver, false);
+ };
+
+ exports.onUnload = function() {
+ bookmarkService.removeObserver(bookmarkObserver);
+ }
+
+Try running this add-on, adding and visiting bookmarks, and observing
+the output in the console.
+
+## Modules as Event Targets ##
+
+We can adapt this code into a separate module that exposes the SDK's
+standard event interface.
+
+To do this we'll use the [`event/core`](packages/api-utils/event/core.html)
+module.
+
+Create a new file in "lib" called "bookmarks.js", and add the following code:
+
+ var { emit, on, once, off } = require("api-utils/event/core");
+
+ var {Cc, Ci, Cu} = require("chrome");
+ Cu.import("resource://gre/modules/XPCOMUtils.jsm", this);
+ var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+ .getService(Ci.nsINavBookmarksService);
+
+ var bookmarkObserver = {
+ onItemAdded: function(aItemId, aFolder, aIndex) {
+ emit(exports, "added", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ onItemVisited: function(aItemId, aVisitID, time) {
+ emit(exports, "visited", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ QueryInterface: XPCOMUtils.generateQI([Components.interfaces.nsINavBookmarkObserver])
+ };
+
+ bookmarkService.addObserver(bookmarkObserver, false);
+
+ exports.on = on.bind(null, exports);
+ exports.once = once.bind(null, exports);
+ exports.removeListener = function removeListener(type, listener) {
+ off(exports, type, listener);
+ };
+
+This code implements a module which can emit `added` and `visited` events.
+It duplicates the previous code, but with a few changes:
+
+* import `emit()`, `on()`, `once()`, and `off()` from `event/core`
+* replace listener functions with calls to `emit()`, passing the appropriate
+event type
+* export its own event API. This consists of three functions:
+ * `on()`: start listening for events or a given type
+ * `once()`: listen for the next occurrence of a given event, and then stop
+ * `removeListener()`: stop listening for events of a given type
+
+The `on()` and `once()` exports delegate to the corresponding function from
+`event/core`, and use `bind()` to pass the `exports` object itself as
+the `target` argument to the underlying function. The `removeListener()`
+function is implemented by calling the underlying `off()` function.
+
+We can use this module in the same way we use any other module that emits
+module-level events, such as
+[`private-browsing`](packages/addon-kit/private-browsing.html). For example,
+we can adapt "main.js" as follows:
+
+ var bookmarks = require("./bookmarks");
+
+ function logAdded(uri) {
+ console.log("added: " + uri);
+ }
+
+ function logVisited(uri) {
+ console.log("visited: " + uri);
+ }
+
+ exports.main = function() {
+ bookmarks.on("added", logAdded);
+ bookmarks.on("visited", logVisited);
+ };
+
+ exports.onUnload = function() {
+ bookmarks.removeListener("added", logAdded);
+ bookmarks.removeListener("visited", logVisited);
+ }
+
+## Classes as Event Targets ##
+
+Sometimes we want to emit events at the level of individual objects,
+rather than at the level of the module.
+
+To do this, we can inherit from the SDK's
+[`EventTarget`](packages/api-utils/event/target.html) class. `EventTarget`
+provides an implementation of the functions needed to add and remove
+event listeners: `on()`, `once()`, and `removeListener()`.
+
+In this example, we could define a class `BookmarkManager` that inherits
+from `EventTarget` and emits `added` and `visited` events.
+
+Open "bookmarks.js" and replace its contents with this code:
+
+ var { emit } = require("api-utils/event/core");
+ var { EventTarget } = require("api-utils/event/target");
+ var { Class } = require("api-utils/heritage");
+ var { merge } = require("api-utils/utils/object");
+
+ var {Cc, Ci, Cu} = require("chrome");
+ Cu.import("resource://gre/modules/XPCOMUtils.jsm", this);
+ var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"]
+ .getService(Ci.nsINavBookmarksService);
+
+ function createObserver(target) {
+ var bookmarkObserver = {
+ onItemAdded: function(aItemId, aFolder, aIndex) {
+ emit(target, "added", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ onItemVisited: function(aItemId, aVisitID, time) {
+ emit(target, "visited", bookmarkService.getBookmarkURI(aItemId).spec);
+ },
+ QueryInterface: XPCOMUtils.generateQI([Components.interfaces.nsINavBookmarkObserver])
+ };
+ bookmarkService.addObserver(bookmarkObserver, false);
+ }
+
+ var BookmarkManager = Class({
+ extends: EventTarget,
+ initialize: function initialize(options) {
+ EventTarget.prototype.initialize.call(this, options);
+ merge(this, options);
+ createObserver(this);
+ }
+ });
+
+ exports.BookmarkManager = BookmarkManager;
+
+The code to interact with the Places API is the same here. However:
+
+* we're now importing from four modules:
+ * [`event/core`](packages/api-utils/event/core.html) gives us
+`emit()`: note that we don't need `on`, `once`, or `off`,
+since we will use `EventTarget` for adding and removing listeners
+ * [`event/target`](packages/api-utils/event/target.html) gives us
+`EventTarget`, which implements the interface for adding and removing
+listeners
+ * [`heritage`](packages/api-utils/heritage.html) gives us
+`Class()`, which we can use to inherit from `EventTarget`
+ * `utils/object` gives us `merge()`, which just simplifies setting up the
+`BookmarkManager`'s properties
+* we use `Class` to inherit from `EventTarget`. In its `initialize()` function,
+we:
+ * call the base class initializer
+ * use `merge()` to copy any supplied options into the newly created object
+ * call `createObserver()`, passing in the newly created object as the
+event target
+* `createObserver()` is the same as in the previous example, except that in
+`emit()` we pass the newly created `BookmarkManager` as the event target
+
+To use this event target we can create it and call the `on()`, `once()`, and
+`removeListener()` functions that it has inherited:
+
+ var bookmarks = require("./bookmarks");
+ var bookmarkManager = bookmarks.BookmarkManager({});
+
+ function logAdded(uri) {
+ console.log("added: " + uri);
+ }
+
+ function logVisited(uri) {
+ console.log("visited: " + uri);
+ }
+
+ exports.main = function() {
+ bookmarkManager.on("added", logAdded);
+ bookmarkManager.on("visited", logVisited);
+ };
+
+ exports.onUnload = function() {
+ bookmarkManager.removeListener("added", logAdded);
+ bookmarkManager.removeListener("visited", logVisited);
+ }
+
+### Implementing "onEvent" Options ###
+
+Finally, most event targets accept options of the form "onEvent", where
+"Event" is the capitalized form of the event type. For example, you
+can listen to the
+[`Panel` object's `show` event](packages/addon-kit/panel.html#show)
+either by calling:
+
+ myPanel.on("show", listenerFunction);
+
+or by passing the `onShow` option to `Panel`'s constructor:
+
+ var myPanel = require("panel").Panel({
+ onShow: listenerFunction,
+ contentURL: "https://en.wikipedia.org/w/index.php"
+ });
+
+If your class inherits from `EventTarget`, options like this are automatically
+handled for you. For example, given the implementation of `BookmarkManager`
+above, your "main.js" could be rewritten like this:
+
+ var bookmarks = require("./bookmarks");
+
+ function logAdded(uri) {
+ console.log("added: " + uri);
+ }
+
+ function logVisited(uri) {
+ console.log("visited: " + uri);
+ }
+
+ var bookmarkManager = bookmarks.BookmarkManager({
+ onAdded: logAdded,
+ onVisited: logVisited
+ });
+
+ exports.onUnload = function() {
+ bookmarkManager.removeListener("added", logAdded);
+ bookmarkManager.removeListener("visited", logVisited);
+ }
@@ -207,6 +207,17 @@ on the left for the full list of APIs.
</tr>
+ <tr>
+ <td>
+ <h4><a href="dev-guide/tutorials/event-targets.html">Writing Event Targets</a></h4>
+ Enable the objects you define to emit their own events.
+ </td>
+
+ <td>
+ </td>
+
+ </tr>
+
</table>
<hr>
@@ -30,6 +30,8 @@ Right now only the following modules are fully functional:
* [page-mod](packages/addon-kit/page-mod.html)
* [page-worker](packages/addon-kit/page-worker.html)
+* [passwords](packages/addon-kit/passwords.html)
+* [private-browsing](packages/addon-kit/private-browsing.html)
* [request](packages/addon-kit/request.html)
* [self](packages/addon-kit/self.html)
* [simple-storage](packages/addon-kit/simple-storage.html)
View
@@ -50,7 +50,7 @@
<h1>
<a href="../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
@@ -805,7 +805,7 @@
will create a profile there for you. So you just have to make up
a path and name the first time, and keep using it:</p>
<pre>
-cfx run --profile-dir="~/addon-dev/profiles/boogaloo"
+cfx run --profiledir="~/addon-dev/profiles/boogaloo"
</pre>
<p>The path must contain at least one "/" (although you may specify
View
@@ -50,7 +50,7 @@
<h1>
<a href="../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
View
@@ -50,7 +50,7 @@
<h1>
<a href="../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
@@ -80,6 +80,7 @@
<li><a href="https://github.com/mixedpuppy">Shane Caraveo</a></li>
<li><a href="https://github.com/mcepl">Matěj Cepl</a></li>
<li>Hernán Rodriguez Colmeiro</li>
+<li><a href="https://github.com/dcrewi">David Creswick</a></li>
<li>dexter</li>
<li><a href="https://github.com/ZER0">Matteo Ferretti (ZER0)</a></li>
<li>fuzzykiller</li>
View
@@ -50,7 +50,7 @@
<h1>
<a href="../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
@@ -50,7 +50,7 @@
<h1>
<a href="../../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
@@ -50,7 +50,7 @@
<h1>
<a href="../../../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
@@ -50,7 +50,7 @@
<h1>
<a href="../../../dev-guide/index.html">Add-on SDK<span></span></a>
</h1>
- <div id="version">Version 1.9</div>
+ <div id="version">Version 1.10</div>
</div>
</div>
Oops, something went wrong.

0 comments on commit ea922e2

Please sign in to comment.