Distinguish between keystroke and character events.

ui/events/event.h

Index: ui/events/event.h
diff --git a/ui/events/event.h b/ui/events/event.h
index 64a3a01bf7b3301087bc3386b72595ac65c90535..ea826f9b29eb0dee6a15fad49e0201439063274b 100644
--- a/ui/events/event.h
+++ b/ui/events/event.h
@@ -543,30 +543,66 @@ class EVENTS_EXPORT TouchEvent : public LocatedEvent {
   float force_;
 };
 
+// A KeyEvent is really two distinct classes, melded together due to the
+// DOM legacy of Windows key events: a keystroke event (is_char_ == false),
+// or a character event (is_char_ == true).
+//
+// For a keystroke event,
+// -- is_char_ is false.
+// -- type() can be any one of ET_KEY_PRESSED, ET_KEY_RELEASED,
+//    ET_TRANSLATED_KEY_PRESS, or ET_TRANSLATED_KEY_RELEASE.
+// -- character_ functions as a bypass or cache for GetCharacter().
+// -- key_code_ is a VKEY_ value associated with the key. For printable
+//    characters, this may or may not be a mapped value, imitating MS Windows:
+//    if the mapped key generates a character that has an associated VKEY_
+//    code, then key_code_ is that code; if not, then key_code_ is the unmapped
+//    VKEY_ code. For example, US, Greek, Cyrillic, Japanese, etc. all use
+//    VKEY_Q for the key beside Tab, while French uses VKEY_A.
+// -- code_ is in one-to-one correspondence with a physical keyboard
+//    location, and does not vary depending on key layout.
+//
+// For a character event,
+// -- is_char_ is true.
+// -- type() is ET_KEY_PRESSED.
+// -- character_ is a UTF-16 character value.
+// -- key_code_ is conflated with character_ by some code, because both
+//    arrive in the wParam field of a Windows event.
+// -- code_ is "".
+//
 class EVENTS_EXPORT KeyEvent : public Event {
  public:
-  KeyEvent(const base::NativeEvent& native_event, bool is_char);
+  // Create a KeyEvent from a NativeEvent. For Windows this native event can
+  // be either a keystroke message (WM_KEYUP/WM_KEYDOWN) or a character message
+  // (WM_CHAR). Other systems have only keystroke events.
+  explicit KeyEvent(const base::NativeEvent& native_event);
 
-  // Used for synthetic events.
-  KeyEvent(EventType type, KeyboardCode key_code, int flags, bool is_char);
+  // Create a keystroke event.
+  KeyEvent(EventType type, KeyboardCode key_code, int flags);
+
+  // Create a character event.
+  KeyEvent(base::char16 character, KeyboardCode key_code, int flags);
 
   // Used for synthetic events with code of DOM KeyboardEvent (e.g. 'KeyA')
   // See also: ui/events/keycodes/dom4/keycode_converter_data.h
-  KeyEvent(EventType type, KeyboardCode key_code, const std::string& code,
-           int flags, bool is_char);
+  KeyEvent(EventType type,
+           KeyboardCode key_code,
+           const std::string& code,
+           int flags);
 
   // This allows an I18N virtual keyboard to fabricate a keyboard event that
   // does not have a corresponding KeyboardCode (example: U+00E1 Latin small
   // letter A with acute, U+0410 Cyrillic capital letter A).
-  void set_character(uint16 character) { character_ = character; }
+  void set_character(base::char16 character) { character_ = character; }
 
   // Gets the character generated by this key event. It only supports Unicode
   // BMP characters.
-  uint16 GetCharacter() const;
+  base::char16 GetCharacter() const;
 
   // Gets the platform key code. For XKB, this is the xksym value.
   uint32 platform_keycode() const { return platform_keycode_; }
   KeyboardCode key_code() const { return key_code_; }
+
+  // True if this is a character event, false if this is a keystroke event.
   bool is_char() const { return is_char_; }
 
   // This is only intended to be used externally by classes that are modifying
@@ -580,9 +616,8 @@ class EVENTS_EXPORT KeyEvent : public Event {
 
   std::string code() const { return code_; }
 
-  // Normalizes flags_ to make it Windows/Mac compatible. Since the way
-  // of setting modifier mask on X is very different than Windows/Mac as shown
-  // in http://crbug.com/127142#c8, the normalization is necessary.
+  // Normalizes flags_ so that it describes the state after the event.
+  // (Native X11 event flags describe the state before the event.)
   void NormalizeFlags();
 
   // Returns true if the key event has already been processed by an input method
@@ -592,6 +627,8 @@ class EVENTS_EXPORT KeyEvent : public Event {
   void SetTranslated(bool translated);
 
  protected:
+  friend class KeyEventTestApi;
+
   // This allows a subclass TranslatedKeyEvent to be a non character event.
   void set_is_char(bool is_char) { is_char_ = is_char; }
 
@@ -605,8 +642,7 @@ class EVENTS_EXPORT KeyEvent : public Event {
   // converted from / to keyboard scan code like XKB.
   std::string code_;
 
-  // True if this is a translated character event (vs. a raw key down). Both
-  // share the same type: ET_KEY_PRESSED.
+  // True if this is a character event, false if this is a keystroke event.
   bool is_char_;
 
   // The platform related keycode value. For XKB, it's keysym value.
@@ -619,7 +655,7 @@ class EVENTS_EXPORT KeyEvent : public Event {
   // This value represents the text that the key event will insert to input
   // field. For key with modifier key, it may have specifial text.
   // e.g. CTRL+A has '\x01'.
-  uint16 character_;
+  base::char16 character_;
 
   static bool IsRepeated(const KeyEvent& event);