jquery-shortcuts
v1.3.1
Published
jQuery.Shortcuts lets you easily switch between groups of arbitrary and easy-to-define shortcuts.
Downloads
5
Maintainers
Readme
jQuery.Shortcuts
jQuery.Shortcuts lets you easily switch between sets (groups) of arbitrary and easy-to-define shortcuts. You can even manage parentage of shortcut groups via namespaces.
Dependencies
This jQuery plugin requires John Resig's hotkeys plugin to be loaded.
Examples
Configuration
// configure $.Shortcuts _before_ you create any group
// (these are the default options)
$.Shortcuts({
// name of the global namespace
global: "global",
// delimitter that separates namespaces
delimitter: ".",
// the default event type
defaultEvent: "keydown",
// the target
target: document,
// apply priorities?
priorities: false
});
Add and remove (global) shortcuts
// get the (global) shortcut group
var sc = $.Shortcuts();
// add a handler for ctrl+h
var handler = function(event) {
// some nifty action
};
sc.add("ctrl+h", handler);
// remove the handler
sc.remove("ctrl+h", handler);
Handle shortcut parentage using namespaces
// register a new shortcut group
var myTopSc = $.Shortcuts("top");
// when we disable the global namespace, all sub namespaces are also disabled
// e.g.: $.Shortcuts().disable();
// register another group that belongs to "top"
var mySubSc = $.Shortcuts("top.sub");
console.log(mySubSc.parent() == myTopSc);
// => true
console.log(myTopSc.child("sub") == mySubSc);
// => true
Using priorities
// configure the plugin
$.Shortcuts({ priorities: true });
// register two shortcut groups
var sc1 = $.Shortcuts("one");
var sc2 = $.Shortcuts("two");
// create and apply a handler for the same key event
var handler = function(event) {
// do sth here
};
sc1.add("ctrl+h", handler);
sc2.add("ctrl+h", handler);
// assign a higher priority for sc2 (default is 0)
sc2.priority(10);
//
// no, when ctrl+h is pressed, only sc2 fires
//
API
$.Shortcuts([namespace|options])
If
options
are passed, the global options are extended and the$.Shortcuts
object is returned. If anamespace
is passed, a new shortcuts instance/group with that namespace is created and returned. When no argument is given, the global shortcut group is returned. Parentage is built automatically. A namespace consists of a number of names seperated by a delimitter. Example: namespace"foo.bar"
=> shortcuts"global"
-> shortcuts"foo"
-> shortcuts"bar"
. Note that the global namespace ("global"
in this example) is always prepended.namespace()
Returns the
namespace
.name()
Returns the
name
.parent()
Returns the parent shortcuts, or
null
when invoked on the global shortcut group.children()
Return all child shortcut groups mapped to their names.
child(name)
Return a child shortcut group given by
name
.enabled()
Returns the state.
enable()
Enable the shorcuts. Note that in case the parent is disabled, this shorcuts do not fire even if they are enabled!
disable()
Disable the shortcuts. Please see the note in
enable()
.priority([priority])
When
priority
is given, the priority is set to that value. Otherwise, the current priority is returned. Note that priorities are only applied, when thepriorities
option is set totrue
.add(key, [handler1], [handler2], [...])
Add handlers for a shortcut given by
key
. See John Resig's hotkeys plugin for more information on the format. As of version 1.1.0, you can prepend the desired event type to your key using the colon character, e.g.keydown:ctrl+a
.keydown
is the default. Other valid events arekeyup
andkeypress
.remove(key, [handler1], [handler2], [...])
Remove handlers for a shortcut given by
key
. If no handlers are given, remove all handlers for thatkey
.empty()
Remove all handlers for all keys.
options()
Returns the current options.
Development
- Source hosted at GitHub
- Report issues, questions, feature requests on GitHub Issues
Authors
Marcel R. (riga)