diff options
author | Thomas Steur <thomas.steur@googlemail.com> | 2014-05-05 04:41:07 +0400 |
---|---|---|
committer | Thomas Steur <thomas.steur@googlemail.com> | 2014-05-05 04:41:07 +0400 |
commit | c324d3859aeb1562eccf14fa9c783b12d085ddbb (patch) | |
tree | 60cbe93d3a6631979eeb5fdd44f92671e26234cc /libs | |
parent | e023f4a2c0715b86405a4c289cea93be9e4eb344 (diff) |
refs #4987 removed duplicated help (already mentioned in regular help icon) and added missing readme
Diffstat (limited to 'libs')
-rw-r--r-- | libs/mousetrap/README.md | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/libs/mousetrap/README.md b/libs/mousetrap/README.md new file mode 100644 index 0000000000..83293f35f7 --- /dev/null +++ b/libs/mousetrap/README.md @@ -0,0 +1,100 @@ +# Mousetrap + +Mousetrap is a simple library for handling keyboard shortcuts in Javascript. + +It is around **1.9kb** minified and gzipped and **3.5kb** minified, has no external dependencies, and has been tested in the following browsers: + +- Internet Explorer 6+ +- Safari +- Firefox +- Chrome + +It has support for ``keypress``, ``keydown``, and ``keyup`` events on specific keys, keyboard combinations, or key sequences. + +If you would like to donate to help support Mousetrap development use [Gittip](https://www.gittip.com/ccampbell). + +## Getting started + +1. Include mousetrap on your page before the closing ``</body>`` tag + + ```html + <script src="/path/to/mousetrap.min.js"></script> + ``` + +2. Add some keyboard events to listen for + + ```html + <script> + // single keys + Mousetrap.bind('4', function() { console.log('4'); }); + Mousetrap.bind("?", function() { console.log('show shortcuts!'); }); + Mousetrap.bind('esc', function() { console.log('escape'); }, 'keyup'); + + // combinations + Mousetrap.bind('command+shift+k', function() { console.log('command shift k'); }); + + // map multiple combinations to the same callback + Mousetrap.bind(['command+k', 'ctrl+k'], function() { + console.log('command k or control k'); + + // return false to prevent default browser behavior + // and stop event from bubbling + return false; + }); + + // gmail style sequences + Mousetrap.bind('g i', function() { console.log('go to inbox'); }); + Mousetrap.bind('* a', function() { console.log('select all'); }); + + // konami code! + Mousetrap.bind('up up down down left right left right b a enter', function() { + console.log('konami code'); + }); + </script> + ``` + +## Why Mousetrap? + +There are a number of other similar libraries out there so what makes this one different? + +- There are no external dependencies, no framework is required +- You are not limited to ``keydown`` events (You can specify ``keypress``, ``keydown``, or ``keyup`` or let Mousetrap choose for you). +- You can bind key events directly to special keys such as ``?`` or ``*`` without having to specify ``shift+/`` or ``shift+8`` which are not consistent across all keyboards +- It works with international keyboard layouts +- You can bind Gmail like key sequences in addition to regular keys and key combinations +- You can programatically trigger key events with the ``trigger()`` method +- It works with the numeric keypad on your keyboard +- The code is well documented/commented + +## Tests + +Unit tests run via <a href="http://visionmedia.github.io/mocha" target="_blank">mocha</a>. + +### Running in browser + +Download the repo and go to `tests/mousetrap.html` in your browser. + +### Running with Grunt and PhantomJS + +1. Install grunt-cli + + ```bash + npm install -g grunt-cli + ``` + +2. Install npm packages + + ```bash + cd /path/to/repo + npm install + ``` + +3. Run tests + + ```bash + grunt mocha + ``` + +## Documentation + +Full documentation can be found at http://craig.is/killing/mice
\ No newline at end of file |