VM.shortcut

Register a shortcut for a function.

This is a helper script for Violentmonkey.

Usage

Importing

1. Use in a userscript:

   // ...
   // @require https://cdn.jsdelivr.net/npm/@violentmonkey/shortcut@1
   // ...
   
   const { register, ... } = VM.shortcut;

2. Use as a module:

   $ yarn add @violentmonkey/shortcut

   import { register, ... } from '@violentmonkey/shortcut';

Registering Shortcuts

1. Register a shortcut:

   const { register } = VM.shortcut;
   
   register('c-i', () => {
     console.log('You just pressed Ctrl-I');
   });
   
   // shortcuts will be enabled by default

2. Enable or disable all shortcuts:

   const { enable, disable } = VM.shortcut;
   
   disable();
   // ...
   enable();

3. Key sequences:

   const { register } = VM.shortcut;
   
   register('c-a c-b', () => {
     console.log('You just pressed Ctrl-A Ctrl-B sequence');
   });

4. Handle keys with custom listeners (e.g. use with text editor like TinyMCE):

   const { handleKey } = VM.shortcut;
   
   function onKeyDown(e) {
     handleKey(e);
   }
   
   addMyKeyDownListener(onKeyDown);

Advanced Usage

The usage above is with the default keyboard service. However you can use the KeyboardService directly to get full control of the class:

import { KeyboardService } from '@violentmonkey/shortcut';

const service = new KeyboardService();
// Or pass options
const service = new KeyboardService({
  sequenceTimeout: 500,
});

service.enable();

service.register('c-i', () => {
  console.log('You just pressed Ctrl-I');
});

// Only register the following key when `inputFocus` is false
service.register('g g', () => {
  console.log('Now inputFocus is false and you pressed `g g`');
}, {
  condition: '!inputFocus',
});

// Handle inputFocus using capture mode
document.addEventListener('focus', (e) => {
  if (isInput(e.target)) service.setContext('inputFocus', true);
}, true);
document.addEventListener('blur', (e) => {
  if (isInput(e.target)) service.setContext('inputFocus', false);
}, true);
   
// Disable the shortcuts and unbind all events whereever you want
service.disable();

// Reenable the shortcuts later
service.enable();

Key Definition

A key sequence is a space-separated list of combined keys. Each combined key is composed of zero or more modifiers and exactly one base key in the end, concatenated with dashes (-). The modifiers are always case-insensitive and can be abbreviated as their first letters.

Here are some valid examples:

ctrl-alt-c
ctrl-a-c
c-a-c

Possible modifiers are:

• c, ctrl, control
• s, shift
• a, alt
• m, meta, cmd
• ctrlcmd

There is one special case, ctrlcmd for ctrl on Windows and cmd for macOS, so if we register ctrlcmd-s to save something, the callback will be called when ctrl-s is pressed on Windows, and when cmd-s is pressed on macOS. This is useful to register cross-platform shortcuts.