keyHandler.js

/* jshint esversion:6 */

/**** 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.
 *
 */
var KeyHandler = Class.extend({
  /*** defaults ***
   *
   *   Default Key Binding Configuration, can be overwriten on init
   *
   */
  defaults: {
    /*** MMM-KeyBindings STANDARD MAPPING ***/
    /* Add the "mode" you would like to respond to */
    mode: "DEFAULT",
    map: {
      /* Add each key you want to respond to in the form:
       *      yourkeyName: "keyName_from_MMM-KeyBindings"
       */
      Right: "ArrowRight",
      Left: "ArrowLeft"
      /* ... */
    },

    /*** OPTIONAL ***/
    /*  When using muliple instances (i.e. the screen connected
     *  to the server & browser windows on other computers):
     *
     *  multiInstance: true -- the bluetooth device will only
     *  control the local server's instance.
     *  The browswer windows are controlled by the local
     *   keyboard (assuming enableMoustrap:true in
     *   MMM-KeyBindings' config)
     *
     *  multiInstance: false -- the bluetooth device will
     *  control all instances of this module.
     *
     */
    multiInstance: true,

    /* If you would like your module to "take focus" when a
     * particular key is pressed change the mode
     * setting to "MYKEYWORD" and add a "takeFocus"
     * mapped to a key. This will keep other modules
     * from responding to key presses when you have focus.
     *
     * Just remember you must release focus when done!
     * Call this.releaseFocus()
     * when you're ready to release the focus.
     *
     * Additional Option:
     * For complex setups you can also set an "external interrupt"
     * in the MMM-KeyBindings config which can set the mode
     * without first sending a keypress to all modules
     *
     * Example below takes the focus when "Enter" is pressed
     *
     */
    takeFocus: "Enter",
    /* OR AS AN OBJECT: */
    // takeFocus: { keyName: "Enter", keyState: "KEY_LONGPRESSED" }
    debug: false
  },

  /* init()
   * Is called when the module is instantiated.
   */
  init: function (name, config) {
    this.name = name;
    this.config = Object.assign({}, this.defaults, config);

    this.currentMode = "DEFAULT";
    if (typeof this.config.multiInstance === undefined) {
      this.config.multiInstance = true;
    }
    this.reverseMap = {};
    for (var eKey in this.config.map) {
      if (this.config.map.hasOwnProperty(eKey)) {
        this.reverseMap[this.config.map[eKey]] = eKey;
      }
    }
  },

  /*** validate ***
   *
   *   Add function below to your moduleName.js
   *   Add `if (this.validate(notification, payload)) { return; }`
   *    to the first line of module's 'notificationRecieved' function.
   *
   *   If your module does not already overridde the function, use the snippet below
   *      notificationReceived: function(notification, payload, sender) {
   *          if (this.validate(notification, payload)) { return; }
   *      },
   *
   */
  validate: function (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 recieved
    if (notification === "KEYPRESS" && this.debug) {
      console.log(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: function () {
    console.log(`${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: function () {
    console.log(`${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.
   *
   */
  validKeyPress: function (kp) {
    console.log(kp.keyName);

    // Example for responding to "Left" and "Right" arrow
    if (kp.keyName === this.config.map.Right) {
      console.log("RIGHT KEY WAS PRESSED!");
    } else if (kp.keyName === this.config.map.Left) {
      console.log("LEFT KEY WAS PRESSED!");
    }
  },
  /*
   * Subclass this method in your KeyHandler definition to do something
   * when focus has been receieved.
   *   Modify this function to do what you need in your module
   *      whenever focus is received.
   */
  onFocus: function (kp) {},
  /*
   * Subclass this method in your KeyHandler definition to do something
   * when focus has been receieved.
   *   Modify this function to do what you need in your module
   *      whenever focus is released.
   */
  onFocusReleased: function (kp) {},

  /*
   *  Subclassed to provide reference to module's send function.
   */
  sendNotification: function (notification, payload) {}
});

KeyHandler.definitions = {};

KeyHandler.create = function (name, config) {
  // Make sure module definition is available.
  if (!KeyHandler.definitions[name]) {
    return;
  }

  var handlerDefinition = KeyHandler.definitions[name];
  var clonedDefinition = cloneObject(handlerDefinition);

  // Note that we clone the definition. Otherwise the objects are shared, which gives problems.
  var KeyHandlerClass = KeyHandler.extend(clonedDefinition);

  return new KeyHandlerClass(name, config);
};

KeyHandler.register = function (name, handlerDefinition) {
  KeyHandler.definitions[name] = handlerDefinition;
};