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

ui/events/keycodes/dom/dom_key.h

 // Copyright 2014 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_DOM3_DOM_KEY_H_
 #define UI_EVENTS_KEYCODES_DOM3_DOM_KEY_H_
 
+#include <stdint.h>
+
 namespace ui {
 

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

Main change here.

+// Integer representation of UI Events KeyboardEvent.key value.
+//
+// The semantics follow the web string form[1]: the value is either a
+// Unicode character or one of a defined set of additional values[2].
+// In this integer form, a printable character is represented by
+// the Unicode code point directly, and a non-Unicode key is represented
+// by a named constant in the DomKey:: scope. This allows DomKey to be
+// used as a proper superset of a Unicode character type.
+//
+// There is one notable difference from the UI Events string key: for
+// the 'Dead' key, this type provides a whole range of values that also
+// encode the associated combining character. This allows the interpretation
+// of any keystroke to be carried as a single integer value.

[Wez, 2015/08/13 22:31:48]

Why aren't dead-keys encoded using the corresponding Unicode combining
characters?

[kpschoedel, 2015/08/14 01:20:07]

The main reason is that they're actually two distinct things. In current
practice a dead key is a non-printable operator key, represented by UI Events
key 'Dead', that combines with a following key to produce a different character;
the combinations are specific and predetermined (on X11 and descendants by
lookup tables, but on the Mac by keyboard layout state transitions) and
arbitrary, not necessarily preserving the identity of the components (e.g. on
ChromeOS, per some long-ago issue, looking up <dead-acute> + <c> yields <ç>
rather than <ć>).

A combining character, on the other hand, is a Unicode character in its own
right, represented in UI Events key by itself (per _key Values_ §1 “support for
the full range of Unicode codepoints”), that decorates a *preceding* character
(in any combination, as shown by ‘Zalgo’ text), with both retaining their
identity — U+0063 LATIN SMALL LETTER C followed by U+0301 COMBINING ACUTE ACCENT
is inherently <ć>. There *are* keyboard layouts that produce actual combining
characters rather than using dead keys (e.g. Bulgarian).

The secondary reason (just to share the misery) is that there exist dead keys
that don't in any sense correspond to a Unicode combining character. The French
Bépo layout has a <dead_currency> key such that (for example) <dead_currency> +
<c> ↦ <¢>, <dead_currency> + <l> ↦ <£>, etc, and a <dead_greek> such that
<dead_greek> + <a> ↦ <α> etc. ChromeOS doesn't currently have these in the dead
key table, but really only because our table derives from an outdated GTK and no
one's ever complained.

[Wez, 2015/08/18 22:34:32]

Oh, interesting; I wonder what Chrome does with those keys right now..?
I was thinking of suggesting we ignore the Unicode post-combination and (ab)use
the combining code points as pre-combining dead-keys, but it sounds like there's
enough differences to warrant the separate scheme. Sad. :(

+//
+// DomKey::NONE is a sentinel used to indicate an error or undefined value.
+// It is not the same as Unicode code point 0 (ASCII NUL) or the valid DOM
+// key 'Unidentified'.
+//
+// References:
+// [1] http://www.w3.org/TR/uievents/#widl-KeyboardEvent-key
+// [2] http://www.w3.org/TR/DOM-Level-3-Events-key/
+//
+class DomKey {
+ public:
+  using Base = int32_t;

[dtapuska, 2015/08/13 14:47:26]

Any specific reason we'd use int32_t here? As opposed to uint32_t?

[kpschoedel, 2015/08/13 15:46:06]

In isolation I'd use uint32_t, but Blink currently uses 'int', and
signed/unsigned interactions can bite; also the style guide frowns somewhat on
unsigned ints. If we had a base::char32 I'd use that type.

[Wez, 2015/08/13 22:31:48]

Agreed; the Unicode range only extends to 0x10ffff, so we can fit comfortably in
the 31-bit range and avoid nasty signed/unsigned interactions. We could even
make non-printable DomKey values live in the -ve space if we felt crafty (and
confident that nothing anywhere assumes they're unsigned... ;)

+
+ private:
+  // Integer representation of DomKey. This is arranged so that Unicode values
+  // are directly usable as DomKey values, and DomKey values are either Unicode
+  // code points or outside the range of Unicode code points.
+  //
+  // 31             24              16              8               0
+  // |       |       |       |       |       |       |       |       |
+  // | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
+  // |        z        | t |                    v                    |
+  //
+  //  - z is reserved and 0 for any valid DomKey.
+  //  - t distinguish the type of DomKey:
+  //    0 for a Unicode code point;
+  //    1 for a dead key;
+  //    2 for any other symbolic DomKey.
+  //  - v is a value whose interpretation depends on t:
+  //    - for a Unicode value, it is the code point;
+  //    - for a dead key, the code point of the associated combining character;

[Wez, 2015/08/13 22:31:48]

See above re using the Unicode combining character code-points.

+  //    - for others, an arbitrary distinct value.
+  enum { VALUE_BITS = 21, TYPE_BITS = 2 };
+  enum Type : Base {
+    VALUE_MASK = (1L << VALUE_BITS) - 1,
+    TYPE_MASK = ((1L << TYPE_BITS) - 1) << VALUE_BITS,
+    TYPE_UNICODE = (0 << VALUE_BITS),
+    TYPE_DEAD = (1 << VALUE_BITS),
+    TYPE_NON_UNICODE = (2 << VALUE_BITS),
+    VALID_MASK = VALUE_MASK | TYPE_MASK,
+  };
+
+ public:
+  enum InvalidKey : Base { NONE = -1 };
+#define DOM_KEY_MAP_DECLARATION enum Key : Base

[Wez, 2015/08/13 22:31:48]

nit: Introduce this macro block with a comment to explain we're pulling in the
non-printable DomKey constants so they'll have names under DomKey?

[kpschoedel, 2015/08/17 20:16:14]

Done.

+#define DOM_KEY_UNI(key, id, value) id = (TYPE_UNICODE | (value))
+#define DOM_KEY_MAP_BEGIN FIRST_NON_UNICODE = TYPE_NON_UNICODE,
 #define DOM_KEY_MAP(key, id) id
-#define DOM_KEY_MAP_DECLARATION enum class DomKey
+#define DOM_KEY_MAP_END LAST_NON_UNICODE
 #include "ui/events/keycodes/dom/dom_key_data.inc"
+#undef DOM_KEY_MAP_DECLARATION
+#undef DOM_KEY_MAP_BEGIN
 #undef DOM_KEY_MAP
-#undef DOM_KEY_MAP_DECLARATION
+#undef DOM_KEY_MAP_END
+#undef DOM_KEY_UNI
+
+  // Create a DomKey, with the undefined-value sentinal DomKey::NONE.

[Wez, 2015/08/13 22:31:48]

nit: sentinel

[kpschoedel, 2015/08/17 20:16:14]

Ouch. I can spell, but my fingers can't.

+  DomKey() : value_(NONE) {}
+
+  // Create a DomKey from an integer value. This is not |explicit|, so that
+  // Unicode characters and DomKey:: constants can be used directly.
+  DomKey(Base value) : value_(value) {}

[dtapuska, 2015/08/13 14:47:26]

I do find this sneaky; in that character -> DomKey assignment assumes
TYPE_UNICODE == 0; and that there really is no static assertion anywhere that
indicates that is a requirement.

[kpschoedel, 2015/08/13 15:46:06]

Will add static assertions as necessary for the final representation.

+
+  // Obtain the integer representation of the DomKey.
+  operator Base() const { return value_; }
+
+  // True if the value is a valid DomKey (which excludes DomKey::NONE and
+  // integers not following the DomKey format).
+  bool IsValid() const { return (value_ & ~(TYPE_MASK | VALUE_MASK)) == 0; }
+
+  // True if the value is a Unicode code point.
+  bool IsUnicode() const { return (value_ & TYPE_MASK) == TYPE_UNICODE; }
+
+  // True if the value is a dead key.
+  bool IsDead() const { return (value_ & TYPE_MASK) == TYPE_DEAD; }
+
+  // Returns the Unicode code point for either a Unicode key or a dead key.
+  // (The return value for other keys is meaningless and not comparable to
+  // a DomKey:: constant.)
+  int32_t GetCodePoint() const { return value_ & VALUE_MASK; }
+
+  // Returns a dead-key DomKey for the given combining character.
+  static DomKey Dead(int32_t combining_character) {
+    return TYPE_DEAD | combining_character;
+  }
+
+ private:
+  Base value_;
+};
 
 }  // namespace ui
 
 #endif  // UI_EVENTS_KEYCODES_DOM3_DOM_KEY_H_