The filtering spec

Example subscriptions might look like this:

// certain keys can be referenced by name
input.on('key', saveAndClose, 'enter');

// require modifier keys with +(modifier)
Y.one('doc').on('key', composeMail, 'n+ctrl');

// specify the event and key codes
datatable.get('contentBox')
    .delegate('key', moveAround, 'down:37,38,39,40', '.yui3-datatable-liner');

The third argument is the filtering spec. Similar to using the node.delegate() method, the callback is only executed if the key event matches the filter. The supported filter syntax is a string defined like this:

1. (0..1) type followed by a colon
2. (0..n) comma separated codes
3. (0..n) modifiers, each preceded by "+"

Choo choo!

If you're into railroad diagrams, the filter spec looks like this:

• "

• type :

• code

  ,

• +modifier

• "

Filter tokens

type

"down", "up", or "press" for keydown, keyup, and keypress. The default is keypress.

code

Any numeric keyCode, unicode character, or common key name.

modifier

"shift", "alt", "ctrl", or "meta". "meta" is the Windows key on Windows-friendly keyboards or the Command key on Apple keyboards. Remember each must be prefixed with "+".

Common keys by name

Certain keys are common enough that referring to them by name is just easier and makes the code more readable. The supported key names are:

If any of these are found in the spec, the default type becomes keydown.

If you have a mind to extend this map, it's stored in Y.Node.DOM_EVENTS.key.eventDef.KEY_MAP. For example, to add support for node.on('key', callback, 'arrowup'), you'd do:

Y.Node.DOM_EVENTS.key.eventDef.KEY_MAP.arrowup = 38;

Caveats

1. You can't yet indicate that modifiers must not be in effect or key combinations must only include those modifiers.
2. You can't yet specify types or modifiers on a per-code basis.
3. Though you can specify keys by their common name, the event is not yet decorated in any way with that common name, so you still have to refer to the keyCode in callback code.