You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Feb 22, 2023. It is now read-only.
Copy file name to clipboardExpand all lines: dev/tools/gen_keycodes/README.md
+37-39Lines changed: 37 additions & 39 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,15 +3,16 @@
3
3
This directory contains a keycode generator that can generate Dart code for
4
4
the `LogicalKeyboardKey` and `PhysicalKeyboardKey` classes.
5
5
6
-
It generates multiple files across Flutter. For framework, it generates
6
+
It generates multiple files across Flutter. For framework, it generates
7
7
8
8
*[`keyboard_key.dart`](../../../packages/flutter/lib/src/services/keyboard_key.dart), which contains the definition and list of logical keys and physical keys; and
9
9
*[`keyboard_maps.dart`](../../../packages/flutter/lib/src/services/keyboard_maps.dart), which contains platform-specific immutable maps used for the `RawKeyboard` API.
10
10
11
-
For engine, it generates one key mapping file for each platform.
11
+
For engine, it generates one key mapping file for each platform, as well as some
12
+
files for testing purposes.
12
13
13
14
It draws information from various source bases, including online
14
-
repositories, and manual mapping in the `data` subdirectory. It incorporates
15
+
repositories, and manual mapping in the `data` subdirectory. It incorporates
15
16
this information into a giant list of physical keys
@@ -38,46 +39,45 @@ This will generate `physical_key_data.json` and `logical_key_data.json`. These
38
39
files should be checked in.
39
40
40
41
By default this tool assumes that the gclient directory for flutter/engine
41
-
and the root for the flutter/flutter are placed at the same folder. If not,
42
+
and the root for the flutter/flutter are placed at the same folder. If not,
42
43
use `--engine-root=/ENGINE/GCLIENT/ROOT` to specify the engine root.
43
44
44
45
Other options can be found using `--help`.
45
46
46
-
## Logical Key ID Scheme
47
+
## Key ID Scheme
47
48
48
-
To provide logical keys with unique ID codes, Flutter uses a scheme
49
-
to assign logical keycodes which keeps us out of the business of minting new
50
-
codes ourselves. This only applies to logical key codes: Flutter's
51
-
physical key codes are just defined as USB HID codes.
49
+
To provide keys with unique ID codes, Flutter uses a scheme to assign keycodes
50
+
which keeps us out of the business of minting new codes ourselves. This applies
51
+
both logical keys and physical keys.
52
52
53
-
The logical codes are meant to be opaque to the user, and should never be
54
-
unpacked for meaning, since the coding scheme could change at any time and the
55
-
meaning is likely to be retrievable more reliably and correctly from
56
-
the API.
53
+
The codes are meant to be opaque to the user, and should never be unpacked for
54
+
meaning, since the coding scheme could change at any time and the meaning is
55
+
likely to be retrievable more reliably and correctly from the API.
57
56
58
57
However, if you are porting Flutter to a new platform, you should follow the
59
-
following guidelines for specifying logical key codes.
58
+
following guidelines for specifying key codes.
60
59
61
-
The logical key code is a 52-bit integer (due to the limitation of JavaScript).
62
-
The entire namespace is divided into 32-bit *planes*. The upper 20 bits of the
63
-
ID represent the plane ID, while the lower 32 bits represent values in the
64
-
plane. For example, plane 0x1 refers to the range 0x1 0000 0000 -
65
-
0x1 FFFF FFFF. Each plane manages how the values within the range are assigned.
60
+
The key code is a 52-bit integer (due to the limitation of JavaScript). The
61
+
entire namespace is divided into 32-bit *planes*. The upper 20 bits of the ID
62
+
represent the plane ID, while the lower 32 bits represent values in the plane.
63
+
For example, plane 0x1 refers to the range 0x1 0000 0000 - 0x1 FFFF FFFF. Each
64
+
plane manages how the values within the range are assigned.
66
65
67
66
The planes are planned as follows:
68
67
69
-
-**Plane 0x00**: The Unicode plane. This plane contains keys that generate Unicode
70
-
characters when pressed (this includes dead keys, but not e.g. function keys
71
-
or shift keys). The value is defined as the Unicode code point corresponding
72
-
to the character, lower case and without modifier keys if possible.
73
-
Examples are Key A (0x61), Digit 1 (0x31), Colon (0x3A), and Key Ù (0xD9).
74
-
(The "Colon" key represents a keyboard key that prints the ":"
75
-
character without modifiers, which can be found on the French layout. On the
76
-
US layout, the key that prints ":" is the Semicolon key.)
77
-
This plane also contains key None (0x0).
78
-
79
-
-**Plane 0x01**: The unprintable plane. This plane contains keys that are defined
80
-
by the [Chromium key list](https://chromium.googlesource.com/codesearch/chromium/src/+/refs/heads/master/ui/events/keycodes/dom/dom_key_data.inc)
68
+
-**Plane 0x00**: The Unicode plane. For logical keys, this plane contains keys
69
+
that generate Unicode characters when pressed (this includes dead keys, but
70
+
not e.g. function keys or shift keys). The value is defined as the Unicode
71
+
code point corresponding to the character, lower case and without modifier
72
+
keys if possible. Examples are Key A (0x61), Digit 1 (0x31), Colon (0x3A),
73
+
and Key Ù (0xD9). (The "Colon" key represents a keyboard key that prints the
74
+
":" character without modifiers, which can be found on the French layout. On
75
+
the US layout, the key that prints ":" is the Semicolon key.) For physical
76
+
keys, this plane contains keys from USB HID usages.
77
+
78
+
-**Plane 0x01**: The unprintable plane. This plane contains logical keys that
0 commit comments