Ozone keyboard layout

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/keyboard_codes.h"
 #include "ui/events/latency_info.h"
 #include "ui/gfx/point.h"
 #include "ui/gfx/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 526 matching lines @@
 
   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.
-// -- type() can be any one of ET_KEY_PRESSED, ET_KEY_RELEASED,
+// -- Event::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().
+// -- code_ and 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.
+//    - 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. Together they

[Wez, 2014/12/12 20:04:18]

nit: suggest "in the context of the active layout and modifiers"?

[kpschoedel, 2014/12/12 21:20:39]

Done.

+//    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 VKEY_ value associated with the key. For printable

[Wez, 2014/12/12 20:04:18]

nit: Worth mentioning that this supports the legacy keyCode field, with values
chosen to match Windows/IE for compatibility?

 //    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.
+// -- code_ is DomCode::NONE.
+// -- key_ is DomKey::CHARACTER and character_ is a UTF-16 code point.

[Wez, 2014/12/12 20:04:18]

Setting |key_| for character events feels wrong, even though it makes no real
difference.

[kpschoedel, 2014/12/12 21:20:39]

The reason for doing so here is that some event-consuming code is vague about
keystroke vs character events, so I want to avoid risk from something operating
on a character event as if it were a keystroke event, by giving them the same
(key, character) pair. Ideally having the cleaner platform-independent DOM Level
3 model here in KeyEvent will encourage other code to move away from the Windows
conflated model.

 // -- key_code_ is conflated with character_ by some code, because both
 //    arrive in the wParam field of a Windows event.
-// -- code_ is DomCode::NONE.
 //
 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.
   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);
+
   // 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/dom3/dom_values.txt
   KeyEvent(EventType type,
            KeyboardCode key_code,
            DomCode code,
            int flags);
 
@@ skipping 63 matching lines @@
   uint16 GetConflatedWindowsKeyCode() const;
 
   // 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;
 
   // Returns the DOM .code (physical key identifier) for a keystroke event.
   DomCode code() const { return code_; };
   std::string GetCodeString() const;
 
+  // Returns the DOM .key (layout meaning) for a keystroke event.
+  DomKey GetDomKey() const;
+
   // 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:
   // True if the key press originated from a 'right' key (VKEY_RSHIFT, etc.).
   bool IsRightSideKey() const;
 
+  // Determine key_ and character_ 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.
   uint32 platform_keycode_;
 
+  // TODO(kpschoedel): refactor so that key_ and character_ are not mutable.
+  // This requires defining the KeyEvent completely at construction rather
+  // than lazily under GetCharacter(), which likely also means removing
+  // the two 'incomplete' constructors.
+  //
+  // 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.
+  mutable DomKey key_;
+
   // 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
@@ skipping 75 matching lines @@
 
   const GestureEventDetails& details() const { return details_; }
 
  private:
   GestureEventDetails details_;
 };
 
 }  // namespace ui
 
 #endif  // UI_EVENTS_EVENT_H_