KeyCommandsRegion

Summary

Easily respond to keyboard shortcuts

A keyboard shortcut has two parts to it:

1. A mapping between keyboard actions and a command
2. A mapping between a command and a callback handler

// Mapping keys to commands (not handled by this component)

The keyboard -> command mapping is defined in a separate .cson file. A majority of the commands your component would want to listen to you have already been defined by core Mailspring defaults, as well as custom user overrides. See 'keymaps/base.cson' for more information.

You can define additional, custom keyboard -> command mappings in your own package-specific keymap .cson file. The file can be named anything but must exist in a folder called keymaps in the root of your package's directory.

// Mapping commands to callbacks (handled by this component)

When a keystroke sequence matches a binding in a given context, a custom DOM event with a type based on the command is dispatched on the target of the keyboard event.

That custom DOM event (whose type is the command you want to listen to) will propagate up from its original target. That original target may or may not be a descendent of your component.

Frequently components will want to listen to a keyboard command regardless of where it was fired from. For those, use the globalHandlers prop. The DOM event will NOT be passed to globalHandlers callbacks.

Components may also want to listen to keyboard commands that originate within one of their descendents. For those use the localHandlers prop. The DOM event WILL be passed to localHandlers callback because it is sometimes valuable to call stopPropagataion on the custom command event.

Props:

Example:

In my-package/lib/my-component.cjsx:

class MyComponent extends React.Component {
  render() {
    return (
      <KeyCommandsRegion
        globalHandlers={{
          "core:moveDown": this.onMoveDown
          "core:selectItem": this.onSelectItem
        }}
        className="my-component"
      >
        <div>... sweet component ...</div>
      </KeyCommandsRegion>
    );
  }
}

In my-package/keymaps/my-package.cson:

".my-component":
  "cmd-t": "selectItem"
  "cmd-enter": "sendMessage"