[macOS] Implement hit testing and handle platform view cursor changes (flutter#43101)

Fixes flutter#129085

## Changes to `FlutterMouseCursorPlugin`

- `none` cursor is not handled by hiding the cursor anymore. That was
too big of a hammer as it also affects other views (and platform views).
Instead empty cursor is created from empty `NSImage`.

- Cursor plugin now notifies the engine when cursor has changed. The
engine forwards the change to last `FlutterView` that handled mouse
event. This is necessary because on occasion `FlutterView` needs to be
able to restore cursor without framework being involved.

## Preventing PlatformView from changing cursor when it is obscured by
Flutter Content.

Generally in Cocoa cursor changes are done as response to `mouseMoved`
event, which is driven by a `NSTrackingArea`. The issue here is that
this is not affected by hit testing and tracking areas form a hierarchy
parallel to view hierarchy and are not affected by being obscured by
another view (or tracking area). This means that platform view will
receive `mouseMoved` event even when is obscured by Flutter content. To
work around this, the mutator view puts a tracking area above platform
view, which means it gets the mouseMove event first, and when it decides
that mouse is over Flutter content, it will prevent platform view from
changing the cursor for the rest of RunLoop turn (see
`NSCursor+IgnoreChange`).

## Actual hit testing

This part is rather straightforward, the area where FlutterContent
obscures mutator view is provided to the mutator view, which will return
`nil` from `hitTest:` when the point is in the obscured area.

## Example of hit testing


https://github.com/flutter/engine/assets/96958/bbac0cfd-8c44-44d3-addd-921c91a8a539

## 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] and the [C++,
Objective-C, Java style guides].
- [X] I listed at least one issue that this PR fixes in the description
above.
- [X] I added new tests to check the change I am making or feature I am
adding, or Hixie said the PR is test-exempt. See [testing the engine]
for instructions on writing and running engine tests.
- [X] I updated/added relevant documentation (doc comments with `///`).
- [X] I signed the [CLA].
- [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/wiki/Tree-hygiene#overview
[Tree Hygiene]: https://github.com/flutter/flutter/wiki/Tree-hygiene
[Flutter Style Guide]:
https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo
[C++, Objective-C, Java style guides]:
https://github.com/flutter/engine/blob/main/CONTRIBUTING.md#style
[testing the engine]:
https://github.com/flutter/flutter/wiki/Testing-the-engine
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/wiki/Tree-hygiene#handling-breaking-changes
[Discord]: https://github.com/flutter/flutter/wiki/Chat

Author: knopp

shell/platform/darwin/macos/framework/Source/FlutterCompositor.h

@@ -8,20 +8,25 @@
 #include <functional>
 #include <list>
 #include <unordered_map>
+#include <variant>
 
 #include "flutter/fml/macros.h"
+#import "flutter/shell/platform/darwin/macos/framework/Source/FlutterMutatorView.h"
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterPlatformViewController.h"
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterTimeConverter.h"
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterViewProvider.h"
 #include "flutter/shell/platform/embedder/embedder.h"
 
 @class FlutterMutatorView;
+@class FlutterCursorCoordinator;
 
 namespace flutter {
 
-class PlatformViewLayer;
+struct BackingStoreLayer {
+  std::vector<FlutterRect> paint_region;
+};
 
-typedef std::pair<PlatformViewLayer, size_t> PlatformViewLayerWithIndex;
+using LayerVariant = std::variant<PlatformViewLayer, BackingStoreLayer>;
 
 // FlutterCompositor creates and manages the backing stores used for
 // rendering Flutter content and presents Flutter content and Platform views.
@@ -67,13 +72,16 @@ class FlutterCompositor {
     ViewPresenter();
 
     void PresentPlatformViews(FlutterView* default_base_view,
-                              const std::vector<PlatformViewLayerWithIndex>& platform_views,
+                              const std::vector<LayerVariant>& layers,
                               const FlutterPlatformViewController* platform_views_controller);
 
    private:
     // Platform view to FlutterMutatorView that contains it.
     NSMapTable<NSView*, FlutterMutatorView*>* mutator_views_;
 
+    // Coordinates mouse cursor changes between platform views and overlays.
+    FlutterCursorCoordinator* cursor_coordinator_;
+
     // Presents the platform view layer represented by `layer`. `layer_index` is
     // used to position the layer in the z-axis. If the layer does not have a
     // superview, it will become subview of `default_base_view`.

shell/platform/darwin/macos/framework/Source/FlutterCompositor.mm

@@ -3,22 +3,31 @@
 // found in the LICENSE file.
 
 #import "flutter/shell/platform/darwin/macos/framework/Source/FlutterCompositor.h"
-#import "flutter/shell/platform/darwin/macos/framework/Source/FlutterMutatorView.h"
 
 #include "flutter/fml/logging.h"
 
 namespace flutter {
 
 namespace {
-std::vector<PlatformViewLayerWithIndex> CopyPlatformViewLayers(const FlutterLayer** layers,
-                                                               size_t layer_count) {
-  std::vector<PlatformViewLayerWithIndex> platform_views;
+std::vector<LayerVariant> CopyLayers(const FlutterLayer** layers, size_t layer_count) {
+  std::vector<LayerVariant> layers_copy;
   for (size_t i = 0; i < layer_count; i++) {
-    if (layers[i]->type == kFlutterLayerContentTypePlatformView) {
-      platform_views.push_back(std::make_pair(PlatformViewLayer(layers[i]), i));
+    const auto& layer = layers[i];
+    if (layer->type == kFlutterLayerContentTypePlatformView) {
+      layers_copy.push_back(PlatformViewLayer(layer));
+    } else if (layer->type == kFlutterLayerContentTypeBackingStore) {
+      std::vector<FlutterRect> rects;
+      auto present_info = layer->backing_store_present_info;
+      if (present_info != nullptr && present_info->paint_region != nullptr) {
+        rects.reserve(present_info->paint_region->rects_count);
+        std::copy(present_info->paint_region->rects,
+                  present_info->paint_region->rects + present_info->paint_region->rects_count,
+                  std::back_inserter(rects));
+      }
+      layers_copy.push_back(BackingStoreLayer{rects});
     }
   }
-  return platform_views;
+  return layers_copy;
 }
 }  // namespace
 
@@ -91,17 +100,16 @@
 
   // Notify block below may be called asynchronously, hence the need to copy
   // the layer information instead of passing the original pointers from embedder.
-  auto platform_views_layers = std::make_shared<std::vector<PlatformViewLayerWithIndex>>(
-      CopyPlatformViewLayers(layers, layers_count));
-
-  [view.surfaceManager presentSurfaces:surfaces
-                                atTime:presentation_time
-                                notify:^{
-                                  // Gets a presenter or create a new one for the view.
-                                  ViewPresenter& presenter = presenters_[view_id];
-                                  presenter.PresentPlatformViews(view, *platform_views_layers,
-                                                                 platform_view_controller_);
-                                }];
+  auto layers_copy = std::make_shared<std::vector<LayerVariant>>(CopyLayers(layers, layers_count));
+
+  [view.surfaceManager
+      presentSurfaces:surfaces
+               atTime:presentation_time
+               notify:^{
+                 // Gets a presenter or create a new one for the view.
+                 ViewPresenter& presenter = presenters_[view_id];
+                 presenter.PresentPlatformViews(view, *layers_copy, platform_view_controller_);
+               }];
 
   return true;
 }
@@ -111,18 +119,45 @@
 
 void FlutterCompositor::ViewPresenter::PresentPlatformViews(
     FlutterView* default_base_view,
-    const std::vector<PlatformViewLayerWithIndex>& platform_views,
+    const std::vector<LayerVariant>& layers,
     const FlutterPlatformViewController* platform_view_controller) {
   FML_DCHECK([[NSThread currentThread] isMainThread])
       << "Must be on the main thread to present platform views";
 
   // Active mutator views for this frame.
   NSMutableArray<FlutterMutatorView*>* present_mutators = [NSMutableArray array];
 
-  for (const auto& platform_view : platform_views) {
-    FlutterMutatorView* container = PresentPlatformView(
-        default_base_view, platform_view.first, platform_view.second, platform_view_controller);
-    [present_mutators addObject:container];
+  for (size_t i = 0; i < layers.size(); i++) {
+    const auto& layer = layers[i];
+    if (!std::holds_alternative<PlatformViewLayer>(layer)) {
+      continue;
+    }
+    const auto& platform_view = std::get<PlatformViewLayer>(layer);
+    FlutterMutatorView* mutator_view =
+        PresentPlatformView(default_base_view, platform_view, i, platform_view_controller);
+    [present_mutators addObject:mutator_view];
+
+    // Gather all overlay regions above this mutator view.
+    [mutator_view resetHitTestRegion];
+    for (size_t j = i + 1; j < layers.size(); j++) {
+      const auto& overlay_layer = layers[j];
+      if (!std::holds_alternative<BackingStoreLayer>(overlay_layer)) {
+        continue;
+      }
+      const auto& backing_store_layer = std::get<BackingStoreLayer>(overlay_layer);
+      for (const auto& flutter_rect : backing_store_layer.paint_region) {
+        double scale = default_base_view.layer.contentsScale;
+        CGRect rect = CGRectMake(flutter_rect.left / scale, flutter_rect.top / scale,
+                                 (flutter_rect.right - flutter_rect.left) / scale,
+                                 (flutter_rect.bottom - flutter_rect.top) / scale);
+        CGRect intersection = CGRectIntersection(rect, mutator_view.frame);
+        if (!CGRectIsNull(intersection)) {
+          intersection.origin.x -= mutator_view.frame.origin.x;
+          intersection.origin.y -= mutator_view.frame.origin.y;
+          [mutator_view addHitTestIgnoreRegion:intersection];
+        }
+      }
+    }
   }
 
   NSMutableArray<FlutterMutatorView*>* obsolete_mutators =
@@ -150,10 +185,15 @@
 
   FML_DCHECK(platform_view) << "Platform view not found for id: " << platform_view_id;
 
+  if (cursor_coordinator_ == nil) {
+    cursor_coordinator_ = [[FlutterCursorCoordinator alloc] initWithFlutterView:default_base_view];
+  }
+
   FlutterMutatorView* container = [mutator_views_ objectForKey:platform_view];
 
   if (!container) {
-    container = [[FlutterMutatorView alloc] initWithPlatformView:platform_view];
+    container = [[FlutterMutatorView alloc] initWithPlatformView:platform_view
+                                                cursorCoordiator:cursor_coordinator_];
     [mutator_views_ setObject:container forKey:platform_view];
     [default_base_view addSubview:container];
   }

shell/platform/darwin/macos/framework/Source/FlutterEngine.mm

@@ -86,7 +86,7 @@ - (instancetype)initWithConnection:(NSNumber*)connection
 /**
  * Private interface declaration for FlutterEngine.
  */
-@interface FlutterEngine () <FlutterBinaryMessenger>
+@interface FlutterEngine () <FlutterBinaryMessenger, FlutterMouseCursorPluginDelegate>
 
 /**
  * A mutable array that holds one bool value that determines if responses to platform messages are
@@ -466,6 +466,10 @@ @implementation FlutterEngine {
   // Map from ViewId to vsync waiter. Note that this is modified on main thread
   // but accessed on UI thread, so access must be @synchronized.
   NSMapTable<NSNumber*, FlutterVSyncWaiter*>* _vsyncWaiters;
+
+  // Weak reference to last view that received a pointer event. This is used to
+  // pair cursor change with a view.
+  __weak FlutterView* _lastViewWithPointerEvent;
 }
 
 - (instancetype)initWithName:(NSString*)labelPrefix project:(FlutterDartProject*)project {
@@ -981,6 +985,7 @@ - (void)updateWindowMetricsForViewController:(FlutterViewController*)viewControl
 
 - (void)sendPointerEvent:(const FlutterPointerEvent&)event {
   _embedderAPI.SendPointerEvent(_engine, &event, 1);
+  _lastViewWithPointerEvent = [self viewControllerForId:kFlutterImplicitViewId].flutterView;
 }
 
 - (void)sendKeyEvent:(const FlutterKeyEvent&)event
@@ -1167,7 +1172,8 @@ - (void)setUpNotificationCenterListeners {
 
 - (void)addInternalPlugins {
   __weak FlutterEngine* weakSelf = self;
-  [FlutterMouseCursorPlugin registerWithRegistrar:[self registrarForPlugin:@"mousecursor"]];
+  [FlutterMouseCursorPlugin registerWithRegistrar:[self registrarForPlugin:@"mousecursor"]
+                                         delegate:self];
   [FlutterMenuPlugin registerWithRegistrar:[self registrarForPlugin:@"menu"]];
   _settingsChannel =
       [FlutterBasicMessageChannel messageChannelWithName:kFlutterSettingsChannel
@@ -1182,6 +1188,13 @@ - (void)addInternalPlugins {
   }];
 }
 
+- (void)didUpdateMouseCursor:(NSCursor*)cursor {
+  // Mouse cursor plugin does not specify which view is responsible for changing the cursor,
+  // so the reasonable assumption here is that cursor change is a result of a mouse movement
+  // and thus the cursor will be paired with last Flutter view that reveived mouse event.
+  [_lastViewWithPointerEvent didUpdateMouseCursor:cursor];
+}
+
 - (void)applicationWillTerminate:(NSNotification*)notification {
   [self shutDownEngine];
 }

shell/platform/darwin/macos/framework/Source/FlutterMouseCursorPlugin.h

@@ -10,6 +10,10 @@
 #import "flutter/shell/platform/darwin/common/framework/Headers/FlutterBinaryMessenger.h"
 #import "flutter/shell/platform/darwin/macos/framework/Headers/FlutterViewController.h"
 
+@protocol FlutterMouseCursorPluginDelegate <NSObject>
+- (void)didUpdateMouseCursor:(nonnull NSCursor*)cursor;
+@end
+
 /**
  * A plugin to handle mouse cursor.
  *
@@ -18,6 +22,9 @@
  */
 @interface FlutterMouseCursorPlugin : NSObject <FlutterPlugin>
 
++ (void)registerWithRegistrar:(nonnull id<FlutterPluginRegistrar>)registrar
+                     delegate:(nullable id<FlutterMouseCursorPluginDelegate>)delegate;
+
 @end
 
 #endif  // FLUTTER_SHELL_PLATFORM_DARWIN_MACOS_FRAMEWORK_SOURCE_FLUTTERMOUSECURSORPLUGIN_H_

shell/platform/darwin/macos/framework/Source/FlutterMouseCursorPlugin.mm

@@ -25,6 +25,11 @@
   // The following mapping must be kept in sync with Flutter framework's
   // mouse_cursor.dart
 
+  if ([kind isEqualToString:kKindValueNone]) {
+    NSImage* image = [[NSImage alloc] initWithSize:NSMakeSize(1, 1)];
+    return [[NSCursor alloc] initWithImage:image hotSpot:NSMakePoint(0, 0)];
+  }
+
   if (systemCursors == nil) {
     systemCursors = @{
       @"alias" : [NSCursor dragLinkCursor],
@@ -58,10 +63,8 @@
 }
 
 @interface FlutterMouseCursorPlugin ()
-/**
- * Whether the cursor is currently hidden.
- */
-@property(nonatomic) BOOL hidden;
+
+@property(nonatomic, weak) id<FlutterMouseCursorPluginDelegate> delegate;
 
 /**
  * Handles the method call that activates a system cursor.
@@ -79,11 +82,6 @@ - (FlutterError*)activateSystemCursor:(nonnull NSDictionary*)arguments;
  */
 - (void)displayCursorObject:(nonnull NSCursor*)cursorObject;
 
-/**
- * Hides the cursor.
- */
-- (void)hide;
-
 /**
  * Handles all method calls from Flutter.
  */
@@ -105,41 +103,22 @@ - (instancetype)init {
   return self;
 }
 
-- (void)dealloc {
-  if (_hidden) {
-    [NSCursor unhide];
-  }
-}
-
 - (FlutterError*)activateSystemCursor:(nonnull NSDictionary*)arguments {
   NSString* kindArg = arguments[kKindKey];
   if (!kindArg) {
     return [FlutterError errorWithCode:@"error"
                                message:@"Missing argument"
                                details:@"Missing argument while trying to activate system cursor"];
   }
-  if ([kindArg isEqualToString:kKindValueNone]) {
-    [self hide];
-    return nil;
-  }
+
   NSCursor* cursorObject = [FlutterMouseCursorPlugin cursorFromKind:kindArg];
   [self displayCursorObject:cursorObject];
   return nil;
 }
 
 - (void)displayCursorObject:(nonnull NSCursor*)cursorObject {
   [cursorObject set];
-  if (_hidden) {
-    [NSCursor unhide];
-  }
-  _hidden = NO;
-}
-
-- (void)hide {
-  if (!_hidden) {
-    [NSCursor hide];
-  }
-  _hidden = YES;
+  [self.delegate didUpdateMouseCursor:cursorObject];
 }
 
 + (NSCursor*)cursorFromKind:(NSString*)kind {
@@ -154,9 +133,15 @@ + (NSCursor*)cursorFromKind:(NSString*)kind {
 #pragma mark - FlutterPlugin implementation
 
 + (void)registerWithRegistrar:(id<FlutterPluginRegistrar>)registrar {
+  [self registerWithRegistrar:registrar delegate:nil];
+}
+
++ (void)registerWithRegistrar:(id<FlutterPluginRegistrar>)registrar
+                     delegate:(id<FlutterMouseCursorPluginDelegate>)delegate {
   FlutterMethodChannel* channel = [FlutterMethodChannel methodChannelWithName:kMouseCursorChannel
                                                               binaryMessenger:registrar.messenger];
   FlutterMouseCursorPlugin* instance = [[FlutterMouseCursorPlugin alloc] init];
+  instance.delegate = delegate;
   [registrar addMethodCallDelegate:instance channel:channel];
 }