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

ui/events/keycodes/keyboard_code_conversion.h

 // Copyright (c) 2011 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_KEYCODES_KEYBOARD_CODE_CONVERSION_H_
 #define UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_
 
 #include "base/strings/string16.h"
 #include "ui/events/events_base_export.h"
 #include "ui/events/keycodes/keyboard_codes.h"
@@ skipping 10 matching lines @@
 // 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.

[Wez, 2015/01/17 02:06:47]

nit: Skimming this comment block, it's not clear to me exactly how it relates to
the functions below. e.g. this mention of "a special native event object"
doesn't seem to tie up with anything below?

[kpschoedel, 2015/02/18 17:14:01]

That dates to the original implementation of GetCharacterFromKeyCode(), and my
interpretation of the comment is that is was intended to create fake
platform-native events if necessary to support events where the character did
not correspond to the VKEY in US layout.

I've revised the comment for now, though it will go away along with the
functions.

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

Acknowledged.

 // 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).

[kpschoedel, 2015/01/14 21:00:32]

A subsequent CL will remove the Get…FromKeyCode() functions.

(Aside: historically there's a mix of FooToBar() and GetBarFromFoo() names for
conversions; in these changes I'm trying to use FooToBar() consistently for
mappings and reserve GetX() for object getters.)

DomCodeToMeaning() replaces Get…FromKeyCode() and the other functions below are
used both by it and by Ozone layout.

[Wez, 2015/01/17 02:06:47]

+1 to the FooToBar() function names. :)

 EVENTS_BASE_EXPORT base::char16 GetCharacterFromKeyCode(KeyboardCode key_code,
                                                         int flags);
 EVENTS_BASE_EXPORT bool GetMeaningFromKeyCode(KeyboardCode key_code,

[Wez, 2015/01/17 02:06:48]

Suggest adding a comment to this w/ TODO(...) and referring to the bug # for the
remaining cleanup work that will remove this.

[kpschoedel, 2015/02/18 17:14:01]

Done.

                                               int flags,
                                               DomKey* dom_key,
                                               base::char16* character);
+EVENTS_BASE_EXPORT bool DomCodeToMeaning(DomCode dom_code,
+                                         int flags,
+                                         DomKey* dom_key,
+                                         base::char16* character,
+                                         KeyboardCode* key_code);

[Wez, 2015/01/17 02:06:47]

Provide a brief comment documenting the in & out parameters?

[kpschoedel, 2015/02/18 17:14:01]

Done.

+
+// Obtains the control character corresponding to a physical key.

[Wez, 2015/01/17 02:06:48]

Need to clarify what you mean by "control character"; are you saying that this
function returns the ASCII control code that the physical key would generate if
Control is pressed, or something else?

[kpschoedel, 2015/02/18 17:14:01]

Yes, see below.

+// In some contexts this is used instead of the key layout.

[Wez, 2015/01/17 02:06:48]

Why? What is the layout that this function applies? e.g. if my keyboard is set
for Hebrew then does Control+<character key> get mapped to a control code as
though the layout were US English? Or does the mapping fail, or something else?

[kpschoedel, 2015/02/18 17:14:01]

As far as I can tell from searching commits, this was added several years ago to
support the field blink::WebKeyboardEvent::text, whose comment sheds no light on
the matter. 
I not entirely sure of the original intent, but I assume it's related to
Windows-style shortcuts (i.e. what's the paste shortcut on a Hebrew keyboard?)
with a dash of Windows-style confusion between shortcuts and ASCII control
codes. To me this makes some sense for non-Latin layouts but none at all for
AZERTY/QWERTZ/Dvorak/etc., but I'm aiming not to change any existing behaviour
in this CL — issues 444045 and 444048 are meant to make the relatively sane DOM
3 |code| and |key| the source of truth in ui::KeyEvent so that reasonable
behaviour can be built on top.

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

:(  That sounds like something Gary may know more about.
OK, SGTM

+// Returns true and sets the output parameters if the (dom_code, flags) pair
+// is interpreted as a control character.

[Wez, 2015/01/17 02:06:48]

So this parameter _only_ succeeds if the supplied dom_code and flags would
result in an ASCII control code?

[kpschoedel, 2015/02/18 17:14:01]

Yes, commented.

+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).
+EVENTS_BASE_EXPORT KeyboardCode DomCodeToKeyboardCode(DomCode dom_code);

[Wez, 2015/01/17 02:06:48]

How does this behave for Numeric Keypad keys, which are non-printable if NumLock
is off, and printable otherwise?

How is this function intended to work if e.g. the user has configured their
Linux or ChromeOS device to swap Control and CapsLock?

[kpschoedel, 2015/02/18 17:14:01]

Does the modified comment help?

This is currently used as a last resort by XKB layout if other methods of
determining a suitable VKEY fail.

+
+// Returns the Windows-based VKEY value corresponding to a DOM Level 3 |code|.
+// The returned VKEY is non-located (e.g. VKEY_SHIFT).
+EVENTS_BASE_EXPORT KeyboardCode
+DomCodeToNonLocatedKeyboardCode(DomCode dom_code);

[Wez, 2015/01/17 02:06:47]

nit: Do you need this or could you just let the caller pass the VKEY on to the
LocatedToNonLocated helper function?

If you're returning a non-located code, is it helpful to also (optionally?)
return the location separately?

[kpschoedel, 2015/02/18 17:14:01]

Right, removed this.

 
 // 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
 // physical keys, and non-located (e.g. VKEY_SHIFT) that identify
 // only the operation.
 EVENTS_BASE_EXPORT KeyboardCode
 LocatedToNonLocatedKeyboardCode(KeyboardCode key_code);
 
 // Determine the located VKEY corresponding to a non-located VKEY.
 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.

[Wez, 2015/01/17 02:06:48]

Do you mean "when a key event has no |code| value associated with it, e.g. if it
was generated synthetically by JavaScript, with only a VKEY value supplied"?

[kpschoedel, 2015/02/18 17:14:01]

At the moment this is used for the old constructor KeyEvent(EventType,
KeyboardCode, flags) to remove some dependence on the VKEY later in the code.
Most uses of that are in tests (where it will be possible to supply the DomCode
directly) and I haven't yet isolated the other uses.

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

OK, cool. Would it cause a lot of churn to rename to include "UsLayout" in the
name?

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

Done.

+EVENTS_BASE_EXPORT DomCode KeyboardCodeToDomCode(KeyboardCode key_code);
+
 }  // namespace ui
 
 #endif  // UI_EVENTS_KEYCODES_KEYBOARD_CODE_CONVERSION_H_