Make KeyboardEvent cross-browser consistent.

sdk/lib/html/src/KeyboardEventController.dart

+// Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+part of html;
+
+/**
+ * Works with KeyboardEvent and KeyEvent to determine how to expose information
+ * about Key(board)Events. This class functions like an EventListenerList, and
+ * provides a consistent interface for the Dart
+ * user, despite the fact that a multitude of browsers that have varying
+ * keyboard default behavior.
+ *
+ * This class is very much a work in progress, and we'd love to get information
+ * on how we can make this class work with as many international keyboards as
+ * possible. Bugs welcome! 
+ */
+class KeyboardEventController {
+  // This code inspired by Closure's KeyHandling library.
+  // http://closure-library.googlecode.com/svn/docs/closure_goog_events_keyhandler.js.source.html
+  
+  /**
+   * The set of keys that have been pressed down without seeing their
+   * corresponding keyup event.
+   */
+  List<KeyboardEvent> keyDownList;
+
+  /** The set of functions that wish to be notified when a KeyEvent happens. */
+  List<Function> _callbacks;
+
+  /** The type of KeyEvent we are tracking (keyup, keydown, keypress). */
+  String _type;
+
+  // The distance to shift from upper case alphabet Roman letters to lower case.
+  const int _ROMAN_ALPHABET_OFFSET = "a".charCodes[0] - "A".charCodes[0];
+
+  /**
+   * An enumeration of key identifiers currently part of the W3C draft for DOM3
+   * and their mappings to keyCodes.
+   * http://www.w3.org/TR/DOM-Level-3-Events/keyset.html#KeySet-Set
+   */
+  static Map<String, int> _keyIdentifier = {
+    'Up': KeyCode.UP,
+    'Down': KeyCode.DOWN,
+    'Left': KeyCode.LEFT,
+    'Right': KeyCode.RIGHT,
+    'Enter': KeyCode.ENTER,
+    'F1': KeyCode.F1,
+    'F2': KeyCode.F2,
+    'F3': KeyCode.F3,
+    'F4': KeyCode.F4,
+    'F5': KeyCode.F5,
+    'F6': KeyCode.F6,
+    'F7': KeyCode.F7,
+    'F8': KeyCode.F8,
+    'F9': KeyCode.F9,
+    'F10': KeyCode.F10,
+    'F11': KeyCode.F11,
+    'F12': KeyCode.F12,
+    'U+007F': KeyCode.DELETE,
+    'Home': KeyCode.HOME,
+    'End': KeyCode.END,
+    'PageUp': KeyCode.PAGE_UP,
+    'PageDown': KeyCode.PAGE_DOWN,
+    'Insert': KeyCode.INSERT
+  };
+
+  /** Named constructor to add an onKeyPress event listener to our handler. */
+  KeyboardEventController.keypress(EventTarget target) {
+    _KeyboardEventController(target, 'keypress');
+  }
+  
+  /** Named constructor to add an onKeyUp event listener to our handler. */
+  KeyboardEventController.keyup(EventTarget target) {
+    _KeyboardEventController(target, 'keyup');
+  }
+
+  /** Named constructor to add an onKeyDown event listener to our handler. */
+  KeyboardEventController.keydown(EventTarget target) {
+    _KeyboardEventController(target, 'keydown');
+  }
+  
+  /**
+   * General constructor, performs basic initialization for our improved
+   * KeyboardEvent controller.
+   */
+  _KeyboardEventController(EventTarget target, String type) {
+    keyDownList = [];
+    _callbacks = [];
+    _type = type;
+    target.on.keyDown.add(processKeyDown, true);
+    target.on.keyPress.add(processKeyPress, true);
+    target.on.keyUp.add(processKeyUp, true);
+  }
+
+  /** Add a callback that wishes to be notified when a KeyEvent occurs. */
+  void add(Function callback) {

[blois, 2012/11/29 00:03:12]

void callback(KeyEvent)?

[Emily Fortuna, 2012/11/29 01:10:37]

Done.

+    _callbacks.add(callback);
+  }
+  
+  /**
+   * Notify all callback listeners that a KeyEvent of the relevant type has
+   * occurred.
+   */
+  bool _dispatch(KeyEvent event) {
+    if (event.type == _type) {
+      for(var callback in _callbacks) {

[blois, 2012/11/29 00:03:12]

Normally need to copy this list to allow removing while iterating.

[Emily Fortuna, 2012/11/29 01:10:37]

No removing is happening here... just calling the callbacks...?

[blois, 2012/11/29 17:06:34]

Right- if the code being called back removes itself while being called, you get
an error. It's a common thing for events like this to have to clone the list.

[Emily Fortuna, 2012/11/29 19:19:49]

I see. Changed. But how could this happen since Dart is single threaded?

[blois, 2012/11/29 21:04:55]

Scenario: user presses the delete button, user code gets that event, removes the
UI element and during clean removes it's handler from this.

+        callback(event);
+      }
+    }
+  }
+
+  /** Remove the given callback from the listeners list. */
+  void remove(Function callback) {

[blois, 2012/11/29 00:03:12]

void callback(KeyEvent)?

[Emily Fortuna, 2012/11/29 01:10:37]

Done.

+    _callbacks = _callbacks.filter((element) => element != callback);

[blois, 2012/11/29 00:03:12]

Not removeAt? This creates a new list...

Should probably remove all of the event listeners when the # of callbacks goes
to 0 (and re-add when non-zero).

[Emily Fortuna, 2012/11/29 01:10:37]

Done.

[blois, 2012/11/29 17:06:34]

What I meant by remove all event listeners is that the processKey* listeners
should be removed when nothing else is listening here. So rather than hooking
them up in the constructor, hook them up in add when the first callback is
added, then unhook them in remove when the last one is removed.

[Emily Fortuna, 2012/11/29 19:19:49]

sgtm.

+  }
+
+  /** Determine if caps lock is one of the currently depressed keys. */
+  bool get _capsLockOn() =>
+      keyDownList.some((var element) => element.keyCode == KeyCode.CAPS_LOCK);
+
+  /**
+   * Given the previously recorded keydown key codes, see if we can determine
+   * the keycode of this keypress [event]. (Generally browsers only provide
+   * charCode information for keypress events, but with a little
+   * reverse-engineering, we can also determine the keyCode.) Returns
+   * KeyCode.UNKNOWN if the keycode could not be determined.
+   */
+  int _determineKeyCodeForKeypress(KeyboardEvent event) {
+    // Note: This function is a work in progress. We'll expand this function
+    // once we get more information about other keyboards.
+    for (var prevEvent in keyDownList) {
+      if (prevEvent._shadowCharCode == event.charCode) {
+        return prevEvent.keyCode;
+      }
+      if ((event.shiftKey || _capsLockOn) && event.charCode >= "A".charCodes[0]
+          && event.charCode <= "Z".charCodes[0] && event.charCode +
+          _ROMAN_ALPHABET_OFFSET == prevEvent._shadowCharCode) {
+        return prevEvent.keyCode;
+      }
+    }
+    return KeyCode.UNKNOWN;
+  }
+
+  /**
+   * Given the charater code returned from a keyDown [event], try to ascertain
+   * and return the corresponding charCode for the character that was pressed.
+   * This information is not shown to the user, but used to help polyfill
+   * keypress events.
+   */
+  int _findCharCodeKeyDown(KeyboardEvent event) {
+    if (event.keyLocation == 3) { // Numpad keys.
+      switch (event.keyCode) {
+        case KeyCode.NUM_ZERO:
+          // Even though this function returns _charCodes_, for some cases the
+          // KeyCode == the charCode we want, in which case we use the keycode
+          // constant for readability.
+          return KeyCode.ZERO;
+        case KeyCode.NUM_ONE:
+          return KeyCode.ONE;
+        case KeyCode.NUM_TWO:
+          return KeyCode.TWO;
+        case KeyCode.NUM_THREE:
+          return KeyCode.THREE;
+        case KeyCode.NUM_FOUR:
+          return KeyCode.FOUR;
+        case KeyCode.NUM_FIVE:
+          return KeyCode.FIVE;
+        case KeyCode.NUM_SIX:
+          return KeyCode.SIX;
+        case KeyCode.NUM_SEVEN:
+          return KeyCode.SEVEN;
+        case KeyCode.NUM_EIGHT:
+          return KeyCode.EIGHT;
+        case KeyCode.NUM_NINE:
+          return KeyCode.NINE;
+        case KeyCode.NUM_MULTIPLY:
+          return 42; // Char code for *
+        case KeyCode.NUM_PLUS:
+          return 43; // +
+        case KeyCode.NUM_MINUS:
+          return 45; // -
+        case KeyCode.NUM_PERIOD:
+          return 46; // .
+        case KeyCode.NUM_DIVISION:
+          return 47; // /
+      }
+    } else if (event.keyCode >= 65 && event.keyCode <= 90) {
+      // Set the "char code" for key down as the lower case letter. Again, this
+      // will not show up for the user, but will be helpful in estimating
+      // keyCode locations and other information during the keyPress event.
+      return event.keyCode + _ROMAN_ALPHABET_OFFSET;
+    }
+    switch(event.keyCode) {
+      case KeyCode.SEMICOLON:
+        return KeyCode.FF_SEMICOLON;
+      case KeyCode.EQUALS:
+        return KeyCode.FF_EQUALS;
+      case KeyCode.COMMA:
+        return 44; // Ascii value for ,
+      case KeyCode.DASH:
+        return 45; // -
+      case KeyCode.PERIOD:
+        return 46; // .
+      case KeyCode.SLASH:
+        return 47; // /
+      case KeyCode.APOSTROPHE:
+        return 96; // `
+      case KeyCode.OPEN_SQUARE_BRACKET:
+        return 91; // [
+      case KeyCode.BACKSLASH:
+        return 92; // \
+      case KeyCode.CLOSE_SQUARE_BRACKET:
+        return 93; // ]
+      case KeyCode.SINGLE_QUOTE:
+        return 39; // '
+    }
+    return event.keyCode;
+  }
+
+  /**
+   * Returns true if the key fires a keypress event in the current browser.
+   */
+  bool _firesKeyPressEvent(KeyEvent event) {
+    if (!_Device.isIE && !_Device.isWebKit) {
+      return true;
+    }
+    
+    if (_Device.userAgent.contains('Mac') && event.altKey) {
+      return KeyCode.isCharacterKey(event.keyCode);
+    }
+ 
+    // Alt but not AltGr which is represented as Alt+Ctrl.
+    if (event.altKey && !event.ctrlKey) {
+      return false;
+    }
+ 
+    // Saves Ctrl or Alt + key for IE and WebKit, which won't fire keypress.
+    if (!event.shiftKey &&
+        (keyDownList.last.keyCode == KeyCode.CTRL ||
+         keyDownList.last.keyCode == KeyCode.ALT ||
+         _Device.userAgent.contains('Mac') &&
+         keyDownList.last.keyCode == KeyCode.META)) {
+      return false;
+    }
+ 
+    // Some keys with Ctrl/Shift do not issue keypress in WebKit.
+    if (_Device.isWebKit && event.ctrlKey && event.shiftKey && (
+        event.keycode == KeyCode.BACKSLASH ||
+        event.keycode == KeyCode.OPEN_SQUARE_BRACKET ||
+        event.keycode == KeyCode.CLOSE_SQUARE_BRACKET ||
+        event.keycode == KeyCode.TILDE ||
+        event.keycode == KeyCode.SEMICOLON || event.keycode == KeyCode.DASH ||
+        event.keycode == KeyCode.EQUALS || event.keycode == KeyCode.COMMA ||
+        event.keycode == KeyCode.PERIOD || event.keycode == KeyCode.SLASH ||
+        event.keycode == KeyCode.APOSTROPHE ||
+        event.keycode == KeyCode.SINGLE_QUOTE)) {
+      return false;
+    }
+ 
+    switch (event.keyCode) {
+      case KeyCode.ENTER:
+        // IE9 does not fire keypress on ENTER.
+        return !_Device.isIE;
+      case KeyCode.ESC:
+        return !_Device.isWebKit;
+    }
+ 
+    return KeyCode.isCharacterKey(event.keyCode);
+  }
+
+  /**
+   * Normalize the keycodes to the IE KeyCodes (this is what Chrome, IE, and
+   * Opera all use).
+   */
+  int normalizeKeyCodes(KeyboardEvent event) {
+    // Note: This may change once we get input about non-US keyboards.
+    if (_Device.isFirefox) {
+      switch(event.keyCode) {
+        case KeyCode.FF_EQUALS:
+          return KeyCode.EQUALS;
+        case KeyCode.FF_SEMICOLON:
+          return KeyCode.SEMICOLON;
+        case KeyCode.MAC_FF_META:
+          return KeyCode.META;
+        case KeyCode.WIN_KEY_FF_LINUX:
+          return KeyCode.WIN_KEY;
+      }
+    }
+    return event.keyCode;
+  }
+
+  /** Handle keydown events. */
+  void processKeyDown(KeyboardEvent e) {
+    // Ctrl-Tab and Alt-Tab can cause the focus to be moved to another window
+    // before we've caught a key-up event.  If the last-key was one of these
+    // we reset the state.
+    if (keyDownList.length > 0 &&
+        (keyDownList.last.keyCode == KeyCode.CTRL && !e.ctrlKey ||
+         keyDownList.last.keyCode == KeyCode.ALT && !e.altKey ||
+         _Device.userAgent.contains('Mac') &&
+         keyDownList.last.keyCode == KeyCode.META && !e.metaKey)) {
+      keyDownList = [];
+    }
+
+    var event = new KeyEvent(e);
+    event._shadowKeyCode = normalizeKeyCodes(event);
+    // Technically a "keydown" event doesn't have a charCode. This is
+    // calculated nonetheless to provide us with more information in giving
+    // as much information as possible on keypress about keycode and also
+    // charCode.
+    event._shadowCharCode = _findCharCodeKeyDown(event);
+    if (keyDownList.length > 0 && event.keyCode != keyDownList.last.keyCode &&
+        !_firesKeyPressEvent(event)) {
+      // Some browsers have quirks not firing keypress events where all other
+      // browsers do. This makes them more consistent.
+      processKeyPress(event);
+    }
+    keyDownList.add(event);
+    _dispatch(event);
+  }
+
+  /** Handle keypress events. */
+  void processKeyPress(KeyboardEvent event) {
+    var e = new KeyEvent(event);
+    // IE reports the character code in the keyCode field for keypress events.
+    // There are two exceptions however, Enter and Escape.
+    if (_Device.isIE) {
+      if (e.keyCode == KeyCode.ENTER || e.keyCode == KeyCode.ESC) {
+        e._shadowCharCode = 0;
+      } else {
+        e._shadowCharCode = e.keyCode;
+      }
+    } else if (_Device.isOpera) {
+      // Opera reports the character code in the keyCode field.
+      e._shadowCharCode = KeyCode.isCharacterKey(keyCode) ? e.keyCode : 0;
+    }
+    // Now we guestimate about what the keycode is that was actually
+    // pressed, given previous keydown information.
+    e._shadowKeyCode = _determineKeyCodeForKeypress(e);
+
+    // Correct the key value for certain browser-specific quirks.
+    if (e._shadowKeyIdentifier &&
+        _keyIdentifier.contains(e._shadowKeyIdentifier)) {
+      // This is needed for Safari Windows because it currently doesn't give a
+      // keyCode/which for non printable keys.
+      e._shadowKeyCode = _keyIdentifier[keyIdentifier];
+    }
+    e._shadowAltKey = keyDownList.some((var element) => element.altKey);
+    _dispatch(e);
+  }
+
+  /** Handle keyup events. */
+  void processKeyUp(KeyboardEvent event) {
+    var e = new KeyEvent(event);
+    KeyboardEvent toRemove = null;
+    for (var key in keyDownList) {
+      if (key.keyCode == e.keyCode) {
+        toRemove = key;
+      }
+    }
+    if (toRemove != null) {
+      keyDownList = keyDownList.filter((element) => element != toRemove);
+    } else if (keyDownList.length > 0) {
+      // This happens when we've reached some international keyboard case we
+      // haven't accounted for or we haven't correctly eliminated all browser
+      // inconsistencies. Filing bugs on when this is reached is welcome! 
+      keyDownList.removeLast(); 
+    }
+    _dispatch(e);
+  }
+}