keyHandler.js

/**
 * Swap keys and values of a plain object.
 * Used to build reverse lookup maps (value → key).
 * @param {object} map - The object to invert
 * @returns {object} A new object with keys and values swapped
 */
function invertMap (map) {
  return Object.fromEntries(Object.entries(map).map(([k, v]) => [v, k]));
}

/**
 *** Extending your module to work with MMM-KeyBindings *****
 *
 *  Use the code below in your module to accept key press
 *  events generated by the MMM-KeyBindings module.
 *
 *  These is a basic implementation, expand as needed.
 *
 */
class KeyHandler {
  /**
   * init()
   * Is called when the module is instantiated.
   * @param {string} name - Module name
   * @param {object} config - Module configuration
   */
  init (name, config) {
    this.name = name;
    this.config = {
      ...this.defaults,
      ...config
    };
    // Give each instance its own key map so handlers never share state.
    this.config.map = {...this.config.map};

    this.currentMode = "DEFAULT";
    // Build reverse lookup: MMM-KeyBindings key name → local name
    this.reverseMap = invertMap(this.config.map);
  }

  /**
   * validate
   *
   *   Add function below to your moduleName.js
   *   Add `if (this.validate(notification, payload)) { return; }`
   *    to the first line of module's 'notificationReceived' function.
   *
   *   If your module does not already override the function, use the snippet below
   *      notificationReceived: function(notification, payload, sender) {
   *          if (this.validate(notification, payload)) { return; }
   *      },
   *
   * @param {string} notification - Notification name
   * @param {object} payload - Notification payload
   * @returns {boolean} - Whether the notification was handled
   */
  validate (notification, payload) {
    // Handle KEYPRESS mode change events from the MMM-KeyBindings Module
    if (notification === "KEYPRESS_MODE_CHANGED") {
      this.currentMode = payload;
      return true;
    }

    // Uncomment line below for diagnostics & to confirm keypresses are being received
    if (notification === "KEYPRESS" && this.debug) {
      Log.debug("[KeyHandler]", payload);
    }

    // Validate Keypresses
    if (notification === "KEYPRESS" && this.currentMode === this.config.mode) {
      if (this.config.multiInstance && payload.sender !== payload.instance) {
        return false; // Wrong Instance
      }
      if (!(payload.keyName in this.reverseMap)) {
        return false; // Not a key we listen for
      }
      this.validKeyPress(payload);
      return true;
    }

    // Test for focus key pressed and need to take focus:
    if (notification === "KEYPRESS" && "takeFocus" in this.config) {
      if (this.currentMode === this.config.mode) {
        return false; // Already have focus.
      }
      if (this.config.multiInstance && payload.sender !== payload.instance) {
        return false; // Wrong Instance
      }
      if (typeof this.config.takeFocus === "object") {
        if (
          this.config.takeFocus.keyPress !== payload.keyPress ||
          this.config.takeFocus.keyState !== payload.keyState
        ) {
          return false; // Wrong keyName/KeyPress Combo
        }
      } else if (
        typeof this.config.takeFocus === "string" &&
        payload.keyName !== this.config.takeFocus
      ) {
        return false; // Wrong Key;
      }

      this.focusReceived();
      return true;
    }

    return false;
  }

  /**
   * focusReceived
   *
   *   Function is called when a valid take focus key press
   *      has been received and is ready for action
   *
   */
  focusReceived () {
    Log.info(`${this.name} HAS FOCUS!`);
    this.sendNotification("KEYPRESS_MODE_CHANGED", this.config.mode);
    this.currentMode = this.config.mode;
    this.onFocus();
  }

  /**
   * releaseFocus
   *
   *   Call this function when ready to release focus
   *
   *   Modify this function to do what you need in your module
   *      whenever you're ready to give up focus.
   *
   */
  releaseFocus () {
    Log.info(`${this.name} HAS RELEASED FOCUS!`);
    this.sendNotification("KEYPRESS_MODE_CHANGED", "DEFAULT");
    this.currentMode = "DEFAULT";
    this.onFocusReleased();
  }

  /** ************** SUBCLASSABLE FUNCTIONS ****************/
  /** * Pass your functions in the KeyHandler definition ***/

  /**
   * validKeyPress
   *
   *   Add function below to your moduleName.js
   *   Function is called when a valid key press for your module
   *      has been received and is ready for action
   *   Modify this function to do what you need in your module
   *      whenever a valid key is pressed.
   *
   * @param {object} kp - Key press payload
   */
  validKeyPress (kp) {
    Log.debug("[KeyHandler] Key pressed:", kp.keyName);

    // Example for responding to "Left" and "Right" arrow
    if (kp.keyName === this.config.map.Right) {
      Log.debug("[KeyHandler] RIGHT KEY WAS PRESSED!");
    } else if (kp.keyName === this.config.map.Left) {
      Log.debug("[KeyHandler] LEFT KEY WAS PRESSED!");
    }
  }

  /**
   * onFocus
   * Subclass this method in your KeyHandler definition to do something
   * when focus has been received.
   *   Modify this function to do what you need in your module
   *      whenever focus is received.
   */
  onFocus () {
    // Override in subclass
    Object.hasOwn(this, "name");
  }

  /**
   * onFocusReleased
   * Subclass this method in your KeyHandler definition to do something
   * when focus has been released.
   *   Modify this function to do what you need in your module
   *      whenever focus is released.
   */
  onFocusReleased () {
    // Override in subclass
    Object.hasOwn(this, "name");
  }

  /**
   * sendNotification
   * Subclassed to provide reference to module's send function.
   */
  sendNotification () {
    // Override in subclass
    Object.hasOwn(this, "name");
  }
}

/**
 * Default key binding configuration shared by all handlers.
 * A registered definition may override any of these; each created handler
 * gets its own `config` in init(), so instances never share state.
 */
KeyHandler.prototype.defaults = {
  // The "mode" this handler responds to.
  mode: "DEFAULT",
  // Map your local key names to MMM-KeyBindings key names.
  map: {
    Right: "ArrowRight",
    Left: "ArrowLeft"
  },
  /*
   * multiInstance: true  -> bluetooth device controls only the local server instance.
   * multiInstance: false -> bluetooth device controls all instances of this module.
   */
  multiInstance: true,
  /*
   * Set "takeFocus" to a key (string) or { keyName, keyState } to grab focus so
   * other modules stop reacting to key presses until releaseFocus() is called.
   */
  takeFocus: "Enter",
  debug: false
};

KeyHandler.definitions = {};
KeyHandler.legacyRegistrationWarned = false;

/**
 * Register a key handler definition.
 * Accepts either a KeyHandler subclass (modern) or a plain-object mixin
 * (legacy). Mixins are normalized into a subclass so their methods live on
 * the prototype and every created handler is an isolated instance.
 * @param {string} name - Handler name
 * @param {Function|object} definition - KeyHandler subclass or mixin object
 */
KeyHandler.register = function register (name, definition) {
  if (typeof definition === "function") {
    // Modern: a KeyHandler subclass / constructor.
    KeyHandler.definitions[name] = definition;
    return;
  }

  if (!KeyHandler.legacyRegistrationWarned && typeof Log !== "undefined" && typeof Log.warn === "function") {
    Log.warn("MMM-KeyBindings: registering KeyHandler definitions as plain objects is deprecated. Please migrate to a KeyHandler subclass.");
    KeyHandler.legacyRegistrationWarned = true;
  }

  /*
   * Legacy: a plain-object mixin. Build a prototype (once) that inherits from
   * KeyHandler and carries the definition's methods, so every created handler
   * is a fresh, isolated instance without cloning.
   */
  KeyHandler.definitions[name] = Object.assign(
    Object.create(KeyHandler.prototype),
    definition
  );
};

/**
 * Create a new key handler instance.
 * @param {string} name - Handler name
 * @param {object} config - Handler configuration
 * @returns {KeyHandler|undefined} New instance, or undefined if unregistered
 */
KeyHandler.create = function create (name, config) {
  const definition = KeyHandler.definitions[name];
  if (!definition) {
    return undefined;
  }

  let handler;
  if (typeof definition === "function") {
    const Handler = definition;
    handler = new Handler();
  } else {
    handler = Object.create(definition);
  }
  handler.init(name, config);
  return handler;
};