DOCSEARCHbyAlgolia
Submit Docs

tbkeys

repository·main·Indexed 42 days ago

https://github.com/wshanks/tbkeys

A Thunderbird add-on version 2.4.4 that allows users to bind custom key sequences to commands using the Mousetrap library. It supports GMail-like keyboard navigation and advanced automation via simple commands, function calls, MailExtension messages, and arbitrary JavaScript eval commands (available in the full version, but not in tbkeys-lite).

Tokens
1.2K
Snippets
0
Records
6
Agent score
5%

What's inside tbkeys

  1. License information for tbkeys

    main

    tbkeys is licensed under the Mozilla Public License, v. 2.0 (MPL-2.0).

    This license allows you to use, reproduce, modify, and distribute the software. You may create a 'Larger Work' by combining tbkeys with other material under terms of your choice, provided you comply with the MPL-2.0 requirements for the tbkeys portion.

  2. Compare tbkeys and tbkeys-lite

    main

    Choose between the two versions based on your security and functional requirements:

    tbkeys (Full)

    • Features: Supports all command types, including Eval commands (arbitrary JavaScript execution).
    • Security: Requires full, unrestricted access to Thunderbird to inject key listeners. It is not reviewed by the official Thunderbird Add-ons store.
    • Use Case: When you need advanced automation or custom JavaScript logic.

    tbkeys-lite

    • Features: Does not support Eval commands (they will function as unset commands).
    • Security: Available on addons.thunderbird.net and undergoes independent manual review.
    • Use Case: When you want to use standard commands or simple function calls but prefer a more restricted, reviewed extension.

  3. Customize key bindings in tbkeys

    main

    Key bindings are customized in the add-on's preferences pane, accessible via the Thunderbird Add-ons Manager.

    Configuration Rules

    • Format: The "key bindings" entry must be a JSON object mapping Mousetrap-syntax keys to commands.
    • Scope: There are separate configuration fields for the main window and the compose window. Key bindings do not fire in other windows.
    • Text Inputs: Key bindings do not fire in text input fields unless the first key combination includes a modifier other than shift.
    • Validation: The preferences page validates JSON syntax but does not perform sanity checks on the logic of the key bindings.
    • Sequences: You cannot define a sequence (multiple keys in succession) where the first part of the sequence matches a built-in Thunderbird shortcut (e.g., ctrl+j ctrl+k is not supported if ctrl+j is already a shortcut). However, single keys with modifiers can be used to override built-in shortcuts.

  4. Install tbkeys in Thunderbird

    main

    To install the full version of tbkeys, follow these steps:

    1. Download the tbkeys.xpi file from the GitHub releases page.
    2. Open the Add-ons Manager in Thunderbird via Tools -> Add-ons.
    3. Click the gear icon in the upper right and select "Install Add-on From File...".
    4. Select the downloaded tbkeys.xpi file.

    Note: The add-on will self-update from GitHub when new updates are released.

    Alternatively, you can install tbkeys-lite directly from the Thunderbird Add-ons Manager by searching for "tbkeys-lite".

  5. Common eval command examples

    main

    If you are using the full version of tbkeys, you can use arbitrary JavaScript (eval commands) to perform complex tasks. Here are common patterns:

    // Next tab
window.document.getElementById('tabmail-tabs').advanceSelectedTab(1, true)

// Previous tab
window.document.getElementById('tabmail-tabs').advanceSelectedTab(-1, true)

// Close tab
func:CloseTabOrWindow

// Scroll message list down
window.document.getElementById('threadTree').scrollByLines(1)

// Scroll message list up
window.document.getElementById('threadTree').scrollByLines(-1)

// Scroll message body down (Thunderbird v115+)
window.gTabmail.currentAboutMessage.getMessagePaneBrowser().contentWindow.scrollBy(0, 100)

// Scroll message body down (Thunderbird v102)
window.document.getElementById('messagepane').contentDocument.documentElement.getElementsByTagName('body')[0].scrollBy(0, 100)

// Create new folder
window.goDoCommand('cmd_newFolder')

// Subscribe to feed
window.openSubscriptionsDialog(window.GetSelectedMsgFolders()[0])

  6. Command syntax for key bindings

    main

    When defining values in your JSON key bindings object, use the following command prefixes to specify the action:

    PrefixTypeDescription
    cmd:Simple commandExecutes a Thunderbird command via goDoCommand(). Example: cmd:cmd_NewMessage
    func:Simple function callCalls a function defined on the Thunderbird window object without arguments. Example: func:CloseTabOrWindow
    tbkeys:Custom function callCalls a custom function provided by tbkeys. Currently only supports tbkeys:closeMessageAndRefresh (closes non-first tabs and refreshes all accounts).
    memsg:MailExtension messageSends a string message to another extension using browser.runtime.sendMessage(). Format: memsg:<extensionID>:<message>.
    unsetUnset bindingDoes nothing. Useful for unbinding built-in Thunderbird shortcuts to prevent accidental triggers.
    (none)Eval commandAny entry not matching the above prefixes is treated as arbitrary JavaScript code executed via eval(). Note: Eval commands are NOT supported in tbkeys-lite.