Skip to content

violentmonkey/vm-shortcut

Repository files navigation

VM.shortcut

NPM License jsDocs.io

Register a shortcut for a function.

This is a helper script for Violentmonkey.

👉 Playground: https://violentmonkey.github.io/vm-shortcut/

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:

    import { register } from '@violentmonkey/shortcut';
    
    register('c-i', () => {
      console.log('You just pressed Ctrl-I');
    });
    
    // shortcuts will be enabled by default
  2. Enable or disable all shortcuts:

    import { enable, disable } from '@violentmonkey/shortcut';
    
    disable();
    // ...
    enable();
  3. Key sequences:

    import { register } from '@violentmonkey/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):

    import { handleKey } from '@violentmonkey/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 `disableThisKey` is false
service.register(
  'g g',
  () => {
    console.log('Now disableThisKey is false and you pressed `g g`');
  },
  {
    condition: '!disableThisKey',
  }
);

// Update `disableThisKey` on different conditions
// Note: these callbacks are just demos, you need to implement them by yourself!!!
onOneCondition(() => {
  service.setContext('disableThisKey', true);
});
onAnotherCondition(() => {
  service.setContext('disableThisKey', false);
});

// Disable the shortcuts and unbind all events whereever you want
service.disable();

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

API

jsDocs.io

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
  • cm, 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.

Condition Syntax

  • conditionA - when conditionA is truthy
  • !conditionB - when conditionB is falsy
  • conditionA && conditionB - when both conditionA and conditionB are truthy

For more complicated cases, it's recommended to handle the logic in a function and store the result as a simple condition to the context.