Remove keyLabel and debugName from Logical/PhysicalKeyboardKey (flutter#78263)

- Remove `LogicalKeyboardKey.keyLabel`
- Make `Physical/LogicalKeyboardKey.debugName` getters
- Make `Physical/LogicalKeyboardKey()` factory constructors, which cache non-predefined instances.

Author: dkwingsmt

dev/tools/gen_keycodes/bin/gen_keycodes.dart

@@ -18,6 +18,7 @@ import 'package:gen_keycodes/glfw_code_gen.dart';
 import 'package:gen_keycodes/gtk_code_gen.dart';
 import 'package:gen_keycodes/windows_code_gen.dart';
 import 'package:gen_keycodes/web_code_gen.dart';
+import 'package:gen_keycodes/key_labels_code_gen.dart';
 import 'package:gen_keycodes/keyboard_keys_code_gen.dart';
 import 'package:gen_keycodes/keyboard_maps_code_gen.dart';
 import 'package:gen_keycodes/key_data.dart';
@@ -253,6 +254,13 @@ Future<void> main(List<String> rawArguments) async {
   print('Writing ${'key maps'.padRight(15)}${mapsFile.absolute}');
   await mapsFile.writeAsString(KeyboardMapsCodeGenerator(data).generate());
 
+  final File keyLabelsFile = File(path.join(flutterRoot.path, 'packages', 'flutter_test', 'lib', 'src', 'key_labels.dart'));
+  if (!keyLabelsFile.existsSync()) {
+    mapsFile.createSync(recursive: true);
+  }
+  print('Writing ${'key labels'.padRight(15)}${mapsFile.absolute}');
+  await keyLabelsFile.writeAsString(KeyLabelsCodeGenerator(data).generate());
+
   for (final String platform in <String>['android', 'macos', 'ios', 'glfw', 'fuchsia', 'linux', 'windows', 'web']) {
     PlatformCodeGenerator codeGenerator;
     switch (platform) {

dev/tools/gen_keycodes/data/key_labels.tmpl

@@ -0,0 +1,16 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// DO NOT EDIT -- DO NOT EDIT -- DO NOT EDIT
+// This file is generated by dev/tools/gen_keycodes/bin/gen_keycodes.dart and
+// should not be edited directly.
+//
+// Edit the template dev/tools/gen_keycodes/data/key_labels.tmpl instead.
+// See dev/tools/gen_keycodes/README.md for more information.
+
+/// The keyLabel corresponding to a logical key.
+///
+/// Used to generate simulated key events out of a logical key.
+const Map<int, String> logicalKeyLabels = <int, String>{
+@@@LOGICAL_KEY_LABELS@@@};

dev/tools/gen_keycodes/data/keyboard_key.tmpl

@@ -76,9 +76,9 @@ abstract class KeyboardKey with Diagnosticable {
 ///       _message = 'Pressed the "Q" key!';
 ///     } else {
 ///       if (kReleaseMode) {
-///         _message = 'Not a Q: Key label is "${event.logicalKey.keyLabel}"';
+///         _message = 'Not a Q: Pressed 0x${event.logicalKey.keyId.toRadixString(16)}';
 ///       } else {
-///         // This will only print useful information in debug mode.
+///         // The debugName will only print useful information in debug mode.
 ///         _message = 'Not a Q: Pressed ${event.logicalKey.debugName}';
 ///       }
 ///     }
@@ -124,59 +124,61 @@ abstract class KeyboardKey with Diagnosticable {
 ///    keyboard events.
 @immutable
 class LogicalKeyboardKey extends KeyboardKey {
-  /// Creates a LogicalKeyboardKey object with an optional key label and debug
-  /// name.
+  /// A LogicalKeyboardKey object for a key ID.
   ///
-  /// [keyId] must not be null.
-  ///
-  /// {@tool snippet}
-  /// To save executable size, it is recommended that the [debugName] be null in
-  /// release mode. You can do this by using the [kReleaseMode] constant.
-  ///
-  /// ```dart
-  /// const LogicalKeyboardKey(0x0010000000a, debugName: kReleaseMode ? null : 'Special Key')
-  /// ```
-  /// {@end-tool}
-  const LogicalKeyboardKey(this.keyId, {this.debugName, this.keyLabel = ''})
-      : assert(keyId != null);
+  /// This factory constructor ensures that the same `keyId` always results
+  /// in the identical instance. It looks up an object from the predefined values
+  /// if possible, or construct a new one and cache it.
+  factory LogicalKeyboardKey(int keyId) {
+    return findKeyByKeyId(keyId) ??
+      _additionalKeyPool.putIfAbsent(keyId, () => LogicalKeyboardKey._(keyId));
+  }
+
+  /// Creates a LogicalKeyboardKey object for a key ID.
+  const LogicalKeyboardKey._(this.keyId);
 
   /// A unique code representing this key.
   ///
   /// This is an opaque code. It should not be unpacked to derive information
   /// from it, as the representation of the code could change at any time.
   final int keyId;
 
+  // Returns the bits that are not included in [valueMask], shifted to the
+  // right.
+  //
+  // For example, if the input is 0x12abcdabcd, then the result is 0x12.
+  //
+  // This could have been a trivial shifting for non-Web environment, but in
+  // order to support JavaScript, which only supports bitwise operation of up to
+  // 32 bits, this function extracts them using division.
+  //
+  // It returns 0 for release mode.
+  static int _debugNonValueBits(int numOf64Bits) {
+    int result = 0;
+    assert(() {
+      const int kDivisorForValueMask = valueMask + 1;
+      result = (numOf64Bits / kDivisorForValueMask).floor();
+      return true;
+    }());
+    return result;
+  }
+
   /// The debug string to print for this keyboard key, which will be null in
   /// release mode.
-  final String? debugName;
-
-  /// The Unicode string representing the character produced by a [RawKeyEvent].
-  ///
-  /// This value is useful for describing or matching mnemonic keyboard
-  /// shortcuts.
-  ///
-  /// This value is an empty string if there's no key label data for a key.
-  ///
-  /// On most platforms this is a single code point, but it could contain any
-  /// Unicode string. The `keyLabel` differs from [RawKeyEvent.character]
-  /// because `keyLabel` only takes into account the key being pressed, not any
-  /// combining keys pressed before it, so, for example, an “o” that follows a
-  /// combining dieresis (“¨”, COMBINING DIAERESIS (U+0308)) would just return
-  /// “o” for [keyLabel], but would return “ö” for [RawKeyEvent.character].
-  ///
-  /// {@macro flutter.services.RawKeyEventData.keyLabel}
-  final String keyLabel;
-
-  @override
-  int get hashCode => keyId.hashCode;
-
-  @override
-  bool operator ==(Object other) {
-    if (other.runtimeType != runtimeType) {
-      return false;
-    }
-    return other is LogicalKeyboardKey
-        && other.keyId == keyId;
+  String? get debugName {
+    String? result;
+    assert(() {
+      result = _debugNames[keyId];
+      if (result == null) {
+        if (_debugNonValueBits(keyId) == 0) {
+          result = 'Key ${String.fromCharCode(keyId)}';
+        } else {
+          result = 'Key with ID 0x${keyId.toRadixString(16).padLeft(11, '0')}';
+        }
+      }
+      return true;
+    }());
+    return result;
   }
 
   /// Returns the [LogicalKeyboardKey] constant that matches the given ID, or
@@ -261,10 +263,11 @@ class LogicalKeyboardKey extends KeyboardKey {
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties.add(StringProperty('keyId', '0x${keyId.toRadixString(16).padLeft(8, '0')}', showName: true));
-    properties.add(StringProperty('keyLabel', keyLabel, showName: true));
     properties.add(StringProperty('debugName', debugName, showName: true, defaultValue: null));
   }
 
+  static final Map<int, LogicalKeyboardKey> _additionalKeyPool = <int, LogicalKeyboardKey>{};
+
   /// Mask for the 32-bit value portion of the key code.
   ///
   /// This is used by platform-specific code to generate Flutter key codes.
@@ -313,6 +316,11 @@ class LogicalKeyboardKey extends KeyboardKey {
   // A map of keys to the pseudo-key synonym for that key. Used by getSynonyms.
   static final Map<LogicalKeyboardKey, LogicalKeyboardKey> _synonyms = <LogicalKeyboardKey, LogicalKeyboardKey>{
 @@@LOGICAL_KEY_SYNONYMS@@@  };
+
+  static const Map<int, String> _debugNames = kReleaseMode ?
+    <int, String>{} :
+    <int, String>{
+@@@LOGICAL_KEY_DEBUG_NAMES@@@    };
 }
 
 /// A class with static values that describe the keys that are returned from
@@ -387,7 +395,7 @@ class LogicalKeyboardKey extends KeyboardKey {
 ///                 onTap: () {
 ///                   FocusScope.of(context).requestFocus(_focusNode);
 ///                 },
-///                 child: Text('Tap to focus'),
+///                 child: const Text('Tap to focus'),
 ///               );
 ///             }
 ///             return Text(_message ?? 'Press a key');
@@ -408,20 +416,18 @@ class LogicalKeyboardKey extends KeyboardKey {
 ///    keyboard events.
 @immutable
 class PhysicalKeyboardKey extends KeyboardKey {
-  /// Creates a PhysicalKeyboardKey object with an optional debug name.
-  ///
-  /// The [usbHidUsage] must not be null.
-  ///
-  /// {@tool snippet}
-  /// To save executable size, it is recommended that the [debugName] be null in
-  /// release mode. You can do this using the [kReleaseMode] constant.
+  /// A PhysicalKeyboardKey object for a USB HID usage.
   ///
-  /// ```dart
-  /// const PhysicalKeyboardKey(0x0000ffff, debugName: kReleaseMode ? null : 'Special Key')
-  /// ```
-  /// {@end-tool}
-  const PhysicalKeyboardKey(this.usbHidUsage, {this.debugName})
-      : assert(usbHidUsage != null);
+  /// This factory constructor ensures that the same `usbHidUsage` always results
+  /// in the identical instance. It looks up an object from the predefined values
+  /// if possible, or construct a new one and cache it.
+  factory PhysicalKeyboardKey(int usbHidUsage) {
+    return findKeyByCode(usbHidUsage) ??
+      _additionalKeyPool.putIfAbsent(usbHidUsage, () => PhysicalKeyboardKey._(usbHidUsage));
+  }
+
+  /// Creates a PhysicalKeyboardKey object for a USB HID usage.
+  const PhysicalKeyboardKey._(this.usbHidUsage);
 
   /// The unique USB HID usage ID of this physical key on the keyboard.
   ///
@@ -435,31 +441,29 @@ class PhysicalKeyboardKey extends KeyboardKey {
 
   /// The debug string to print for this keyboard key, which will be null in
   /// release mode.
-  final String? debugName;
+  String? get debugName {
+    String? result;
+    assert(() {
+      result = _debugNames[usbHidUsage] ??
+        'Key with ID 0x${usbHidUsage.toRadixString(16).padLeft(8, '0')}';
+      return true;
+    }());
+    return result;
+  }
 
   /// Finds a known [PhysicalKeyboardKey] that matches the given USB HID usage
   /// code.
   static PhysicalKeyboardKey? findKeyByCode(int usageCode) => _knownPhysicalKeys[usageCode];
 
-  @override
-  int get hashCode => usbHidUsage.hashCode;
-
-  @override
-  bool operator ==(Object other) {
-    if (other.runtimeType != runtimeType) {
-      return false;
-    }
-    return other is PhysicalKeyboardKey
-        && other.usbHidUsage == usbHidUsage;
-  }
-
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {
     super.debugFillProperties(properties);
     properties.add(StringProperty('usbHidUsage', '0x${usbHidUsage.toRadixString(16).padLeft(8, '0')}', showName: true));
     properties.add(StringProperty('debugName', debugName, showName: true, defaultValue: null));
   }
 
+  static final Map<int, PhysicalKeyboardKey> _additionalKeyPool = <int, PhysicalKeyboardKey>{};
+
   // Key constants for all keyboard keys in the USB HID specification at the
   // time Flutter was built.
 @@@PHYSICAL_KEY_DEFINITIONS@@@
@@ -468,4 +472,9 @@ class PhysicalKeyboardKey extends KeyboardKey {
   static const Map<int, PhysicalKeyboardKey> _knownPhysicalKeys = <int, PhysicalKeyboardKey>{
 @@@PHYSICAL_KEY_MAP@@@
   };
+
+  static const Map<int, String> _debugNames = kReleaseMode ?
+    <int, String>{} :
+    <int, String>{
+@@@PHYSICAL_KEY_DEBUG_NAMES@@@    };
 }

dev/tools/gen_keycodes/lib/key_labels_code_gen.dart

@@ -0,0 +1,49 @@
+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'package:path/path.dart' as path;
+
+import 'base_code_gen.dart';
+import 'key_data.dart';
+import 'utils.dart';
+
+/// Generates the event_simulation_keylabels.dart based on the information in the
+/// key data structure given to it.
+class KeyLabelsCodeGenerator extends BaseCodeGenerator {
+  KeyLabelsCodeGenerator(KeyData keyData) : super(keyData);
+
+  /// Gets the generated definitions of logicalKeyLabels.
+  String get _logicalKeyLabels {
+    String escapeLabel(String label) => label.contains("'") ? 'r"$label"' : "r'$label'";
+    final StringBuffer result = StringBuffer();
+    void printKey(int flutterId, String keyLabel) {
+      if (keyLabel != null)
+        result.write('''
+  ${toHex(flutterId, digits: 11)}: ${escapeLabel(keyLabel)},
+''');
+    }
+
+    for (final Key entry in keyData.data) {
+      printKey(entry.flutterId, entry.keyLabel);
+    }
+    for (final String name in Key.synonyms.keys) {
+      // Use the first item in the synonyms as a template for the ID to use.
+      // It won't end up being the same value because it'll be in the pseudo-key
+      // plane.
+      final Key entry = keyData.data.firstWhere((Key item) => item.name == Key.synonyms[name][0]);
+      printKey(Key.synonymPlane | entry.flutterId, entry.keyLabel);
+    }
+    return result.toString();
+  }
+
+  @override
+  String get templatePath => path.join(flutterRoot.path, 'dev', 'tools', 'gen_keycodes', 'data', 'key_labels.tmpl');
+
+  @override
+  Map<String, String> mappings() {
+    return <String, String>{
+      'LOGICAL_KEY_LABELS': _logicalKeyLabels,
+    };
+  }
+}