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 element we are watching for events to happen on. */
+  EventTarget _target;
+
+  // 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) {
+    _callbacks = [];
+    _type = type;
+    _target = target;
+    _initializeAllEventListeners();
+  }
+
+  /**
+   * Hook up all event listeners under the covers so we can estimate keycodes
+   * and charcodes when they are not provided.
+   */
+  void _initializeAllEventListeners() {
+    keyDownList = [];
+    _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(void callback(KeyEvent)) {
+    if (_callbacks.length == 0) {
+      _initializeAllEventListeners();
+    }
+    _callbacks.add(callback);
+  }
+  
+  /**
+   * Notify all callback listeners that a KeyEvent of the relevant type has
+   * occurred.
+   */
+  bool _dispatch(KeyEvent event) {
+    if (event.type == _type) {
+      // Make a copy of the listeners in case a callback gets removed while
+      // dispatching from the list.
+      List callbacksCopy = new List.from(_callbacks);
+      for(var callback in callbacksCopy) {
+        callback(event);
+      }
+    }
+  }
+
+  /** Remove the given callback from the listeners list. */
+  void remove(void callback(KeyEvent)) {
+    var index = _callbacks.indexOf(callback);
+    if (index != -1) {
+      _callbacks.removeAd(index);

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

removeAt?

[Emily Fortuna, 2012/11/30 00:08:52]

Eeek you can tell I pushed this new code in right before my interview training.
sorry about that.

+    }
+    if (_callbacks.length == 0) {
+      // If we have no listeners, don't bother keeping track of keypresses.
+      target.on.keyDown.remove(processKeyDown);

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

_target?

[Emily Fortuna, 2012/11/30 00:08:52]

Done.

+      target.on.keyPress.remove(processKeyPress);

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

Dart does not (currently?) have unique closure identity, meaning that
processKeyPress will be different here than where it was added.

You need to assign the method to an instance member, then add/remove that
instance member.

[Emily Fortuna, 2012/11/30 00:08:52]

Done.

+      target.on.keyUp.remove(processKeyUp);
+    }
+  }
+
+  /** 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);
+  }
+}