https://github.com/rodrigoroma/mouse-killer
An Angular.JS directive to bind keyboard shortcuts to buttons (or any other DOM element).
https://github.com/rodrigoroma/mouse-killer
angular angularjs keyboard-shortcuts shortcut
Last synced: 6 months ago
JSON representation
An Angular.JS directive to bind keyboard shortcuts to buttons (or any other DOM element).
- Host: GitHub
- URL: https://github.com/rodrigoroma/mouse-killer
- Owner: rodrigoroma
- License: mit
- Created: 2017-03-25T19:21:02.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2017-08-21T12:05:38.000Z (over 8 years ago)
- Last Synced: 2025-08-16T08:42:59.523Z (8 months ago)
- Topics: angular, angularjs, keyboard-shortcuts, shortcut
- Language: JavaScript
- Homepage: https://rodrigoroma.github.io/mouse-killer/
- Size: 39.1 KB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mouse-killer
An Angular.JS directive to bind keyboard shortcuts to buttons (or any other DOM element).
## Should I use this?
If your shortcuts have a strong relationship with DOM elements (like buttons), so probably you want to use this.
The rule of thumb is:
* If you have a relationship of 1:1 between DOM elements and shortcuts, you probably want to use Mouse Killer.
* If not, maybe there's a better option for you.
Or:
* If your shortcuts are binded to buttons and you only want to trigger the shortcut if the button can be clicked (ie. it's not disabled, it's not hidden and it's not overrided by other element), so you really want to use Mouse Killer.
* If not, maybe there's a better option for you.
Or even:
* If you prefer to define the shortcuts directly in you HTML tags, you should consider using Mouse Killer.
* If you prefer to define the shortcuts in your controller, you should consider using another plugin.
Not sure if Mouse Killer is the option that best suit your needs? So take a look at [angular-hotkeys](https://github.com/chieffancypants/angular-hotkeys) which has a different approach.
## Installation
1. Add Mouse Killer to your project.
* Using **Bower**: `bower install mouse-killer --save`
* Using **NPM**: `npm install mouse-killer --save`
* Or directly downloading `dist/mouse-killer.js` file.
2. Include `mouse-killer.js` in your HTML:
3. Add **mouseKiller** as a dependency to your AngularJS app:
angular.module('myApp', [
'mouseKiller'
])
## Usage
Complete example:
Button
| Attribute | Required | Default | Description |
|---------------------|----------|-------------|---------------------------------------------------------------|
| mk-shortcut | Yes | - | The key combination (see below). |
| mk-hint | No | title | `none` doesn't display a hint for the shortcut.
`title` display the shortcut in the *title* attribute of the element.
`inline` appends the shortcut to the inner text of the element. Example: **Button text** becomes **Button text (F8)** |
| mk-hint-title | No | Shortcut: % | If `mk-hint` is set to `title`, this attribute defines how the title will be. The character `%` will be replaced by the shortcut. |
| mk-event | No | click | The event to be triggered on the element when the shortcut is pressed. |
| mk-prevent-default | No | true | Choose if Mouse Killer will try to prevent the browser default action for the shortcut (like open the find tool if `F3` is pressed or open a file if `ctrl+o` is pressed). |
| mk-stop-propagation | No | true | Choose if Mouse Killer will stop the event propagation to prevent others event handlers from firing another action. |
| mk-enabled | No | auto | An expression that returns one of the following values:
`true` the shortcut is enabled.
`false` the shortcut is disabled.
`auto` this string makes the shortcut enabled if the element is clickable EXCEPT if the focus is on an input field AND the shortcut has only one key.
`function(elem, evt, isClickable)` a function that returns true or false. The first parameter is the element where the shortcut is bound to. The second parameter is the kespressed event. The third parameter is a boolean that indicates if the user could manually click the element (i.e. it's not disabled, hidden or overrided). |
### Directive default configuration
You can use the `.config()` of your application to set the directive default parameters (that can be overrided by some attribute).
In the code below you can see all the parameters that can be set.
app.config(['mouseKillerProvider', function(mouseKillerProvider) {
mouseKillerProvider.setHint('title');
mouseKillerProvider.setHintTitle('Be faster using the % shortcut');
mouseKillerProvider.setEvent('focus');
mouseKillerProvider.setPreventDefault(true);
mouseKillerProvider.setStopPropagation(false);
mouseKillerProvider.setEnabled(true);
}]);
### Non-overridable shortcuts
For security reasons, there are some shortcuts that can't be overrided/prevented and it varies by browser. For example, Google Chrome won't let you override the `ctrl+n` shortcut.
### Valid shortcuts
Keys in a key combination should be separated by the `+` character. In your shortcut, you can have:
* Any number of modifier keys
* Zero or one normal key
Examples of valid shortcuts:
* `ctrl+enter`
* `ctrl+alt+k`
* `w`
* `Ctrl` (shortcuts are case-insensitive)
* `CTRL + Shift+ F` (shortcuts are "space-insensitive")
* `ctrl + {32}` (use `{xxx}` to specify a key by its key code)
#### Modifiers
The following strings are considered modifiers keys:
| Modifier keys |
|----------------------|
| `ctrl` |
| `alt` |
| `shift` |
| `meta` (Windows key) |
#### Keys
| Letters | | Numbers | Numpad | Fx | Misc. |
|---------|---|---------|--------|----|-------|
| a | n | 0 | numpad 0 | f1 | backspace |
| b | o | 1 | numpad 1 | f2 | tab |
| c | p | 2 | numpad 2 | f3 | enter |
| d | q | 3 | numpad 3 | f4 | esc |
| e | r | 4 | numpad 4 | f5 | page up |
| f | s | 5 | numpad 5 | f6 | page down |
| g | t | 6 | numpad 6 | f7 | end |
| h | u | 7 | numpad 7 | f8 | home |
| i | v | 8 | numpad 8 | f9 | left arrow |
| j | w | 9 | numpad 9 | f10 | up arrow |
| k | x | | multiply | f11 | right arrow |
| l | y | | add | f12 | down arrow |
| m | z | | subtract | | insert |
| | | | decimal point | | delete |
| | | | divide | | |
## License
MIT