#labels Featured,Phase-Support,Phase-Implementation,Phase-Design
= About =
jQuery.hotkeys is a plugin that let you easily add and remove handlers for keyboard events anywhere in your code supporting almost any key combination.
It is based on a library [http://www.openjs.com/scripts/events/keyboard_shortcuts/ shortcut.js] written by [http://www.openjs.com/ Binny V A].

The syntax is as follows:
{{{ 
$(expression).bind(<types>,<options>, <handler>);
$(expression).unbind(<types>,<options>, <handler>);

$(document).bind('keydown', 'Ctrl+a', fn);

// e.g. replace '$' sign with '€'
$('input.foo').bind('keyup', '$', function(){
    this.value = this.value.replace('$', '€');
});

$('div.foo').unbind('keydown', 'Ctrl+a', fn);
}}}

==== Types ====
Supported types are `'keydown'`, `'keyup'` and `'keypress'`

==== Options ====
The options are `'combi'` i.e. the key combination, and `'disableInInput'` which allow your code not to be executed when the cursor is located inside an input ( `$(elem).is('input') || $(elem).is('textarea')` ).

As you can see, the key combination can be passed as string or as an object. You may pass an object in case you wish to override the default option for `disableInInput` which is set to `false`:
{{{
$(document).bind('keydown', {combi:'a', disableInInput: true}, fn);
}}}
I.e. when cursor is within an input field, `'a'` will be inserted into the input field without interfering. 

If you want to use more than one modifiers (e.g. alt+ctrl+z) you should define them by an alphabetical order e.g. alt+ctrl+shift

Modifiers are case insensitive, i.e. 'Ctrl+a' == 'ctrl+a'.

==== Handler ====
In previous versions there was an option propagate which is removed now and implemented at the user code level.

When using jQuery, if an event handler returns false, jQuery will call `stopPropagation()` and `preventDefault()`


== [http://jshotkeys.googlepages.com/test-static-01.html Live Demo] ==

== jQuery Compatibility ==
Tested with *jQuery 1.2.6* to *jQuery 1.3.1*

== Browser support ==
||        ||IE 6/7/8||FF 1.5/2/3||Opera-9||Safari-3||Chrome-0.2 ||
||Windows||+||+||+||+||+||
||Mac OS X||x||+||?||+||x||
||GNU/Linux||x||+||+||x||x||

 * + - Works fine.  
 * X - The browser is not available on that platform.  
 * ? - I don't have that browser installed on that platform.

*If you happened to have a browser installed on a platform which I marked as '?', I will appreciate if you kindly run the demo and send over the results.*

== Features added in this version (0.7.x) ==
 * Implemented as $.fn - let you use `this`.
 * jQuery selectors are supported.
 * Extending `$.fn.bind` and `$.fn.unbind` so you get a single interface for binding events to handlers
 
== Overriding jQuery ==
The plugin wraps the following jQuery methods:
 * $.fn.bind
 * $.fn.unbind
 * $.find

Even though the plugin overrides these methods, the original methods will *always* be called.

The plugin will add functionality only for the `keydown`, `keyup` and `keypress` event types. Any other types are passed untouched to the original `'bind()'` and `'unbind()'` methods.

Moreover, if you call `bind()` without passing the shortcut key combination e.g. `$(document).bind('keydown', fn)` only the original `'bind()'` method will be executed.

I also modified the `$.fn.find` method by adding a single line at the top of the function body. here is the code:

* Plugin's Version*
{{{
    jQuery.fn.find = function( selector ) {
        // the line I added
        this.query=selector;
        // call jQuery original find
        return jQuery.fn.__find__.apply(this, arguments);
    };
}}}
You can read about this at [http://groups.google.com/group/jquery-en/browse_thread/thread/18f9825e8d22f18d jQuery's User Group]

===Overrides Browser Native Shortcuts (f5, Ctrl-l, etc)===

Firefox is the most liberal one in the manner of letting you capture all short-cuts even those that are built-in in the browser such as `Ctrl-t` for new tab, or `Ctrl-a` for selecting all text. You can always bubble them up to the browser by returning `true` in your handler.

Others, (IE) either let you handle built-in short-cuts, but will add their functionality after your code has executed. Or (Opera/Safari) will *not* pass those events to the DOM at all.

*So, if you bind `Ctrl-Q` or `Alt-F4` and your Safari/Opera window is closed don't be surprised.*

The following example omit the quick-search feature in firefox when typing '/'
{{{
jQuery(document).bind('keydown', '/', function (evt){
    alert("Hello Slash"); 
    evt.stopPropagation( );  
    evt.preventDefault( );
    return false;
});
}}}

*Note that I am calling `preventDefault()` and `stopPropagation()` inside the handler*
For some reason just returning false does not work.
===Current Version is: beta 0.7===