Distinguish between keystroke and character events.

ui/events/event.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef UI_EVENTS_EVENT_H_
 #define UI_EVENTS_EVENT_H_
 
 #include "base/basictypes.h"
 #include "base/compiler_specific.h"
 #include "base/event_types.h"
@@ skipping 525 matching lines @@
   // Radius of the Y (minor) axis of the touch ellipse. 0.0 if unknown.
   float radius_y_;
 
   // Angle of the major axis away from the X axis. Default 0.0.
   float rotation_angle_;
 
   // Force (pressure) of the touch. Normalized to be [0, 1]. Default to be 0.0.
   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
   // events in EventFilter::PreHandleKeyEvent().  set_character() should also be
   // called.
   void set_key_code(KeyboardCode key_code) { key_code_ = key_code; }
 
   // Returns true for [Alt]+<num-pad digit> Unicode alt key codes used by Win.
   // TODO(msw): Additional work may be needed for analogues on other platforms.
   bool IsUnicodeKeyCode() const;
 
   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
   // and there is no need to pass the key event to the input method again.
   bool IsTranslated() const;
   // Marks this key event as translated or not translated.
   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; }
 
  private:
   KeyboardCode key_code_;
 
   // String of 'code' defined in DOM KeyboardEvent (e.g. 'KeyA', 'Space')
   // http://www.w3.org/TR/uievents/#keyboard-key-codes.
   //
   // This value represents the physical position in the keyboard and can be
   // 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.
   // For now, this is used for CharacterComposer in ChromeOS.
   uint32 platform_keycode_;
 
   // String of 'key' defined in DOM KeyboardEvent (e.g. 'a', 'â')
   // http://www.w3.org/TR/uievents/#keyboard-key-codes.
   //
   // 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);
 
   static KeyEvent* last_key_event_;
 };
 
 class EVENTS_EXPORT ScrollEvent : public MouseEvent {
  public:
   explicit ScrollEvent(const base::NativeEvent& native_event);
   template <class T>
@@ skipping 62 matching lines @@
 
   const GestureEventDetails& details() const { return details_; }
 
  private:
   GestureEventDetails details_;
 };
 
 }  // namespace ui
 
 #endif  // UI_EVENTS_EVENT_H_