Great! So how do I use it?

Of course you'll need to include the js file in your HTML, but that's all you need to do to get started. All that's left for you to do is describe all of your key combos.

The simplest way to register a combo is to use 'keypress.combo()'. The first parameter is a string or array of key names that describe the combo. The second parameter is the on_keydown callback, and the third optional parameter is the prevent_default option which defaults to false.

keypress.combo("shift s", function() {
    console.log("You pressed shift and s");
});

// There are also a few other shortcut methods:

// If we want to register a counting combo
keypress.counting_combo("tab space", function(e, count) {
    console.log("You've pressed this " + count + " times.");
});

// If you want to register a sequence combo
keypress.sequence_combo("up up down down left right left right b a enter", function() {
    lives = 30;
}, true);

If you only want to use Keypress for some very simple keyboard shortcuts, that's all you need to know, and you can stop reading.

If you want to use some of the more advanced features of Keypress, you can use 'keypress.register_combo()' and supply an object with any number of options described below. All of the options are listed below with their default settings.

keypress.register_combo({
    "keys"              : null,
    "on_keydown"        : null,
    "on_keyup"          : null,
    "on_release"        : null,
    "this"              : window,
    "prevent_default"   : false,
    "prevent_repeat"    : false,
    "is_ordered"        : false,
    "is_counting"       : false,
    "is_sequence"       : false,
    "is_exclusive"      : false
    "is_solitary"       : false
});

• keys: This option can be either an array of strings, or a single space separated string of key names that describe the keys that make up the combo.
• on_keydown: This is a function that gets called everytime the keydown event for our combo is fired. We pass this two arguments: the keydown event that triggered it, and an integer representing the number of times the combo has been pressed (this will be 0 unless it is a counting combo).
• on_keyup: Same as above but for keyup. This only receives the keyup event and does not receive the second 'count' argument. This will only be called the first time you release one of the component keys of the combo.
• on_release: This is similar to keyup, but will fire once when ALL of the keys of a combo have been released. If you're unsure, you probably want to ignore this and use on_keyup.
• this: By default our callbacks will be called with 'this' set to window, but we can specify the scope with this option.
• prevent_default: While you can either return false in your callback or use event.preventDefault() to prevent the default browser behavior for a combo, this option will prevent the default browser behavior for all keypresses that are part of a combo. What this means is that if you have, for example, a combo "shift s", both 'shift' and 's' will independently preventDefault when pressed.
• prevent_repeat: Normally the on_keydown callback will be called as fast as your browser fires the keydown event, but by setting this option to true, the on_keydown callback will only be called the first time.
• is_ordered: This option allows us to force the order in which the user presses the keys to activate the combo. The combo "shift s" will normally activate even if the user presses 's' first, then presses 'shift' while still holding down 's'. Setting this option to true will force the user to press the keys in the order described in the keys option.
• is_counting: Setting this to true will make the combo a counting combo as described above.
• is_sequence: Setting this to true will make the combo a sequence combo as described above.
• is_exclusive: Normally when pressing a key, any and all combos that match will have their callbacks called. For instance, pressing 'shift' and then 's' would activate the following combos if they existed: "shift", "shift s" and "s". When we set is_exclusive to true, we will not call the callbacks for any combos that are also exclusive and less specific.
• is_solitary: This option will check that ONLY the combo's keys are being pressed when set to true. When set to the default value of false, a combo can be activated even if extraneous keys are pressed.

If you are registering a lot of combos at once, you'll probably want to describe combo objects as described above, store them all in an array, and then register them all at once using 'keypress.register_many()'. That might look something like this:

my_scope = this;
my_combos = [
    {
        "keys"          : "shift s",
        "is_exclusive"  : true,
        "on_keydown"    : function() {
            console.log("You pressed shift and s together.");
        },
        "on_keyup"      : function(e) {
            console.log("And now you've released one of the keys.");
        },
        "this"          : my_scope
    },
    {
        "keys"          : "s"
        "is_exclusive"  : true,
        "on_keyup"      : function(event) {
            event.preventDefault();
            console.log("We've prevented the s key from doing anything!");
        },
        "this"          : my_scope
    }
];
keypress.register_many(my_combos);

You can then also unregister your combos either specifying the keys (beware that this will clear ALL combos that match the keys), or you can unregister by passing in the object you passed in to register_combo (another reason to manually create the combo objects yourself instead of using the 'keypress.combo()' shortcut method). Or you can simply remove all registered combos using 'keypress.reset()'.

// Remove all "shift s" combos we've registered
keypress.unregister_combo("shift s");

// Or only these specific combos
keypress.unregister_many(my_combos);

// Or remove ALL combos that have been registered
keypress.reset();

If we simply want keypress to stop listening (for instance when focusing on a text input field or textarea). We could use keypress.stop_listening() like so:

$('input[type=text]')
    .bind("focus", keypress.stop_listening)
    .bind("blur", keypress.listen);

A few notes on usage

If you want to make a shortcut to override default behavior such as saving, you should use the "meta" key instead of specifically using "ctrl" or "cmd". This "meta" key will become "ctrl" or "cmd" appropriately depending on the user's system.

Non-modifier keys do not ever fire a keyup event when the command key is held down, so we manually force a keyup event immediately after keydown is received. This means that if your combo includes the meta key, it can contain any number of modifier keys, but only one non-modifier key. Modifier keys are: "meta", "alt", "option", "ctrl", "shift", and "cmd".

Some keys have unreliable support and should mostly be avoided. Print, Scroll Lock, Pause/Break, and Insert have unreliable keyup or keydown firing in Windows or OS X, so I suggest avoiding them, although Keypress does still allow them.

The numpad keys should also be used with caution since you can't always count on the user having a numpad, and browser support for the numpad keys is not standardized. The numpad keys have to be specified manually with "num_" preceeding the key name. If you used a "." in your combo, for instance, it would assume a period and not a decimal (which would be "num_decimal").