Use DOM- rather than Windows-based key code for non-layout cases.

ui/events/keycodes/keyboard_code_conversion.h

Index: ui/events/keycodes/keyboard_code_conversion.h
diff --git a/ui/events/keycodes/keyboard_code_conversion.h b/ui/events/keycodes/keyboard_code_conversion.h
index 0c14ed74cee248798e11f3abfeb90cc9251c1548..f962a3f8b60a0f099c30c6449b6ff1dd7a448216 100644
--- a/ui/events/keycodes/keyboard_code_conversion.h
+++ b/ui/events/keycodes/keyboard_code_conversion.h
@@ -18,22 +18,20 @@ enum class DomKey;
 // platform independent way. It supports control characters as well.
 // It assumes a US keyboard layout is used, so it may only be used when there
 // is no native event or no better way to get the character.
+//
 // For example, if a virtual keyboard implementation can only generate key
 // events with key_code and flags information, then there is no way for us to
 // determine the actual character that should be generate by the key. Because
 // a key_code only represents a physical key on the keyboard, it has nothing
 // to do with the actual character printed on that key. In such case, the only
 // thing we can do is to assume that we are using a US keyboard and get the
-// character according to US keyboard layout definition.
-// If a virtual keyboard implementation wants to support other keyboard
-// layouts, that may generate different text for a certain key than on a US
-// keyboard, a special native event object should be introduced to carry extra
-// information to help determine the correct character.
-// Take XKeyEvent as an example, it contains not only keycode and modifier
-// flags but also group and other extra XKB information to help determine the
-// correct character. That's why we can use XLookupString() function to get
-// the correct text generated by a X key event (See how is GetCharacter()
-// implemented in event_x.cc).
+// character according to US keyboard layout definition. Preferably, such
+// events should be created using a full KeyEvent constructor, explicitly
+// specifying the character and DOM 3 values as well as the legacy VKEY.
+//
+// TODO(kpschoedel): replace remaining uses of the ...FromKeyCode() functions
+// and remove them, to avoid future creation of underspecified key events.
+// crbug.com/444045
 EVENTS_BASE_EXPORT base::char16 GetCharacterFromKeyCode(KeyboardCode key_code,
                                                         int flags);
 EVENTS_BASE_EXPORT bool GetMeaningFromKeyCode(KeyboardCode key_code,
@@ -41,6 +39,44 @@ EVENTS_BASE_EXPORT bool GetMeaningFromKeyCode(KeyboardCode key_code,
                                               DomKey* dom_key,
                                               base::char16* character);
 
+// Helper function to map a physical key state (dom_code and flags)
+// to a meaning (dom_key and character, together corresponding to the
+// DOM keyboard event |key| value), along with a corresponding Windows-based
+// key_code.
+//
+// This follows a US keyboard layout, so it should only be used when there
+// is other better way to obtain the meaning (e.g. actual keyboard layout).

[Wez, 2015/02/19 23:16:08]

Do you mean where there *isn't* a better way?

Suggest including "UsLayout" in the name so that it's clear this shouldn't
generally be used.

[kpschoedel, 2015/04/10 18:32:34]

Done.

+EVENTS_BASE_EXPORT bool DomCodeToMeaning(DomCode dom_code,
+                                         int flags,
+                                         DomKey* dom_key,
+                                         base::char16* character,
+                                         KeyboardCode* key_code);
+
+// Obtains the control character corresponding to a physical key;
+// that is, the meaning of the physical key state (dom_code, and flags
+// containing EF_CONTROL_DOWN) under a specific US ASCII layout.

[Wez, 2015/02/19 23:16:08]

You mean under _the_ US English layout?

[kpschoedel, 2015/04/10 18:32:34]

Done.

+// Returns true and sets the output parameters if the (dom_code, flags) pair
+// is interpreted as a control character; otherwise the output parameters
+// are untouched.
+EVENTS_BASE_EXPORT bool DomCodeToControlCharacter(
+    DomCode dom_code,
+    int flags,
+    DomKey* dom_key,
+    base::char16* character,
+    KeyboardCode* key_code);
+
+// Returns a Windows-based VKEY for a non-printable DOM Level 3 |key|.
+// The returned VKEY is non-located (e.g. VKEY_SHIFT).
+EVENTS_BASE_EXPORT KeyboardCode
+NonPrintableDomKeyToKeyboardCode(DomKey dom_key);
+
+// Returns the Windows-based VKEY value corresponding to a DOM Level 3 |code|.
+// The returned VKEY is located (e.g. VKEY_LSHIFT) and considered as a
+// layout-independent physical key (e.g. DomCode::KEY_Q -> VKEY_Q). This

[Wez, 2015/02/19 23:16:08]

Rather than layout independent, you're really saying it's hard-wire for US
English again, aren't you?

[kpschoedel, 2015/04/10 18:32:34]

The intent was that the VKEY here is used purely to label a physical key, so
it's US layout in the same sense that DOM3 code 'KeyA' or USB 07:0004 being
called 'Keyboard a and A' is US layout.

However, after looking at the remaining uses in this refactoring, I think it's
better to eliminate this function entirely.

+// should only be used as a last resort when other means of determining a
+// suitable VKEY fail.
+EVENTS_BASE_EXPORT KeyboardCode DomCodeToKeyboardCode(DomCode dom_code);
+
 // Determine the non-located VKEY corresponding to a located VKEY.
 // Most modifier keys have two kinds of KeyboardCode: located (e.g.
 // VKEY_LSHIFT and VKEY_RSHIFT), that indentify one of two specific
@@ -53,6 +89,12 @@ LocatedToNonLocatedKeyboardCode(KeyboardCode key_code);
 EVENTS_BASE_EXPORT KeyboardCode
 NonLocatedToLocatedKeyboardCode(KeyboardCode key_code, DomCode dom_code);
 
+// Returns a DOM Level 3 |code| from a Windows-based VKEY value.
+// This assumes a US layout and should only be used when |code| cannot be
+// determined from a physical scan code, for example when a key event was
+// generated synthetically by JavaScript with only a VKEY value supplied.
+EVENTS_BASE_EXPORT DomCode KeyboardCodeToDomCode(KeyboardCode key_code);
+
 }  // namespace ui
 
 #endif  // UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_