Revise ui::DomKey to unify character and non-character codes.

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"
 #include "base/gtest_prod_util.h"
 #include "base/logging.h"
 #include "base/memory/scoped_ptr.h"
 #include "base/time/time.h"
 #include "ui/events/event_constants.h"
 #include "ui/events/gesture_event_details.h"
 #include "ui/events/gestures/gesture_types.h"
+#include "ui/events/keycodes/dom/dom_key.h"
 #include "ui/events/keycodes/keyboard_codes.h"
 #include "ui/events/latency_info.h"
 #include "ui/gfx/geometry/point.h"
 #include "ui/gfx/geometry/point_conversions.h"
 
 namespace gfx {
 class Transform;
 }
 
 namespace ui {
 class EventTarget;
 enum class DomCode;
-enum class DomKey;
 
 class EVENTS_EXPORT Event {
  public:
   static scoped_ptr<Event> Clone(const Event& event);
 
   virtual ~Event();
 
   class DispatcherApi {
    public:
     explicit DispatcherApi(Event* event) : event_(event) {}
@@ skipping 550 matching lines @@
   virtual ~ExtendedKeyEventData() {}
 
   virtual ExtendedKeyEventData* Clone() const = 0;
 };
 
 // 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.
-// -- Event::type() can be any one of ET_KEY_PRESSED, ET_KEY_RELEASED.
-// -- code_ and Event::flags() represent the physical key event.
+// -- |bool is_char_| is false.
+// -- |EventType Event::type()| can be ET_KEY_PRESSED or ET_KEY_RELEASED.
+// -- |DomCode code_| and |int Event::flags()| represent the physical key event.
 //    - code_ is a platform-independent representation of the physical key,
-//      based on DOM KeyboardEvent |code| values. It does not vary depending
-//      on key layout.
+//      based on DOM UI Events KeyboardEvent |code| values. It does not
+//      vary depending on key layout.
+//      http://www.w3.org/TR/DOM-Level-3-Events-code/
 //    - Event::flags() provides the active modifiers for the physical key
 //      press. Its value reflects the state after the event; that is, for
 //      a modifier key, a press includes the corresponding flag and a release
 //      does not.
-// -- key_ and character_ provide the meaning of the key event, in the context
-//    of the active layout and modifiers. Together they correspond to DOM
-//    KeyboardEvent |key| values.
-//    - key_ is an enumeration of non-Unicode meanings, plus sentinels
-//      (specifically DomKey::CHARACTER for Unicode meanings).
-//    - character_ is the code point for Unicode meanings.
-// -- key_code_ is a KeyboardCode value associated with the key. This supports
-//    the legacy web event |keyCode| field, and the VKEY_ values are chosen
-//    to match Windows/IE for compatibility. For printable characters, this
-//    may or may not be a layout-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. The stored
-//    key_code_ is non-located (e.g. VKEY_SHIFT rather than VKEY_LSHIFT,
-//    VKEY_1 rather than VKEY_NUMPAD1).
+// -- |DomKey key_| provides the meaning (character or action) of the key
+//    event, in the context of the active layout and modifiers. It corresponds
+//    to DOM UI Events KeyboardEvent |key| values.
+//    http://www.w3.org/TR/DOM-Level-3-Events-key/
+// -- |KeyboardCode key_code_| supports the legacy web event |keyCode| field,
+//    and its VKEY_ values are chosen to match Windows/IE for compatibility.
+//    For printable characters, this may or may not be a layout-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. The stored key_code_ is non-located (e.g. VKEY_SHIFT rather than
+//    VKEY_LSHIFT, VKEY_1 rather than VKEY_NUMPAD1).
 //
 // For a character event,
-// -- is_char_ is true.
-// -- type() is ET_KEY_PRESSED.
-// -- code_ is DomCode::NONE.
-// -- key_ is DomKey::CHARACTER and character_ is a UTF-16 code point.
-// -- key_code_ is conflated with character_ by some code, because both
-//    arrive in the wParam field of a Windows event.
+// -- |bool is_char_| is true.
+// -- |EventType Event::type()| is ET_KEY_PRESSED.
+// -- |DomCode code_| is DomCode::NONE.
+// -- |DomKey key_| is a UTF-16 code point.
+// -- |KeyboardCode key_code_| is conflated with the character-valued key_
+//    by some code, because both arrive in the wParam field of a Windows event.
 //
 class EVENTS_EXPORT KeyEvent : public Event {
  public:
   // 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);
 
-  // Create a keystroke event.
+  // Create a keystroke event from a legacy KeyboardCode.
+  // This should not be used in new code.
   KeyEvent(EventType type, KeyboardCode key_code, int flags);
 
   // Create a fully defined keystroke event.
   KeyEvent(EventType type,
            KeyboardCode key_code,
            DomCode code,
            int flags,
            DomKey key,
-           base::char16 character,
            base::TimeDelta time_stamp);
 
   // 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/dom/dom_values.txt
   KeyEvent(EventType type,
            KeyboardCode key_code,
            DomCode code,
@@ skipping 13 matching lines @@
   // resulting data when read across IPC boundaries.
   void SetExtendedKeyEventData(scoped_ptr<ExtendedKeyEventData> data);
   const ExtendedKeyEventData* extended_key_event_data() const {
     return extended_key_event_data_.get();
   }
 
   // This bypasses the normal mapping from keystroke events to characters,
   // which 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(base::char16 character) { character_ = character; }
+  void set_character(base::char16 character) { key_ = character; }
 
   // Gets the character generated by this key event. It only supports Unicode
   // BMP characters.
   base::char16 GetCharacter() const;
 
   // If this is a keystroke event with key_code_ VKEY_RETURN, returns '\r';
   // otherwise returns the same as GetCharacter().
   base::char16 GetUnmodifiedText() const;
 
   // If the Control key is down in the event, returns a layout-independent
   // character (corresponding to US layout); otherwise returns the same
   // as GetUnmodifiedText().
   base::char16 GetText() const;
 
   // Gets the platform key code. For XKB, this is the xksym value.
+  // This should not be used in new code.
   void set_platform_keycode(uint32 keycode) { platform_keycode_ = keycode; }
   uint32 platform_keycode() const { return platform_keycode_; }
 
   // Gets the associated (Windows-based) KeyboardCode for this key event.
   // Historically, this has also been used to obtain the character associated
   // with a character event, because both use the Window message 'wParam' field.
   // This should be avoided; if necessary for backwards compatibility, use
   // GetConflatedWindowsKeyCode().
   KeyboardCode key_code() const { return key_code_; }
 
@@ skipping 30 matching lines @@
   // (Native X11 event flags describe the state before the event.)
   void NormalizeFlags();
 
  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:
-  // Determine key_ and character_ on a keystroke event from code_ and flags().
+  // Determine key_ on a keystroke event from code_ and flags().
   void ApplyLayout() const;
 
   KeyboardCode key_code_;
 
   // DOM KeyboardEvent |code| (e.g. DomCode::KEY_A, DomCode::SPACE).
   // http://www.w3.org/TR/DOM-Level-3-Events-code/
   //
   // This value represents the physical position in the keyboard and can be
   // converted from / to keyboard scan code like XKB.
   DomCode code_;
 
   // 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.
   mutable uint32 platform_keycode_;
 
-  // TODO(kpschoedel): refactor so that key_ and character_ are not mutable.
+  // TODO(kpschoedel): refactor so that key_ is not mutable.
   // This requires defining the KeyEvent completely at construction rather
   // than lazily under GetCharacter(), which likely also means removing
   // the two 'incomplete' constructors. crbug.com/444045
   //
   // DOM KeyboardEvent |key|
   // http://www.w3.org/TR/DOM-Level-3-Events-key/
   //
-  // This value, together with character_, represents the meaning of a key.
-  // The value is DomKey::CHARACTER when the interpretation is a character.
-  // This, along with character_, is not necessarily initialized when the
-  // event is constructed; it may be set only if and when GetCharacter()
-  // or GetDomKey() is called.
+  // This value represents the meaning of a key, which is either a Unicode
+  // character, or a named DomKey:: value.
+  // This is not necessarily initialized when the event is constructed;
+  // it may be set only if and when GetCharacter() or GetDomKey() is called.
   mutable DomKey key_;

[kpschoedel, 2015/08/07 20:42:12]

|key_| now subsumes |character_|.

[Wez, 2015/08/26 23:38:33]

*celebratory dance*

 
-  // 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'.
-  mutable base::char16 character_;
-
   // Parts of our event handling require raw native events (see both the
   // windows and linux implementations of web_input_event in content/). Because
   // mojo instead serializes and deserializes events in potentially different
   // processes, we need to have a mechanism to keep track of this data.
   scoped_ptr<ExtendedKeyEventData> extended_key_event_data_;
 
   static bool IsRepeated(const KeyEvent& event);
 
   static KeyEvent* last_key_event_;
 };
@@ skipping 67 matching lines @@
 
   const GestureEventDetails& details() const { return details_; }
 
  private:
   GestureEventDetails details_;
 };
 
 }  // namespace ui
 
 #endif  // UI_EVENTS_EVENT_H_