Skip to content

Latest commit

 

History

History
159 lines (117 loc) · 5.68 KB

keyboard.md

File metadata and controls

159 lines (117 loc) · 5.68 KB
Raw

KeyboardEvent Polyfill

Polyfill for the additional KeyboardEvent properties defined in the D3E and D4E draft specifications:

Details

For all browsers (except IE7-) this adds the following properties to KeyboardEvent instances:

  • event.code - (string) identifier of the key from D3E
  • event.key - (string) printed representation of the key from D3E
  • event.location - (number) location of key on device, from the DOM 3 Events working draft

It also adds a static method:

  • KeyboardEvent.queryKeyCap(code) - yields a human readable label for the key

As a helper for IE7-, it also a non-standard function to the global namespace:

  • identifyKey(keyboardEvent)

The keyboardEvent argument should be a keyup/keydown DOM event. After calling this, the event will be populated with code, key and location properties.

Example

div.onkeydown = function(e) {
  identifyKey(e); // for IE7-
  switch (e.code) {
    case 'ArrowLeft': map.scroll(-10, 0); break;
    case 'ArrowRight': map.scroll(10, 0); break;
    case 'ArrowUp': map.scroll(0, -10); break;
    case 'ArrowDown': map.scroll(0, 10); break;
  }
};

Background: Keys vs. Characters

In most operating systems, physical key presses generate events (keydown, keyup) which are delivered to applications but simultaneously processed by the operating system to perform actions or generate characters. For example:

  • Keys: [A] - generate character 'a'
  • Keys: [Shift] - no character generated
  • Keys: [Shift]+[A] - generate character 'A'
  • Keys: [9] - generate character '9'
  • Keys: [Shift]+[9] - generate character '('
  • Keys: [;:] - generate character ';'
  • Keys: [Shift]+[;:] - generate character ':'
  • Keys: [Alt]+[`~], [E] - generate e with grave accent
  • Keys: [Alt]+[0],[1],[2],[8] - generate Euro symbol
  • Keys: [Enter] - generate 0x0D character (maybe)
  • Keys: [Esc] - generate 0x1B character (maybe)

And of course, for non-Latin languages things get even more complicated including IMEs where multiple keystrokes may generate a list of candidate characters in an OS- or application-provided display, from which the user selects before the character is presented to the application.

Browsers and Key Events

Keyboard events were implemented before a specification was written; as such, the behavior across browsers is very different. The HTML4 spec defines the model as sending 'keydown' and 'keyup' events corresponding to physical actions with the keys (with possibly repeated 'keydown' events due to auto-repeat), and 'keypress' events corresponding to the generation of a character. The actual properties identifying the key are unspecified, but can be described as:

  readonly attribute unsigned long keyCode;
  readonly attribute unsigned long charCode;
  readonly attribute unsigned long which;

  • keyCode is a OS/browser dependent code identifying the specific key; sent on keydown and keyup events

  • charCode is the Unicode code point of character generated by key press sequence, sent on keypress events

  • which is only used in some browsers - it's basically like charCode combined with keyCode

For compatibility most browsers conform on the keyCode values produced by Microsoft Internet Explorer. But some browsers deviate

  • notably Firefox - and there several are OS- and browser-specific quirks.

IE's keyCode values derive from Windows Virtual Key Codes. MSDN

Safari and Chrome adopted the IE model and codes for compatibility webkit-dev

Firefox (Mozilla/Gecko) uses a very similar set of codes, which differ for a handful of keys for punctuation symbols. MDN

Older versions of Opera also uses different codes for some non-alphabetic keys. dev.opera.com

Other references:

Emerging Standards and Directions

The DOM Level 3 Events (D3E) draft specification defines new properties for KeyboardEvent:

  readonly attribute DOMString code;
  readonly attribute DOMString key;
  readonly attribute unsigned long location;

code is a standardized key identifier mapping to a physical key on the device, rather like a USB code.

key is a string giving the printed representation of the key, or other identifier.

location is a number identifying the physical location of the key - standard, left vs. right, numpad, etc.

Earlier drafts of the specs use keyLocation instead of location, keyIdentifier instead of key, and keyChar instead of char. Some browsers (Chrome, Safari) have partial implementation of these earlier properties.

The DOM Level 4 Events (D4E) draft specification defines a new method on KeyboardEvent:

  static DOMString queryKeyCap (DOMString code, optional DOMString locale);

For cross-browser legacy mappings, see:

http://dev.w3.org/2006/webapi/DOM-Level-3-Events/html/Note-KeyProps.html

Known Issues

  • Win/Chrome, Win/Safari, Win/IE, Win/Firefox - PrintScreen and Scroll only generate keyup events
  • Win/Chrome - Apps doesn't send keyup
  • Win/Opera - Tab moves focus even if cancelled; need explicit workaround to return focus
  • Windows w/ Apple's Bootcamp: Backquote, BackSlash and Quote are mixed up in Chrome and IE