Keyconfig extension

From MozillaZine Knowledge Base
Jump to navigationJump to search

The Keyconfig extension allows you to configure, customize, or disable keyboard shortcuts. The updated "Dorando keyconfig" add-on works with Firefox through version 56. Go to addons.thunderbird.net for a version that works with Thunderbird and Seamonkey. The old version, and discussion and examples of how to use either version, is available here. It works with Firefox, Thunderbird, and (probably) Mozilla Suite/SeaMonkey. Shortcuts defined via a key can be changed. For more author notes see this.

If you are using an extremely old version of Firefox or Thunderbird, you may need to use an older version of Keyconfig. See this post for more information.

Keyconfig allows for very simple customization of many - though not all - keyboard shortcuts, by simply selecting the action from the list, and typing a new key combination. It also has an advanced feature for creating or editing shortcuts that run snippets of code, which can control many aspects of Firefox, Thunderbird, or other installed add-ons.

A similar add-on, which does not provide the advanced code snippet feature, but does have additional options, is Keybinder. It is not available for Thunderbird.

Keyconfig's user interface

Keyconfig has a user interface for working with keyboard shortcuts. For example, if you have installed the Keyconfig extension, here is how you can compact the current folder in Thunderbird by using the shortcut Alt-C:

  1. In Thunderbird, choose: Tools – Keyconfig... The Keyconfig dialog opens.
  2. At the bottom of the Keyconfig dialog, press the button "Add a new key". The Key editor dialog opens.
  3. Name the key: Compact This Folder (You can use any name—it does not affect the operation of the key.)
  4. Copy and paste the following code sample where you see the comment /*CODE*/:
  5. goDoCommand("cmd_compactFolder")
  6. Press OK to close the Key editor.
  7. Go to the field at the bottom of the Keyconfig dialog, and press the key combination Alt+C. (Do not type the characters A l t + C, but instead hold down the Alt key and press the C key.)
  8. Press the Apply button, then the Close button.
  9. Restart Thunderbird.

Finding code for keys

See the Examples section below for articles that contain many code samples.

When you want to add a key for an action that already exists in the user interface, you can often find the code by using the DOM Inspector extension. For example, if you have installed the DOM Inspector extension in Thunderbird, here is how you can find the code that opens a saved message:

  1. Identify the user-interface element that performs the action. Open the required window if necessary.
  2. In this example, it is the menu item: File – Open saved Message... in Thunderbird's main window.

  3. In the main window, choose Tools – DOM Inspector.
  4. In the DOM Inspector window, choose File – Inspect a Window and choose the window where you identified the user-interface element.
  5. In this example, it is Thunderbird's main window.

  6. In the DOM Inspector window, choose Search – Select Element By Click (or press the button at the left). The button depresses. Now it will act on the first thing in Thunderbird that you click, so you must not click on anything until you find the user-interface element that you identified.
  7. Use your keyboard to return to the window where you identified the user-interface element, and to navigate to that element. Click that user-interface element so that DOM Inspector finds it.
  8. In this example, return to Thunderbird's main window. Press Alt-F to open the File menu. Now that you can see the Open Saved Message... item, click it. (Cancel the file picker that it opens.)

  9. In DOM Inspector's left-hand pane, check that the appropriate element is now selected.
  10. In this example, it is a menuitem element.

  11. In DOM Inspector's right-hand pane, ensure that that DOM Node is selected at the top. Look for the node name: oncommand   The corresponding node value is the code you need for your key.
  12. In this example, the code is: MsgOpenFromFile();

Notes:

  • If the element has no oncommand node, but only a command node, then you might be able to find the code by searching. Note the exact value of the command. It is case sensitive. In DOM Inspector, choose Search – Find Nodes... and specify that command as the ID. If you find a matching command element with an oncommand node, then you can use the code there in your key.
  • If the code that you find contains either this or event.target, replace that with document.getElementById("id") where id is the id of the user-interface element that you identified. For example, if the code in a menu item is:
ToggleInlineAttachment(event.target)
then use this code in your key:
ToggleInlineAttachment(document.getElementById("viewAttachmentsInlineMenuitem"))
  • If the code that you find contains event (not event.target), then it might work unmodified. (Technically, the application expects a mouse event, and you are providing a key event, but the two kinds of event are similar in many ways.)
  • In some cases DOM Inspector cannot show you the code, because it is in a separate file, or the code that you find does not work in a key. Finding the code in these cases is beyond the scope of this article.

Tips

  • You can add preferences for custom keys to the prefs.js file in your profile folder to get the described results. All instances of Firefox, Thunderbird, or Mozilla must be closed before editing this file. After editing start the browser and open the Keyconfig window to set your keyboard shortcut. Attention: Don't add these preferences to your user.js file because they are applied again with the next start and the assigned keyboard shortcuts will be deleted.
  • Here is a template for Keyconfig preferences that you add to your prefs.js file:

user_pref("keyconfig.main.xxx_key__NAME", "!][][][FUNCTION");
  • The Compose window for mail messages is recycled after the first message, so you do not really get a new window for subsequent messages. To get a new Compose window so that keyconfig loads its keys there, close and restart the application.
  • To get a new main window, you do not usually need to close the application. For example, in Firefox you can choose File – New Window, or in Thunderbird you can double-click a folder. When the new window opens, close the old one (where your keyconfig changes are not active).

Examples

External Links