RawKeyboardMacos accepts a new field "specifiedLogicalKey" (#100803)

dev/tools/gen_keycodes/data/keyboard_key.tmpl

@@ -83,9 +83,9 @@ class LogicalKeyboardKey extends KeyboardKey {
     const int valueMaskWidth = 32;
 
     // Equivalent to assert(divisorForValueMask == (1 << valueMaskWidth)).
-    const int _firstDivisorWidth = 28;
+    const int firstDivisorWidth = 28;
     assert(divisorForValueMask ==
-      (1 << _firstDivisorWidth) * (1 << (valueMaskWidth - _firstDivisorWidth)));
+      (1 << firstDivisorWidth) * (1 << (valueMaskWidth - firstDivisorWidth)));
 
     // JS only supports up to 2^53 - 1, therefore non-value bits can only
     // contain (maxSafeIntegerWidth - valueMaskWidth) bits.

dev/tools/gen_keycodes/data/macos_key_code_map_cc.tmpl

@@ -4,7 +4,7 @@
 
 #import <Cocoa/Cocoa.h>
 #import <Foundation/Foundation.h>
-#include "./KeyCodeMap_internal.h"
+#include "./KeyCodeMap_Internal.h"
 
 // DO NOT EDIT -- DO NOT EDIT -- DO NOT EDIT
 // This file is generated by
@@ -17,6 +17,8 @@
 //
 // See flutter/flutter:dev/tools/gen_keycodes/README.md for more information.
 
+namespace flutter {
+
 @@@MASK_CONSTANTS@@@
 
 const NSDictionary* keyCodeToPhysicalKey = @{
@@ -36,3 +38,9 @@ const NSDictionary* modifierFlagToKeyCode = @{
 };
 
 @@@SPECIAL_KEY_CONSTANTS@@@
+
+const std::vector<LayoutGoal> layoutGoals = {
+@@@LAYOUT_GOALS@@@
+};
+
+}  // namespace flutter

dev/tools/gen_keycodes/lib/macos_code_gen.dart

@@ -96,6 +96,27 @@ class MacOSCodeGenerator extends PlatformCodeGenerator {
     return specialKeyConstants.toString().trimRight();
   }
 
+  String get _layoutGoals {
+    final OutputLines<int> lines = OutputLines<int>('macOS layout goals');
+    final Iterable<LogicalKeyEntry> asciiEntries = logicalData.entries.where(
+        (LogicalKeyEntry entry) => entry.value <= 128);
+    for (final LogicalKeyEntry logicalEntry in asciiEntries) {
+      final int value = logicalEntry.value;
+      final PhysicalKeyEntry? physicalEntry = keyData.tryEntryByName(logicalEntry.name);
+      if (physicalEntry == null) {
+        continue;
+      }
+      final bool mandatory = (value >= '0'.codeUnitAt(0) && value <= '9'.codeUnitAt(0))
+                          || (value >= 'a'.codeUnitAt(0) && value <= 'z'.codeUnitAt(0));
+      lines.add(value,
+          '    LayoutGoal{${toHex(physicalEntry.macOSScanCode, digits: 2)}, '
+          '${toHex(value, digits: 2)}, '
+          '${mandatory ? 'true}, ' : 'false},'}'
+          '  // ${logicalEntry.name}');
+    }
+    return lines.sortedJoin().trimRight();
+  }
+
   @override
   String get templatePath => path.join(dataRoot, 'macos_key_code_map_cc.tmpl');
 
@@ -115,6 +136,7 @@ class MacOSCodeGenerator extends PlatformCodeGenerator {
       'KEYCODE_TO_MODIFIER_FLAG_MAP': _keyToModifierFlagMap,
       'MODIFIER_FLAG_TO_KEYCODE_MAP': _modifierFlagToKeyMap,
       'SPECIAL_KEY_CONSTANTS': _specialKeyConstants,
+      'LAYOUT_GOALS': _layoutGoals,
     };
   }
 }

packages/flutter/lib/src/services/raw_keyboard.dart

@@ -343,6 +343,7 @@ abstract class RawKeyEvent with Diagnosticable {
             charactersIgnoringModifiers: message['charactersIgnoringModifiers'] as String? ?? '',
             keyCode: message['keyCode'] as int? ?? 0,
             modifiers: message['modifiers'] as int? ?? 0,
+            specifiedLogicalKey: message['specifiedLogicalKey'] as int?,
           );
           character = message['characters'] as String?;
           break;

packages/flutter/lib/src/services/raw_keyboard_macos.dart

@@ -36,6 +36,7 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
     this.charactersIgnoringModifiers = '',
     this.keyCode = 0,
     this.modifiers = 0,
+    this.specifiedLogicalKey,
   }) : assert(characters != null),
        assert(charactersIgnoringModifiers != null),
        assert(keyCode != null),
@@ -70,6 +71,15 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
   ///  * [Apple's NSEvent documentation](https://developer.apple.com/documentation/appkit/nsevent/1535211-modifierflags?language=objc)
   final int modifiers;
 
+  /// A logical key specified by the embedding that should be used instead of
+  /// deriving from raw data.
+  ///
+  /// The macOS embedding detects the keyboard layout and maps some keys to
+  /// logical keys in a way that can not be derived from per-key information.
+  ///
+  /// This is not part of the native macOS key event.
+  final int? specifiedLogicalKey;
+
   @override
   String get keyLabel => charactersIgnoringModifiers;
 
@@ -78,6 +88,10 @@ class RawKeyEventDataMacOs extends RawKeyEventData {
 
   @override
   LogicalKeyboardKey get logicalKey {
+    if (specifiedLogicalKey != null) {
+      final int key = specifiedLogicalKey!;
+      return LogicalKeyboardKey.findKeyByKeyId(key) ?? LogicalKeyboardKey(key);
+    }
     // Look to see if the keyCode is a printable number pad key, so that a
     // difference between regular keys (e.g. "=") and the number pad version
     // (e.g. the "=" on the number pad) can be determined.

packages/flutter/test/services/raw_keyboard_test.dart

@@ -1546,6 +1546,21 @@ void main() {
       expect(data.logicalKey, equals(const LogicalKeyboardKey(0x1400000000)));
     });
 
+    test('Prioritize logical key from specifiedLogicalKey', () {
+      final RawKeyEvent digit1FromFrench = RawKeyEvent.fromMessage(const <String, dynamic>{
+        'type': 'keydown',
+        'keymap': 'macos',
+        'keyCode': 0x00000012,
+        'characters': '&',
+        'charactersIgnoringModifiers': '&',
+        'specifiedLogicalKey': 0x000000031,
+        'modifiers': 0,
+      });
+      final RawKeyEventDataMacOs data = digit1FromFrench.data as RawKeyEventDataMacOs;
+      expect(data.physicalKey, equals(PhysicalKeyboardKey.digit1));
+      expect(data.logicalKey, equals(LogicalKeyboardKey.digit1));
+    });
+
     test('data.toString', () {
       expect(RawKeyEvent.fromMessage(const <String, dynamic>{
         'type': 'keydown',