{"id":3399,"date":"2015-01-12T16:31:21","date_gmt":"2015-01-12T22:31:21","guid":{"rendered":"http:\/\/bililite.com\/blog\/?p=3399"},"modified":"2015-01-12T16:31:21","modified_gmt":"2015-01-12T22:31:21","slug":"rethinking-keymap","status":"publish","type":"post","link":"https:\/\/bililite.com\/blog\/2015\/01\/12\/rethinking-keymap\/","title":{"rendered":"Rethinking $.keymap<\/code>"},"content":{"rendered":"

Download the code<\/a>.<\/p>\n

See the demo<\/a>.<\/p>\n

See the hotkeys demo<\/a>.<\/p>\n

Dealing with keydown<\/code> events is a pain, since the event object has always encoded the key as an arbitrary numeric code, so any program that deals with key-related events has something like:<\/p>\n

var charcodes = {\r\n\t 32\t: ' ',\r\n\t  8\t: 'Backspace',\r\n\t 20\t: 'CapsLock',\r\n\t 46\t: 'Delete',\r\n\t 13\t: 'Enter',\r\n\t 27\t: 'Escape',\r\n\t 45\t: 'Insert',\r\n\t144\t: 'NumLock',\r\n\t  9\t: 'Tab'\r\n};<\/code><\/pre>\n
And so on. There is a proposal<\/a> to add a key<\/code> field that uses standardized names for the keys<\/a>, but only Firefox and IE implement that right now<\/a>. The time is ripe for a polyfill to bring Chrome and Safari into the twenty-first century, and I'd already worked on something similar with my $.keymap<\/code> plugin<\/a>.<\/p>\n
So I updated that plugin to simply implement the key<\/code> field in keydown<\/code> and keyup<\/code> events. Now just include the plugin and you can do things like:<\/p>\n
$('textarea').keydown(function(event){\r\n  if (event.key == 'Escape') { do something useful }\r\n});<\/code><\/pre>\n
<\/p>\n
I also added a nonstandard field called keymap<\/code> that includes the state of the modifier keys, using Microsoft's sendkeys<\/a> notation, with +<\/code> for shift, ^<\/code> for control and %<\/code> for alt. While Windows doesn't have a meta key, it's part of the standard key event, and I included that with ~<\/code> for meta. I can't test it, though, so feedback on whether it works would be nice. So now rather than doing:<\/p>\n
$('textarea').keydown(function(event){\r\n  if (event.key == 'Enter' && event.ctrlKey && event.shiftKey && !event.altKey && !event.metaKey) { do something useful }\r\n});<\/code><\/pre>\n
you can do:<\/p>\n
$('textarea').keydown(function(event){\r\n  if (event.keymap == '^+Enter') { do something useful }\r\n});<\/code><\/pre>\n
There's one exception: the standard uses ' '<\/code> for the key<\/code> value for the space bar, where IE uses Spacebar<\/code>. I think the latter is more useful, since I can't see the space character (and I want to use space as a delimiter). So the key<\/code> field is ' '<\/code>, per the standard, but keymap<\/code> use Spacebar<\/code>.<\/p>\n
It will normalize synthetic keystrokes too, so doing:<\/p>\n
$(el).trigger({type: 'keydown', keymap: '^%a'});<\/code><\/pre>\n
or<\/p>\n
$(el).trigger({type: 'keydown', key: 'a', ctrlKey: true, altKey: true});<\/code><\/pre>\n
allows you to do<\/p>\n
$(el).on('keydown', function (event){\r\n  if (event.key == 'a' && event.ctrlKey && event.altKey) {do something useful}\r\n});<\/code><\/pre>\n
or simply<\/p>\n
$(el).on('keydown', function (event){\r\n  if (event.keymap == '^%a') {do something useful}\r\n});<\/code><\/pre>\n
The keymap<\/code> passed as part of a synthetic event will be normalized to the standard key names, as will the key<\/code> field. Indicate shifted letters with uppercase; thus control-a is '^a'<\/code> and control-shift-a is '^A'<\/code>, not '+^a'<\/code>. Redundant shifts are removed: '+@'<\/code> is normalized to '@'<\/code>. It also allows for VIM<\/a> and jquery.hotkeys<\/a> notation; thus both '<C-a><\/code> and 'ctrl+a'<\/code> are normalized to '^a'<\/code>. Please look at the source for aliasgenerator<\/code><\/a> for all the translations.<\/p>\n
Hotkeys<\/h3>\n
Writing if (event.keymap = '^%a') { ...<\/code> gets old, and I wanted to be able to look for sequences of characters as well (Escape<\/code> %<\/code> if I'm trying to implement emacs). John Resig wrote a hotkeys plugin<\/a> and I added keyup<\/code> and keydown<\/code> handlers to implement the same idea. Add a keys<\/code> field to the data<\/code> argument and the handler will only be called if the keymap<\/code> of that event matches it (it should be called keymaps<\/code> rather than keys<\/code>, for consistency. I'm keeping it this way). Use a space-delimited list of keys to match a sequence (and use Spacebar<\/code> to match the space key). The keys<\/code> field will be normalized as above, so any notation works. The Event object will have an additional field, hotkeys<\/code>, which is the sequence of keys matched.
\nThus:<\/p>\n
$(el).on('keydown', {keys: '^%a'}, handler);\r\n$(el).off('keydown', {keys: '^%a'}); \/\/ works\r\n$(el).off('keydown', handler); \/\/ DOES NOT WORK. The plugin changes the handler internally so the remove mechanism can't search for it.\r\n\r\n$('body').on('keydown', {\r\n    keys: 'up up down down left right left right b a' \/\/ This will be normalized to ArrowUp ArrowUp ArrowDown ArrowDown ArrowLeft ArrowRight ArrowLeft ArrowRight b a\r\n  }, \r\n  function() {alert('Konami!')}\r\n);\r\n\r\n$('body').on('keydown', 'input', {keys: '^A'}, function() {alert('Control A was pressed in an input')} ); \/\/ selectors work\r\n\r\n$(el).keydown ({keys: 'C-x C-s'}, function(event){ \/\/ $.keydown is just a shortcut for $.on('keydown'...\r\n  \/\/ do emacs save-buffer, somehow...\r\n\r\n  console.log (event.hotkeys); \/\/ displays '^x ^s', the \"normalized\" form of the keystrokes\r\n});<\/code><\/pre>\n
You can also use a regular expression to match keys, but that has to match the final normalized keystrokes, including exactly one space between keys:<\/p>\n
$(el).keydown({keys: \/\" [a-z] p\/}, function (event){\r\n  \/\/ the vi put command\r\n  var buffer = event.hotkeys.charAt(1); \/\/ the letter matching [a-z] above\r\n  \/\/ do the put command\r\n});<\/code><\/pre>\n
There's one other option: allowDefault<\/code>. Normally if a sequence is in the process of being matched, the intermediate keystrokes are discarded. Set allowDefault<\/code> to true<\/code> to pass them through. So, for the Konami code you would still want the arrow keys to work:<\/p>\n
$('body').on('keydown', {\r\n    keys: '{up} {up} {down} {down} {left} {right} {left} {right} b a', \/\/ braces notation from Microsoft's sendkeys will be normalized\r\n    allowDefault: true \/\/ the arrow keys will still work\r\n  }, \r\n  function() {alert('Konami!')}\r\n);<\/code><\/pre>\n
Events<\/h4>\n
The hotkeys plugin also triggers two other events: 'keymapprefix'<\/code> when the event is the prefix of a valid sequence, and 'keymapcomplete'<\/code> when a sequence is matched. Both are sent with an additional parameter indicating what keys were pressed so far (in the normalized notation). So:<\/p>\n
$('body').on('keymapprefix keymapcomplete', function(event, keys){\r\n\talert ('sequence pressed: '+keys);\r\n})<\/code><\/pre>\n
Localization<\/h3>\n
The code as it stands assumes a standard US-English keyboard. There's no way for javascript code to know what keyboard the user has<\/a>. This is bad in browsers that do not support key<\/code> directly, since all I get is the keyCode<\/code>, and that corresponds to a different character in every keyboard. But even in browsers that support key<\/code> natively, I still need to know whether the key should be marked with a +<\/code> when shifted; for instance, '@' with shiftKey<\/code> set should have a keymap<\/code> of @<\/code> (no +<\/code>, since that character implies the shift), but the 'DEL' key with shiftKey<\/code> set should have a keymap<\/code> of +Delete<\/code>. This is even more of a problem with the AltGr key, which in most keyboards does not change the printed character and thus needs to be indicated in keymap<\/code>.<\/p>\n
As far as I can tell, there are two modifier keys that affect the printed character: shift and AltGr. In all modern browsers<\/a>, AltGr is indicated by setting both ctrlKey<\/code> and altKey<\/code>, so keymap<\/code> indicates it with ^%<\/code>; so AltGr and the A key produces ^%a<\/code>.<\/p>\n
You can change the assumed keyboard layout with $.keymap.setlayout(layout)<\/code>, where layout<\/code> is a object of the form:<\/p>\n
{\r\n  normal: \"`1234567890-=\\\\qwertyuiop[]asdfghjkl;'zxcvbnm,.\/\",\r\n  shift: ... \/\/ keyboard layout for shifted keys\r\n  alt: ... \/\/ keyboard layout for the AltGr key\r\n  shift_alt: ... \/\/ keyboard layout for Shift and AltGr key both held down\r\n}<\/code><\/pre>\n
Each string should have 47 characters, just the rows of the keyboard left to right and top to bottom (it assumes the keyboard that has an extra-large Enter key and the backslash to the right of '=', not right of ']'). The format is that used by Virtual Keyboard<\/a>, which I use extensively<\/a>. Unfortunately, the development site<\/a> seems to be dead, but you can download the source from SourceForge<\/a> and look in the layouts folder for layout formats for lots of different languages.<\/p>\n
Keys that do not change with the modifier should be indicated with '\\00'<\/code>, or use an abbreviated format: an object {index1: substring1, index2: substring2 ...}<\/code> where index<\/code> is the starting index of the given substring. For all keys that have an uppercase, if the shift<\/code> string is not set, it will be set to c.toUpperCase()<\/code>. Any of the strings may be omitted, and will be assumed to be all blank. For example:<\/p>\n
var layouts = {\r\n\tUS :{\r\n\t\tnormal:'`1234567890-=\\\\qwertyuiop[]asdfghjkl;\\'zxcvbnm,.\/',\r\n\t\tshift:{0:'~!@#$%^&*()_+|',24:'{}',35:':\"',44:'<>?'} \/\/ note the uppercase letters are skipped; the plugin can figure that out for itself\r\n\t},\r\n\tUK :{\r\n\t\tnormal:'`1234567890-=#qwertyuiop[]asdfghjkl;\\'zxcvbnm,.\/',\r\n\t\tshift:{0:'\u00ac!\"\u00a3$%^&*()_+~',24:'{}',35:':@',44:'<>?'},\r\n\t\talt:{0:'\u00a6',4:'\u20ac',16:'\u00e9',20:'\u00fa\u00ed\u00f3',26:'\u00e1'} \/\/ altGr keys\r\n\t},\r\n\tIsrael : {\r\n\t\tnormal:';1234567890-=\\\\\/\\'\u05e7\u05e8\u05d0\u05d8\u05d5\u05df\u05dd\u05e4][\u05e9\u05d3\u05d2\u05db\u05e2\u05d9\u05d7\u05dc\u05da\u05e3,\u05d6\u05e1\u05d1\u05d4\u05e0\u05de\u05e6\u05ea\u05e5.',\r\n\t\tshift:{0:'~!@#$%^&*)(_+|QWERTYUIOP}{ASDFGHJKL:\"ZXCVBNM><'+'?'}, \/\/ I had to split the < and ? up to avoid confusing my syntax highlighter\r\n\t\talt:{3:'\u20ac\u20aa\u00b0\u05ab\u05bd\u00d7\u200e\u200f',11:'\u200f\u05be\u2013\u05bb\u05c2',16:'\u05b8\u05b3',19:'\u05f0\u05b9',23:'\u05b7\u05b2\u05bf\u05b0\u05bc',30:'\u05f1\u05f2\u05b4',34:'\u201d\u201e\u05f4',43:'\u05b5\u2019\u201a\u00f7'}\r\n\t}\r\n};\r\n$.keymap.setlayout(layouts.Israel);<\/code><\/pre>\n
Utilities<\/h3>\n
$.keymap(event)<\/code> is the basic plugin; it normalizes the Event object as described (setting key<\/code> and keymap<\/code>) and returns the value of keymap<\/code>. Possibly useful if you are handling events straight with addEventListener()<\/code>; the plugin patches the jQuery handing to automatically do this.<\/p>\n
$.keymap.normalize(event)<\/code> is the same as $.keymap(event)<\/code> but returns event<\/code>.<\/p>\n
$.keymap.normalizeString(string)<\/code> is the workhorse function to normalize the key descriptions; $.keymap.normalizeString('ctrl-esc')<\/code> returns '^Escape'<\/code>.<\/p>\n
$.keymap.normalizeList(string)<\/code> does the same for a space-delimited list of key descriptions; $.keymap.normalizeList('ctrl-esc %   alt-5')<\/code> returns '^Escape % %5'<\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"
Download the code. See the demo. See the hotkeys demo. Dealing with keydown events is a pain, since the event object has always encoded the key as an arbitrary numeric code, so any program that deals with key-related events has something like: var charcodes = { 32 : ' ', 8 : 'Backspace', 20 : […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[10,5],"tags":[],"_links":{"self":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3399"}],"collection":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/comments?post=3399"}],"version-history":[{"count":27,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3399\/revisions"}],"predecessor-version":[{"id":3426,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/posts\/3399\/revisions\/3426"}],"wp:attachment":[{"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/media?parent=3399"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/categories?post=3399"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/bililite.com\/blog\/wp-json\/wp\/v2\/tags?post=3399"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}