This directory contains a keycode generator that can generate Dart code for the LogicalKeyboardKey and PhysicalKeyboardKey classes. It draws information from both the Chromium and Android source bases and incorporates the information it finds in those sources into a single key database in JSON form.
It then generates keyboard_key.dart (containing the LogicalKeyboardKey and PhysicalKeyboardKey classes), and keyboard_maps.dart, containing platform-specific immutable maps for translating platform keycodes and information into the pre-defined key values in the LogicalKeyboardKey and PhysicalKeyboardKey classes.
The data subdirectory contains both some local data files and the templates used to generate the source files.
data/key_data.json: contains the merged data from all the other sources. This file will be regenerated if “--collect” is specified for the gen_keycodes script.data/key_name_to_android_name.json: contains a mapping from Flutter key names to Android keycode names (with the “KEY_” prefix stripped off).data/keyboard_key.tmpl: contains the template for the keyboard_key.dart file. Markers that begin and end with “@@@” denote the locations where generated data will be inserted.data/keyboard_maps.tmpl: contains the template for the keyboard_maps.dart file. Markers that begin and end with “@@@” denote the locations where generated data will be inserted.data/printable.json: contains a mapping between Flutter key name and its printable character. This character is used as the key label.data/synonyms.json: contains a mapping between pseudo-keys that represent other keys and the sets of keys they represent. For example, this contains the “shift” key that represents either a “shiftLeft” or “shiftRight” key.To run the gen_keycodes tool using the checked in key_data.json file, run it like so:
$FLUTTER_ROOT/bin/cache/dart-sdk/bin/dart bin/gen_keycodes.dart
This will regenerate the keyboard_key.dart and keyboard_maps.dart files in place.
If you wish to incorporate and parse changes from the Chromium and Android source trees, add --collect to the command line. The script will download and incorporate the changed data automatically. Note that the parsing is specific to the format of the source code that it is reading, so if the format of those files changes appreciably, you will need to update the parser.
There are other options for manually specifying the file to read in place of the downloaded files, use --help to see what is available.
If the data in those files changes in the future to be unhelpful, then we can switch to another data source, or abandon the parsing and maintain key_data.json manually. All output files and local input files should be checked in.
To provide logical keys with unique ID codes, Flutter uses a scheme to assign logical keycodes which keeps us out of the business of minting new codes ourselves. This only applies to logical key codes: Flutter's physical key codes are just defined as USB HID codes.
The logical codes are meant to be opaque to the user, and should never be unpacked for meaning, since the coding scheme could change at any time and the meaning is likely to be retrievable more reliably and correctly from the API.
However, if you are porting Flutter to a new platform, you should follow the following guidelines for specifying logical key codes.
The logical key code is a 37-bit integer in a namespace that we control and define. It has values in the following ranges.
0x00 0000 0000 - 0x0 0010 FFFF: For keys that generate Unicode characters when pressed (this includes dead keys, but not e.g. function keys or shift keys), the logical key code is the Unicode code point corresponding to the representation of the key in the current keyboard mapping. The Unicode code point might not match the string that is generated for an unshifted keypress of that key, for example, we would use U+0034 for the “4 $” key in the US layout, and also the “4 ;” key in the Russian layout, and also, maybe less intuitively, for the “' 4 {“ in French layout (wherein the latter case, an unshifted press gets you a ', not a 4). Similarly, the Q key in the US layout outputs a q in normal usage, but its code would be 0x0 0000 0051 (U+00051 being the code for the uppercase Q).
0x01 0000 0000 - 0x01 FFFF FFFF: For keys that are defined by the USB HID standard, the key code consists of the 32 bit USB extended usage code. For example, the Enter key would have code 0x01 0007 0028. Only keys that fall into collections “Keyboard”, “Keypad”, and “Tablet PC System Controls” are considered for this API; for example, a mixing desk with multiple collections of volume controls would not be exposed via DOWN and UP events, nor would a mouse, joystick, or golf simulator control.
0x02 0000 0000 - 0xFF FFFF FFFF: For keys that aren't defined in USB at the time of implementation, but that we need to support. For example, if Flutter were ever ported to the Symbolics LM-2, the “thumb up” key might be given the code 0x14 0000 0001, where 0x14 is defined as the “Symbolics” platform range. Where possible, we will use specific subranges of this space to reuse keys from other platforms. When this is not possible, the prefix 0xFF is reserved for “Custom” codes. Each platform from which we take codes will get a unique prefix in the range 0x2-0xFE. If multiple systems define keys with the same usage (not the same number), then the value with the lowest prefix is used as the defining code.
Prefixes will be:
| Code | Platform |
|---|---|
| 0x02 | Android |
| 0x03 | Fuchsia |
| 0x04 | iOS |
| 0x05 | macOS |
| 0x06 | Linux |
| 0x07 | Windows |
| 0x08 | Web |
| 0xFF | Custom |
Further ranges will be added as platforms are added. The platform prefix does not define the platform it is used on, it is just the platform that decides what the value is: the codes are mapped to the same value on all platforms.
0x100 0000 0000 - 0x1FF FFFF FFFF: For keys that have no definition yet in Flutter, but that are encountered in the field, this range is used to embed the platform-specific keycode in an ID that must be tested for in a platform-specific way. For instance, if a platform generates a new USB HID code 0x07 00E8 that a Flutter app wasn’t compiled with, then it would appear in the app as 0x100 0007 00E8, and the app could test against that code. Yes, this also means that once they recompile with a version of Flutter that supports this new HID code, apps looking for this code will break. This situation is only meant to provide a fallback ability for apps to handle esoteric codes that their version of Flutter doesn’t support yet. The prefix for this code is the platform prefix from the previous sections, plus 0x100.
0x200 0000 0000 - 0x2FF FFFF FFFF: For pseudo-keys which represent combinations of other keys, and conceptual keys which don't have a physical representation. This is where things like key synonyms are defined (e.g. “shiftLeft” is a synonym for “shift”: the “shift” key is a pseudo-key representing either the left or right shift key).
This is intended to get us out of the business of defining key codes where possible. We still have to have mapping tables, but at least the actual minting of codes is deferred to other organizations to a large extent. Coming up with a code is a mechanical process consisting of just picking the lowest number code possible that matches the semantic meaning of the key according to the definitions above.
Here are some examples:
For example, on a French keyboard layout, pressing CAPS LOCK then pressing SHIFT + Y would generate the following sequence:
DOWN, code 0x0100070039. (CAPS LOCK DOWN)
UP, code 0x0100070039. (CAPS LOCK UP)
DOWN, code 0x01000700E1 (LEFT SHIFT DOWN)
DOWN, code 0x0000000059, string U+00059 (Y DOWN)
UP, code 0x0000000059 (Y UP)
UP, code 0x01000700E1 (LEFT SHIFT UP)
Here's another example. On a German keyboard layout, you press ^e (the ^ key is at the top left of the keyboard and is a dead key) to produce an “ê”:
DOWN, code 0x0000000302 (CIRCUMFLEX DOWN) It produces no string, because it's a dead key. The key code is for “Combining circumflex accent U+0302” in Unicode.
UP, code 0x0000000302 (CIRCUMFLEX UP)
DOWN, code 0x0000000065, string U+000EA (Unicode for ê) (E DOWN).
UP, code 0x0000000065. (E UP).
It is an important point that even though we’re representing many keys with USB HID codes, these are not necessarily the same HID codes produced by the hardware and presented to the driver, since on most platforms we have to map the platform representation back to an HID code because we don’t have access to the original HID code. USB HID is simply a conveniently well-defined standard that includes many of the keys we would want.