Revision 693143 of notifications

<div class="note">
 <p>Stable</p>
</div>
<p><span class="seoSummary">Display transient, <a href="https://en.wikipedia.org/wiki/Toast_%28computing%29">toaster</a>-style desktop messages to the user.</span></p>
<h2 id="Usage">Usage</h2>
<p>This API supports desktop notifications on Windows, OS X using <a href="https://growl.info/">Growl</a> (and Notification Center as of OS X 10.9 Mavericks), and Linux using libnotify.</p>
<p>Here's a typical example. When the message is clicked, a string is logged to the console.</p>
<pre class="brush: js">
var notifications = require("sdk/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.
  }
});</pre>
<p>This one displays an icon that's stored in the add-on's <code>data</code> directory. See the <a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a> module documentation for more information.</p>
<pre class="brush: js">
var notifications = require("sdk/notifications");
var self = require("sdk/self");
var myIconURL = self.data.url("myIcon.png");

notifications.notify({
  text: "I have an icon!",
  iconURL: myIconURL
});</pre>
<p>Note that from FIrefox 34 onwards you can use <code>"./myIcon.png"</code> as a shorter alias for your add-on's data directory. So the above add-on could be rewritten like this:</p>
<pre class="brush: js">
var notifications = require("sdk/notifications");
var myIconURL = "./myIcon.png";

notifications.notify({
  text: "I have an icon!",
  iconURL: myIconURL
});</pre>
<p>This module depends on the underlying system's notification service. If the user's system does not support desktop notifications or if its notifications service is not running:</p>
<ul>
 <li>if Firefox was started normally, notifications are logged to Firefox's error console</li>
 <li>if the user launched Firefox from the command line, notifications are logged to the terminal.</li>
</ul>
<h2 id="Globals">Globals</h2>
<h3 id="Functions">Functions</h3>
<h4 class="addon-sdk-api-name" id="notify(options)"><code>notify(options)</code></h4>
<p>Displays a transient notification to the user.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>options : object</strong><br />
 Optional options:</p>
<table class="standard-table">
 <thead>
  <tr>
   <th scope="col">Name</th>
   <th scope="col">Type</th>
   <th scope="col">&nbsp;</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>title</td>
   <td>string</td>
   <td>
    <p>A string to display as the message's title.</p>
   </td>
  </tr>
  <tr>
   <td>text</td>
   <td>string</td>
   <td>
    <p>A string to display as the body of the message.</p>
   </td>
  </tr>
  <tr>
   <td>iconURL</td>
   <td>string</td>
   <td>
    <p>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 <a href="/en-US/Add-ons/SDK/High-Level_APIs/self"><code>self</code></a> module.</p>
   </td>
  </tr>
  <tr>
   <td>onClick</td>
   <td>function</td>
   <td>
    <p>A function to be called when the user clicks the message. It will be passed the value of <code>data</code>.</p>
   </td>
  </tr>
  <tr>
   <td>data</td>
   <td>string</td>
   <td>
    <p>A string that will be passed to <code>onClick</code>.</p>
   </td>
  </tr>
 </tbody>
</table>
<p>&nbsp;</p>