hotkeys

  • Revision slug: Mozilla/Add-ons/SDK/High-Level_APIs/hotkeys
  • Revision title: hotkeys
  • Revision id: 505515
  • Created:
  • Creator: wbamberg
  • Is current revision? No
  • Comment

Revision Content

Stable

The hotkeys module enables add-on developers to define hotkey combinations.

Usage

To define a hotkey combination, create a Hotkey 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:

// 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();
  }
});

Choosing Hotkeys

Choose hotkey combinations with care. It's very easy to choose combinations which clash with hotkeys defined for Firefox or for other add-ons.

If you choose any of the following commonly used Firefox combinations your add-on will not pass AMO review:

accel+Z, accel+C, accel+X, accel+V or accel+Q

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, accel-S is typically used to save a file, but if you use it for something completely different then it would be extremely confusing for users.

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.

Globals

Constructors

Hotkey(options)

Creates a hotkey whose onPress listener method is invoked when key combination defined by hotkey is pressed.

If more than one hotkey is created for the same key combination, the listener is executed only on the last one created.

Parameters

options : Object
Required options:

Name Type  
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.
onPress Function

Function that is invoked when the key combination hotkey is pressed.

Hotkey

Methods

destroy()

Stops this instance of Hotkey from reacting on the key combinations. Once destroyed it can no longer be used.

Revision Source

<div class="note">
 <p>Stable</p>
</div>
<p><span class="seoSummary">The <code>hotkeys</code> module enables add-on developers to define hotkey combinations.</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>
<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>
Revert to this revision