## Keyboard Event Descriptions
Keyboard event description contains a key name and a modifier keys if they are used. The modifier keys `ctrl`, `alt`, and `shift` are supported. They are added to the keyboard event by sign `+`:

```js
// example:
// ctrl+alt+shift+a -> for key 'a' with ctrl, alt and shift keys pressed
```

Keyboard event description support a shortcut sequenses. These means that you can press a sequence of keys to trigger a shortcut. The sequence elements are separated by sign "," ( coma ):

```js
// example:
// a,b,c -> for key 'a' then key 'b' then key 'c'

// g+shift,o,t,o -> for key 'g' with shift, then key 'o', then key 't' then key 'o'
```

Order of describing keyboard event and modifier keys is not important, but sequence elements are:

```js
// example:
// a+ctrl,l,o,t -> a with ctrl, then l, then o, then t
// this is equal to:
// ctrl+a,l,o,t
// but not equal to:
// ctrl+a,o,t,l
```

Keyboard sequence is detected automatically by time interval between key presses. The default interval is 480ms but you can change it by setting `keyWait` option. Read more in section `Options`.

There is a way to disable automatic sequence detection and mark the begining and the end of the sequense by using a keyboard action functions. Read more in section `Keyboard Action Functions`.

Special characters that are available for your shortcut descriptions:
- 'left' - left arrow key
- 'right' - right arrow key
- 'up' - up arrow key
- 'down' - down arrow key
- 'enter' - enter key
- 'space' - space key
- 'esc' - escape key
- 'tab' - tab key
- 'backspace' - backspace key
- '=' - equal key
- F1 - F12 - function keys
- '/' - slash key
- '\\' - backslash key
- '[' - open square bracket key
- ']' - close square bracket key
- '`' - backtick key

**Warning**: For keys with two symbols, in shortcut description use the lower one. Examples: Use '=' instead of '+', use '/' instead of '?', etc. Modifier keys are available for special characters too.

**Warining**: Some of the shortcuts are used by OS and the browswer, so they are not available.

## Action Functions
Action functions are called when a shortcut is triggered. They is a difference between keyboard and mouse action functions. Arguments are slightly different.

### Keyboard Action Functions
Description of keyboard action functions is:
```js
function myKeyHandler ({
context // (string) Name of the current context;
, note // (string) Name of the note or null if note isn't set;
, dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
, wait // (function). Call it to stop a sequence timer and write shortcut sequence without a timer.
, end // (function). Recover the sequence timer;
, ignore // (function). Call it to ignore the current shortcut from the sequence;
, isWaiting // (boolean). True if the sequence timer is active;
}) {
// Body of the handler. Do something...
}
```

### Mouse Action Functions
Mouse action functions can be described like:

```js
function myMouseHandler ({
context // (string) Name of the current context;
, note // (string) Name of the note or null if note isn't set;
, dependencies // (object) Object with dependencies that you have set by calling `setDependencies` method;
, target // (DOM element). Target element of the mouse event;
, targetProps // (object). Coordinates of the target element (top, left, right, bottom, width, height) or null if target element is not available;
, x // (number). X coordinate of the target element;
, y // (number). Y coordinate of the target element;
, event // (object). Original mouse event object;
}) {
// Body of the handler. Do something...
}
```

## Methods

Description of the methods of shortcut instance:

```js
load : 'Load and extend a shortcut definition.'
, unload : 'Remove a shortcut context with all its shortcuts.'
, changeContext : 'Switch to existing shortcut context.'
, emit : 'Trigger a shortcut or custom event programmatically.'
, pause : 'Stop listening for shortcuts.'
, resume : 'Resume listening for shortcuts.'
, listContexts : 'Return list of available contexts.'
, listShortcuts : 'Return list of shortcuts per context.'
, getContext : 'Return a name of current context or null if there is no context selected'
, getNote : `Return a name of current note or null if note isn't set`
, setNote : 'Set a note to current context.'
, setDependencies : 'Set dependencies that will be available in action functions.'
, getDependencies : 'Return dependencies object.'
```

### How to 'pause' and 'resume'?
When you want to stop execution of shortcuts, call `short.pause()`. It's equal to `short.pause('*')`. Will stop all shortcuts in the active context. Stop for single shortcut is by calling `short.pause('shortcutName')`. To resume shortcuts execution call `short.resume()`. It's equal to `short.resume('*')`. Will resume all shortcuts in the active context. Resume for single shortcut is by calling `short.resume('shortcutName')`.

```js
// pause all shortcuts in the active context
short.pause () // will stop all shortcuts in the active context
short.resume ( 'shift+a' ) // will resume only 'shift+a' shortcut

short.resume ('*') // will resume all shortcuts
```

## Options

By `options` you can customize the behavior of the shortcuts. Here is the list of available options:

```js
mouseWait : 'Timeout for entering multiple mouse events. Default value - 320.'
, keyWait : 'Timeout for entering shortcut sequence in ms. Default value - 480'
, clickTarget : 'Data attribute name to recognize click items in HTML. Default value - click' // data attribute 'click' means attribute ( data-click='someName' )
, listenFor : `List input signal sources. Default value - [ 'mouse', 'keyboard' ]`
, onShortcut : 'False or a callback function that is called when a shortcut is triggered. Default value - false'
, streamKeys : 'False or a callback function that is called when a key is pressed. Default value - false'
```

You can request default list of options with their default values:

```js
shortcuts.getDefaults ()
// Note: This method is availalble on the original shortcuts object, not on the shortcuts instance.

// start a shortcuts with default options
const short = shortcuts ()
const short = shortcuts ( shortcuts.getDefaults () ) // same as above
// The idea behind getDefaults is to see what options are available and what are their default values.
```

### onShortcut option
```js
function onShortcut ({ shortcut, context, note, dependencies }) {
// shortcut - (string) Triggered shortcut name
// context - (string) Name of the current context
// note - (string) Name of the note or null if note isn't set
// dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
}
```

### streamKeys option
```js
function streamKeys ({ key, context, note, dependencies }) {
// key - (string) Pressed key name
// context - (string) Name of the current context
// note - (string) Name of the note or null if note isn't set
// dependencies - (object) Object with dependencies that you have set by calling `setDependencies` method
}
```

## Links

- [History of changes](https://github.com/PeterNaydenov/shortcuts/blob/main/Changelog.md)
- [Migration guide](https://github.com/PeterNaydenov/shortcuts/blob/main/Migration.guide.md)

## Credits
'@peter.naydenov/shortcuts' was created and supported by Peter Naydenov.