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 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:

    <script src="/bower_components/mouse-killer/dist/mouse-killer.min.js"></script>
   

3. Add mouseKiller as a dependency to your AngularJS app:

    angular.module('myApp', [
        'mouseKiller'
    ])
   

Usage

Complete example:

<button 
    mk-shortcut="ctrl + enter"
    mk-hint="title"
    mk-hint-title="The shortcut for this button is %"
    mk-event="click"
    mk-prevent-default="true"
    mk-stop-propagation="true"
    mk-enabled="auto">Button</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