attachCustomKeyEventHandler in xterm.js

How to use attachCustomKeyEventHandler in xterm.js to intercept keys for special handling, with source notes and use cases.

Apr 13, 2024 · 2 min read · 346 Words · -Views -Comments · Programming
WebShell Tech Learning
Read with AI

Choose an AI assistant

ChatGPT Open in a new tab with the article link and prompt
Claude Copy the prompt, then open Claude

Open Claude
Trouble reading the article?

If the prompt is missing, copy the full prompt below into your AI assistant. If the AI cannot read the article, paste the visible passage you want to discuss and add your question.

To handle special key behavior in xterm.js, use attachCustomKeyEventHandler. Here’s how it works.

Source Walkthrough

/**
     * Attaches a custom key event handler which is run before keys are
     * processed, giving consumers of xterm.js ultimate control as to what keys
     * should be processed by the terminal and what keys should not.
     * @param customKeyEventHandler The custom KeyboardEvent handler to attach.
     * This is a function that takes a KeyboardEvent, allowing consumers to stop
     * propagation and/or prevent the default action. The function returns
     * whether the event should be processed by xterm.js.
     *
     * @example A custom keymap that overrides the backspace key
     * ```ts
     * const keymap = [
     *   { "key": "Backspace", "shiftKey": false, "mapCode": 8 },
     *   { "key": "Backspace", "shiftKey": true, "mapCode": 127 }
     * ];
     * term.attachCustomKeyEventHandler(ev => {
     *   if (ev.type === 'keydown') {
     *     for (let i in keymap) {
     *       if (keymap[i].key == ev.key && keymap[i].shiftKey == ev.shiftKey) {
     *         socket.send(String.fromCharCode(keymap[i].mapCode));
     *         return false;
     *       }
     *     }
     *   }
     * });
     * ```
     */
attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;

Source location

 protected _keyDown(event: KeyboardEvent): boolean | undefined {
    this._keyDownHandled = false;
    this._keyDownSeen = true;

    if (this._customKeyEventHandler && this._customKeyEventHandler(event) === false) {
      return false;
    }
    ...
 }
 protected _keyUp(ev: KeyboardEvent): void {
    this._keyDownSeen = false;

    if (this._customKeyEventHandler && this._customKeyEventHandler(ev) === false) {
      return;
    }
    ...
  }
   protected _keyPress(ev: KeyboardEvent): boolean {
    let key;

    this._keyPressHandled = false;

    if (this._keyDownHandled) {
      return false;
    }

    if (this._customKeyEventHandler && this._customKeyEventHandler(ev) === false) {
      return false;
    }
   ... 
  }
   

Source location

From the above we can see:

The callback provided to attachCustomKeyEventHandler runs before xterm.js processes keys. It fires on keydown/keyup/keypress. Returning void or true has the same effect; only returning false prevents xterm.js from further processing the key event.

Example

Suppose I want `Ctrl + `` in xterm.js to trigger a special action (e.g., invoke AI). Do this:

term.attachCustomKeyEventHandler((event)=>{
  if (event.type==='keydown'&&'`' === event.key && event.ctrlKey) {
    // dosomething
    return false;
  }
}); 

If you still want xterm.js to process the key after your handler, return void or true.

Done.

Authors
Developer, digital product enthusiast, tinkerer, sharer, open source lover