[macOS] Prepare FlutterKeyboardManager for multi-view (flutter#163962)

Notable changes:
- Moved keyboard layout related code from `FlutterViewController` to
`FlutterKeyboardLayout`.
- `FlutterKeyboardManager` is now owned by the engine and shared between
view controllers. The per view controller part, which is associated with
event, has been moved from `FlutterKeyboardManager` delegate to
`FlutterKeyboardManagerEventContext`.
- The `FlutterKeyboardManagerDelegate` is implemented by
`FlutterEngine`.
- Some overall clean-up and dead code removal (i.e. `_NSResponderPtr`
and `NextResponderProvider`)

## Pre-launch Checklist

- [x] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [x] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [x] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [x] I signed the [CLA].
- [x] I listed at least one issue that this PR fixes in the description
above.
- [x] I updated/added relevant documentation (doc comments with `///`).
- [x] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [x] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [x] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

---------

Co-authored-by: Tong Mu <[email protected]>

Author: knopp

engine/src/flutter/ci/licenses_golden/licenses_flutter

@@ -43450,10 +43450,11 @@ ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterEng
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterExternalTexture.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterExternalTexture.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyPrimaryResponder.h + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.h + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManagerTest.mm + ../../../flutter/LICENSE
-ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardViewDelegate.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPlugin.h + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPlugin.mm + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPluginTest.mm + ../../../flutter/LICENSE
@@ -46401,10 +46402,11 @@ FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterEngin
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterExternalTexture.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterExternalTexture.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyPrimaryResponder.h
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.h
+FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManagerTest.mm
-FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardViewDelegate.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPlugin.h
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPlugin.mm
 FILE: ../../../flutter/shell/platform/darwin/macos/framework/Source/FlutterMenuPluginTest.mm

engine/src/flutter/shell/platform/darwin/macos/BUILD.gn

@@ -77,9 +77,10 @@ source_set("flutter_framework_source") {
     "framework/Source/FlutterExternalTexture.h",
     "framework/Source/FlutterExternalTexture.mm",
     "framework/Source/FlutterKeyPrimaryResponder.h",
+    "framework/Source/FlutterKeyboardLayout.h",
+    "framework/Source/FlutterKeyboardLayout.mm",
     "framework/Source/FlutterKeyboardManager.h",
     "framework/Source/FlutterKeyboardManager.mm",
-    "framework/Source/FlutterKeyboardViewDelegate.h",
     "framework/Source/FlutterMenuPlugin.h",
     "framework/Source/FlutterMenuPlugin.mm",
     "framework/Source/FlutterMenuPlugin_Internal.h",

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterChannelKeyResponder.mm

@@ -104,9 +104,6 @@ - (void)syncModifiersIfNeeded:(NSEventModifierFlags)modifierFlags
             forEventFlags:modifierFlags
                   keyCode:0x00000039  // kVK_CapsLock
                 timestamp:timestamp];
-
-  // At the end we should end up with the same modifier flags as the event.
-  FML_DCHECK(_previouslyPressedFlags == modifierFlags);
 }
 
 - (void)handleEvent:(NSEvent*)event callback:(FlutterAsyncKeyCallback)callback {

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngine.mm

@@ -89,7 +89,9 @@ - (instancetype)initWithConnection:(NSNumber*)connection
 /**
  * Private interface declaration for FlutterEngine.
  */
-@interface FlutterEngine () <FlutterBinaryMessenger, FlutterMouseCursorPluginDelegate>
+@interface FlutterEngine () <FlutterBinaryMessenger,
+                             FlutterMouseCursorPluginDelegate,
+                             FlutterKeyboardManagerDelegate>
 
 /**
  * A mutable array that holds one bool value that determines if responses to platform messages are
@@ -473,6 +475,9 @@ @implementation FlutterEngine {
   // Weak reference to last view that received a pointer event. This is used to
   // pair cursor change with a view.
   __weak FlutterView* _lastViewWithPointerEvent;
+
+  // Pointer to a keyboard manager.
+  FlutterKeyboardManager* _keyboardManager;
 }
 
 - (instancetype)initWithName:(NSString*)labelPrefix project:(FlutterDartProject*)project {
@@ -513,6 +518,7 @@ - (instancetype)initWithName:(NSString*)labelPrefix
   _binaryMessenger = [[FlutterBinaryMessengerRelay alloc] initWithParent:self];
   _isResponseValid = [[NSMutableArray alloc] initWithCapacity:1];
   [_isResponseValid addObject:@YES];
+  _keyboardManager = [[FlutterKeyboardManager alloc] initWithDelegate:self];
 
   _embedderAPI.struct_size = sizeof(FlutterEngineProcTable);
   FlutterEngineGetProcAddresses(&_embedderAPI);
@@ -1024,12 +1030,6 @@ - (void)sendPointerEvent:(const FlutterPointerEvent&)event {
   _lastViewWithPointerEvent = [self viewControllerForIdentifier:kFlutterImplicitViewId].flutterView;
 }
 
-- (void)sendKeyEvent:(const FlutterKeyEvent&)event
-            callback:(FlutterKeyEventCallback)callback
-            userData:(void*)userData {
-  _embedderAPI.SendKeyEvent(_engine, &event, callback, userData);
-}
-
 - (void)setSemanticsEnabled:(BOOL)enabled {
   if (_semanticsEnabled == enabled) {
     return;
@@ -1127,6 +1127,7 @@ - (void)engineCallbackOnPreEngineRestart {
     [nextViewController onPreEngineRestart];
   }
   [_platformViewController reset];
+  _keyboardManager = [[FlutterKeyboardManager alloc] initWithDelegate:self];
 }
 
 - (void)onVSync:(uintptr_t)baton {
@@ -1564,4 +1565,15 @@ - (void)postMainThreadTask:(FlutterTask)task targetTimeInNanoseconds:(uint64_t)t
   return _macOSCompositor.get();
 }
 
+#pragma mark - FlutterKeyboardManagerDelegate
+
+/**
+ * Dispatches the given pointer event data to engine.
+ */
+- (void)sendKeyEvent:(const FlutterKeyEvent&)event
+            callback:(FlutterKeyEventCallback)callback
+            userData:(void*)userData {
+  _embedderAPI.SendKeyEvent(_engine, &event, callback, userData);
+}
+
 @end

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterEngine_Internal.h

@@ -14,6 +14,7 @@
 #include "flutter/shell/platform/common/app_lifecycle_state.h"
 
 #import "flutter/shell/platform/darwin/macos/framework/Source/AccessibilityBridgeMac.h"
+#import "flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardManager.h"
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatformViewController.h"
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterRenderer.h"
 
@@ -165,13 +166,6 @@ typedef NS_ENUM(NSInteger, FlutterAppExitResponse) {
  */
 - (void)sendPointerEvent:(const FlutterPointerEvent&)event;
 
-/**
- * Dispatches the given pointer event data to engine.
- */
-- (void)sendKeyEvent:(const FlutterKeyEvent&)event
-            callback:(nullable FlutterKeyEventCallback)callback
-            userData:(nullable void*)userData;
-
 /**
  * Registers an external texture with the given id. Returns YES on success.
  */
@@ -218,6 +212,11 @@ typedef NS_ENUM(NSInteger, FlutterAppExitResponse) {
 - (void)announceAccessibilityMessage:(NSString*)message
                         withPriority:(NSAccessibilityPriorityLevel)priority;
 
+/**
+ * Returns keyboard manager for the engine.
+ */
+@property(nonatomic, readonly) FlutterKeyboardManager* keyboardManager;
+
 /**
  * Returns an array of screen objects representing all of the screens available on the system.
  */

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.h

@@ -0,0 +1,61 @@
+// Copyright 2013 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.
+
+#ifndef FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERKEYBOARDLAYOUT_H_
+#define FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERKEYBOARDLAYOUT_H_
+
+#import <AppKit/AppKit.h>
+
+namespace flutter {
+
+// The printable result of a key under certain modifiers, used to derive key
+// mapping.
+typedef struct {
+  // The printable character.
+  //
+  // If `isDeadKey` is true, then this is the character when pressing the same
+  // dead key twice.
+  uint32_t character;
+
+  // Whether this character is a dead key.
+  //
+  // A dead key is a key that is not counted as text per se, but holds a
+  // diacritics to be added to the next key.
+  bool isDeadKey;
+} LayoutClue;
+
+}  // namespace flutter
+
+/**
+ * A delegate protocol for FlutterKeyboardLayout. Implemented by FlutterKeyboardManager.
+ */
+@protocol FlutterKeyboardLayoutDelegate
+
+/**
+ * Called when the active keyboard input source changes.
+ *
+ * Input sources may be simple keyboard layouts, or more complex input methods involving an IME,
+ * such as Chinese, Japanese, and Korean.
+ */
+- (void)keyboardLayoutDidChange;
+
+@end
+
+/**
+ * A class that allows querying the printable result of a key with a modifier state according to the
+ * current keyboard layout. It also provides a delegate protocol for clients interested in
+ * listening to keyboard layout changes.
+ */
+@interface FlutterKeyboardLayout : NSObject
+
+@property(readwrite, nonatomic, weak) id<FlutterKeyboardLayoutDelegate> delegate;
+
+/**
+ * Querying the printable result of a key under the given modifier state.
+ */
+- (flutter::LayoutClue)lookUpLayoutForKeyCode:(uint16_t)keyCode shift:(BOOL)shift;
+
+@end
+
+#endif  // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERKEYBOARDLAYOUT_H_

engine/src/flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.mm

@@ -0,0 +1,107 @@
+// Copyright 2013 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 "flutter/shell/platform/darwin/macos/framework/Source/FlutterKeyboardLayout.h"
+
+#include <Carbon/Carbon.h>
+#include <cctype>
+#include "flutter/fml/platform/darwin/cf_utils.h"
+
+@implementation FlutterKeyboardLayout {
+  NSData* _keyboardLayoutData;
+}
+
+@synthesize delegate = _delegate;
+
+/**
+ * Returns the current Unicode layout data (kTISPropertyUnicodeKeyLayoutData).
+ *
+ * To use the returned data, convert it to CFDataRef first, finds its bytes
+ * with CFDataGetBytePtr, then reinterpret it into const UCKeyboardLayout*.
+ * It's returned in NSData* to enable auto reference count.
+ */
+static NSData* CurrentKeyboardLayoutData() {
+  fml::CFRef<TISInputSourceRef> source(TISCopyCurrentKeyboardInputSource());
+  CFTypeRef layout_data = TISGetInputSourceProperty(source, kTISPropertyUnicodeKeyLayoutData);
+  if (layout_data == nil) {
+    // TISGetInputSourceProperty returns null with Japanese keyboard layout.
+    // Using TISCopyCurrentKeyboardLayoutInputSource to fix NULL return.
+    // https://github.com/microsoft/node-native-keymap/blob/5f0699ded00179410a14c0e1b0e089fe4df8e130/src/keyboard_mac.mm#L91
+    source.Reset(TISCopyCurrentKeyboardLayoutInputSource());
+    layout_data = TISGetInputSourceProperty(source, kTISPropertyUnicodeKeyLayoutData);
+  }
+  return (__bridge NSData*)layout_data;
+}
+
+/**
+ * NotificationCenter callback invoked on kTISNotifySelectedKeyboardInputSourceChanged events.
+ */
+static void OnKeyboardLayoutChanged(CFNotificationCenterRef center,
+                                    void* observer,
+                                    CFStringRef name,
+                                    const void* object,
+                                    CFDictionaryRef userInfo) {
+  FlutterKeyboardLayout* controller = (__bridge FlutterKeyboardLayout*)observer;
+  if (controller != nil) {
+    [controller onKeyboardLayoutChanged];
+  }
+}
+
+- (instancetype)initWithDelegate:(id<FlutterKeyboardLayoutDelegate>)delegate {
+  self = [super init];
+  if (self) {
+    _delegate = delegate;
+    // macOS fires this message when changing IMEs.
+    CFNotificationCenterRef cfCenter = CFNotificationCenterGetDistributedCenter();
+    __weak FlutterKeyboardLayout* weakSelf = self;
+    CFNotificationCenterAddObserver(cfCenter, (__bridge void*)weakSelf, OnKeyboardLayoutChanged,
+                                    kTISNotifySelectedKeyboardInputSourceChanged, NULL,
+                                    CFNotificationSuspensionBehaviorDeliverImmediately);
+  }
+  return self;
+}
+
+- (void)dealloc {
+  CFNotificationCenterRef cfCenter = CFNotificationCenterGetDistributedCenter();
+  CFNotificationCenterRemoveEveryObserver(cfCenter, (__bridge void*)self);
+}
+
+- (void)onKeyboardLayoutChanged {
+  _keyboardLayoutData = nil;
+  [_delegate keyboardLayoutDidChange];
+}
+
+- (flutter::LayoutClue)lookUpLayoutForKeyCode:(uint16_t)keyCode shift:(BOOL)shift {
+  if (_keyboardLayoutData == nil) {
+    _keyboardLayoutData = CurrentKeyboardLayoutData();
+  }
+  const UCKeyboardLayout* layout = reinterpret_cast<const UCKeyboardLayout*>(
+      CFDataGetBytePtr((__bridge CFDataRef)_keyboardLayoutData));
+
+  UInt32 deadKeyState = 0;
+  UniCharCount stringLength = 0;
+  UniChar resultChar;
+
+  UInt32 modifierState = ((shift ? shiftKey : 0) >> 8) & 0xFF;
+  UInt32 keyboardType = LMGetKbdLast();
+
+  bool isDeadKey = false;
+  OSStatus status =
+      UCKeyTranslate(layout, keyCode, kUCKeyActionDown, modifierState, keyboardType,
+                     kUCKeyTranslateNoDeadKeysBit, &deadKeyState, 1, &stringLength, &resultChar);
+  // For dead keys, press the same key again to get the printable representation of the key.
+  if (status == noErr && stringLength == 0 && deadKeyState != 0) {
+    isDeadKey = true;
+    status =
+        UCKeyTranslate(layout, keyCode, kUCKeyActionDown, modifierState, keyboardType,
+                       kUCKeyTranslateNoDeadKeysBit, &deadKeyState, 1, &stringLength, &resultChar);
+  }
+
+  if (status == noErr && stringLength == 1 && !std::iscntrl(resultChar)) {
+    return flutter::LayoutClue{resultChar, isDeadKey};
+  }
+  return flutter::LayoutClue{0, false};
+}
+
+@end