Revision 513089 of hotkeys

<div class="note">
 <p>Stable</p>
</div>
<p><span class="seoSummary">Assign hotkey combinations to functions in your add-on.</span></p>
<h2 id="Usage">Usage</h2>
<p>To define a hotkey combination, create a <code>Hotkey</code> object, passing it the combination and a function to be called when the user presses that combination. For example, this add-on defines two hotkey combinations, to show and hide a panel:</p>
<pre class="brush: js">
// Define keyboard shortcuts for showing and hiding a custom panel.
var { Hotkey } = require("sdk/hotkeys");

var showHotKey = Hotkey({
  combo: "accel-shift-o",
  onPress: function() {
    showMyPanel();
  }
});
var hideHotKey = Hotkey({
  combo: "accel-alt-shift-o",
  onPress: function() {
    hideMyPanel();
  }
});</pre>
<h3 id="Choosing_Hotkeys">Choosing Hotkeys</h3>
<p>Choose hotkey combinations with care. It's very easy to choose combinations which clash with hotkeys defined for Firefox or for other add-ons.</p>
<p>If you choose any of the following commonly used Firefox combinations your add-on will not pass AMO review:</p>
<pre>
accel+Z, accel+C, accel+X, accel+V or accel+Q
</pre>
<p>If you choose to use a key combination that's already defined, choose one which makes sense for the operation it will perform. For example, <code>accel-S</code> is typically used to save a file, but if you use it for something completely different then it would be extremely confusing for users.</p>
<p>No matter what you choose, it's likely to annoy some people, and to clash with some other add-on, so consider making the combination you choose user-configurable.</p>
<h2 id="Globals">Globals</h2>
<h3 id="Constructors">Constructors</h3>
<h4 class="addon-sdk-api-name" id="Hotkey(options)"><code>Hotkey(options)</code></h4>
<p>Creates a hotkey whose <code>onPress</code> listener method is invoked when key combination defined by <code>hotkey</code> is pressed.</p>
<p>If more than one <code>hotkey</code> is created for the same key combination, the listener is executed only on the last one created.</p>
<h5 id="Parameters">Parameters</h5>
<p><strong>options : Object</strong><br />
 Required 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>combo</td>
   <td>String</td>
   <td>
    <p>Any function key: <code>"f1, f2, ..., f24"</code> or key combination in the format of <code>'modifier-key'</code>:</p>
    <pre class="brush: js">
"accel-s"
"meta-shift-i"
"control-alt-d"</pre>
    <p>Modifier keynames:</p>
    <ul>
     <li><strong>shift</strong>: The Shift key.</li>
     <li><strong>alt</strong>: The Alt key. On the Macintosh, this is the Option key. On Macintosh this can only be used in conjunction with another modifier, since <code>Alt-Letter</code> combinations are reserved for entering special characters in text.</li>
     <li><strong>meta</strong>: The Meta key. On the Macintosh, this is the Command key.</li>
     <li><strong>control</strong>: The Control key.</li>
     <li><strong>accel</strong>: 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.</li>
    </ul>
   </td>
  </tr>
  <tr>
   <td>onPress</td>
   <td>Function</td>
   <td>
    <p>Function that is invoked when the key combination <code>hotkey</code> is pressed.</p>
   </td>
  </tr>
 </tbody>
</table>
<h2 id="Hotkey">Hotkey</h2>
<p>Module exports <code>Hotkey</code> constructor allowing users to create a <code>hotkey</code> for the host application.</p>
<h3 id="Methods">Methods</h3>
<h4 class="addon-sdk-api-name" id="destroy()"><code>destroy()</code></h4>
<p>Stops this instance of <code>Hotkey</code> from reacting on the key combinations. Once destroyed it can no longer be used.</p>