Theia API Documentation v1.77.0
    Preparing search index...

    Module @theia/keymaps


    theia-ext-logo

    ECLIPSE THEIA - KEYMAPS EXTENSION


    The @theia/keymaps allows the user to reconfigure default keybindings with custom keymaps.
    By modifying the appropriate keymaps.json, the user can modify existing keybindings, or add keybindings to commands that do not yet have a keybinding associated to them.

    Example of a valid keymaps.json file

    [
    {
    "command": "quickCommand",
    "keybinding": "ctrl+shift+f4"
    }
    ]

    where command is a unique command id and keybinding is a valid keybinding. There's also an optional context property that can be specified (which is also a unique string for a context id).

    Printable keys use logical-character semantics. For example, ctrl+[ means Ctrl plus the character [, regardless of which physical key produces it on the active keyboard layout. Bare one-code-point characters such as a, 3, /, ^, §, ², and ä can be used directly.

    Latin letters that the active layout does not produce on its base or Shift layer (for example on Cyrillic or Greek layouts) fall back to their US key position, so ctrl+c keeps working while typing in another script. This mirrors VS Code and applies to letters only; digits and punctuation always follow the logical character.

    Use a bracketed scan code such as ctrl+[BracketLeft] when a binding should follow a physical key rather than a character. Scan-code names are validated against supported KeyboardEvent.code values.

    Characters reserved by the keybinding grammar use a Unicode escape. For example, use ctrl+[char:0x2B] for logical +, [char:0x20] for Space as a logical character, and [char:0x5D] for ]. Literal escapes such as [char:§] are supported when the character is not reserved. Each character token must contain exactly one Unicode code point; multi-code-point graphemes are not supported.

    A logical binding that the active layout cannot produce remains visible but inactive. Inactive bindings are shown dimmed and struck through in the Keyboard Shortcuts editor, with a warning icon whose tooltip explains the reason. It becomes active automatically after switching to a layout that can produce the character. A binding is also inactive when authored Shift is a command modifier but its character requires an AltGr layer that consumes Shift, and when a command modifier is combined with a character on the AltGr layer that consumes that modifier: Ctrl or Alt on Windows, where AltGr is reported as Ctrl+Alt (for example German ctrl+[), and Option (alt) on macOS, where Option selects that layer (for example German cmd+alt+[). If a keyboard event is ambiguous (Windows reports AltGraph together with Ctrl+Alt), Theia prefers a binding that matches the authored command modifiers; if none exists, it falls back to the binding for the produced logical character. Existing keybinding strings remain valid. To restore the former positional behavior for all shortcuts, set "keyboard.dispatch": "keyCode"; character-only tokens such as ü or [char:0x...] are inactive in this mode because they have no positional key code.

    To use ctrl on Linux/Windows and cmd on OSX, use ctrlcmd.

    You can use shift, ctrl, alt, meta, option (alt), command (meta), cmd (meta) as modifiers. Note that if you defined a custom shortcut with cmd, command or meta, the same keymaps file won't work on a Windows/Linux machine as this key doesn't have an equivalent.

    You can also use the following strings for special keys: backspace, tab, enter, return, capslock, esc, escape, space, pageup, pagedown, end, home, left, up, right, down, ins and del.

    The keybinding recorder saves printable input as its logical character. For a Latin-letter fallback on a non-Latin layout, it records the Latin letter: Ctrl and the physical V key on a Russian layout record ctrl+v, not ctrl+м, matching VS Code. When Windows reports Ctrl+Alt, with or without AltGraph, the recorder still records the produced logical character, so recorded shortcuts stay typeable on the current layout. Non-printable keys, Space and numpad keys are recorded by name (for example delete, f1, space, add, subtract); numpad digits are recorded like the top-row digits (1…9). Dead-key captures of printable keys use [ScanCode] syntax. On macOS, Option is recorded as the alt command modifier rather than as the character it produces: Option+Shift+P records shift+alt+p, not ∏.

    If unsure you can always look at the framework's supported keys

    Key sequences like: ctrl+x ctrl+a or ctrl+a b c are supported. With the following limitations:

    • If the key sequence exceeds 1 key chord it won't show in the electron menu.
    • If the key sequence exceeds 2 key chords it won't show in the command palette.

    "Theia" is a trademark of the Eclipse Foundation https://www.eclipse.org/theia

    index
    keybinding-schema-updater
    keybindings-widget
    keymaps-frontend-contribution
    keymaps-frontend-module
    keymaps-monaco-contribution
    keymaps-service