feat: Component Mixin to Receive Cursor Hover Events

doc/flame/inputs/gesture_input.md

@@ -515,3 +515,44 @@ More information about how to define hitboxes can be found in the hitbox section
 
 An example of how to use it can be seen
 [here](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/input/gesture_hitboxes_example.dart).
+
+
+### MouseMovement on the game level
+
+To give a `Game` class the ability to handle mouse movement/hover events,
+use the `MouseMovementDetector` mixin.  
+
+You can then override an `onMouseMove` method. This method receives
+[`PointerHoverInfo`](https://pub.dev/documentation/flame/latest/events/PointerHoverInfo-class.html)
+which provides the position of the hover event, as well as the raw
+[`PointerHoverEvent`](https://api.flutter.dev/flutter/gestures/PointerHoverEvent-class.html)
+
+```{warning}
+This should not be used on platforms that do not support mouse cursors.
+```
+
+Example:
+
+```dart
+class MouseCursorExample extends FlameGame with MouseMovementDetector {
+  // ...
+  @override
+  void onMouseMove(PointerHoverInfo info) {
+    print('X: ${info.eventPosition.game.x}');
+    print('Y: ${info.eventPosition.game.y}');
+  }
+}
+
+```
+
+
+### MouseMovement on the component level
+
+To receive mouse movement/hover events in components, use the `HasCursorHandlerComponents`
+mixin on any `Game` sub class first, and remove the `MouseMovementDetector` mixin (if present).
+
+Then, use the `CursorHandler` mixin on any `Component` sub class.
+
+See
+[here](https://github.com/flame-engine/flame/blob/main/examples/lib/stores/input/mouse_movement_components_example.dart)
+for an example.

examples/lib/stories/input/input.dart

@@ -79,6 +79,13 @@ void addInputStories(Dashbook dashbook) {
       codeLink: baseLink('input/mouse_movement_example.dart'),
       info: MouseMovementExample.description,
     )
+    // TODO: Add example
+    // ..add(
+    //   'Mouse Movement (Component)',
+    //   (_) => GameWidget(game: MouseMovementComponentsExample()),
+    //   codeLink: baseLink('input/mouse_movement_listener_example.dart'),
+    //   info: MouseMovementComponentsExample.description,
+    // )
     ..add(
       'Mouse Cursor',
       (_) => GameWidget(

examples/lib/stories/input/mouse_movement_components_example.dart

@@ -0,0 +1,72 @@
+// import 'dart:math';
+
+// import 'package:flame/components.dart';
+// import 'package:flame/events.dart';
+// import 'package:flame/game.dart';
+// import 'package:flutter/material.dart';
+
+// class MouseMovementComponentsExample extends FlameGame
+//     with HasCursorHandlerComponents {
+//   static const String description = '''
+//     This example shows how to handle mouse movement using `CursorHandler` Components.\n\n
+//     Moving the mouse around the canvas changes the angle of each Component, and causes
+//     the line drawn on them to face towards the mouse's position.
+//   ''';
+
+//   @override
+//   Future<void> onLoad() async {
+//     add(
+//       CursorFollowerCircle(
+//         radius: 20.0,
+//       )..position = size / 2,
+//     );
+//     add(
+//       CursorFollowerCircle(
+//         radius: 20.0,
+//       )..position = Vector2(100.0, 100.0),
+//     );
+//   }
+// }
+
+// class CursorFollowerCircle extends PositionComponent with CursorHandler {
+//   final double _radius;
+
+//   final Paint _paint;
+
+//   CursorFollowerCircle({required double radius})
+//       : _radius = radius,
+//         _paint = Paint()..color = const Color(0xFF80C080),
+//         super(
+//           size: Vector2.all(2 * radius),
+//           anchor: Anchor.center,
+//         );
+
+//   @override
+//   bool onMouseMove(PointerHoverInfo info) {
+//     final gameMousePositionX = info.eventPosition.game.x;
+
+//     final gameMousePositionY = info.eventPosition.game.y;
+
+//     angle =
+//         atan2(gameMousePositionY - position.y, gameMousePositionX - position.x);
+//     return super.onMouseMove(info);
+//   }
+
+//   @override
+//   void render(Canvas canvas) {
+//     super.render(canvas);
+
+//     canvas.drawCircle(
+//       Offset(_radius, _radius),
+//       _radius,
+//       _paint,
+//     );
+//     canvas.drawLine(
+//       Offset(_radius, _radius),
+//       Offset(_radius * 3.0, _radius),
+//       Paint()
+//         ..color = const Color(0xFFFFFFFF)
+//         ..strokeWidth = 2.0,
+//     );
+//   }
+// }

packages/flame/lib/components.dart

@@ -16,6 +16,7 @@ export 'src/components/input/joystick_component.dart';
 export 'src/components/input/keyboard_listener_component.dart';
 export 'src/components/isometric_tile_map_component.dart';
 export 'src/components/mixins/component_viewport_margin.dart';
+export 'src/components/mixins/cursor_handler.dart';
 export 'src/components/mixins/draggable.dart';
 export 'src/components/mixins/gesture_hitboxes.dart';
 export 'src/components/mixins/has_ancestor.dart';

packages/flame/lib/src/components/mixins/cursor_handler.dart

@@ -0,0 +1,8 @@
+import 'package:flame/components.dart';
+import 'package:flame/src/gestures/events.dart';
+
+mixin CursorHandler on Component {
+  bool onMouseMove(PointerHoverInfo info) {
+    return true;
+  }
+}

packages/flame/lib/src/events/component_mixins/cursor_hover_callbacks.dart

@@ -0,0 +1,19 @@
+import 'package:flame/src/components/core/component.dart';
+import 'package:flame/src/events/flame_game_mixins/cursor_hover_dispatcher.dart';
+import 'package:flame/src/events/messages/cursor_hover_event.dart';
+import 'package:flame/src/game/flame_game.dart';
+import 'package:meta/meta.dart';
+
+mixin CursorHoverCallbacks on Component {
+  void onMouseMove(CursorHoverEvent event) {}
+
+  @override
+  @mustCallSuper
+  void onMount() {
+    super.onMount();
+    final game = findGame()! as FlameGame;
+    if (game.firstChild<CursorHoverDispatcher>() == null) {
+      game.add(CursorHoverDispatcher());
+    }
+  }
+}

packages/flame/lib/src/events/flame_game_mixins/cursor_hover_dispatcher.dart

@@ -0,0 +1,41 @@
+import 'package:flame/src/components/core/component.dart';
+import 'package:flame/src/events/component_mixins/cursor_hover_callbacks.dart';
+import 'package:flame/src/events/messages/cursor_hover_event.dart';
+import 'package:flame/src/game/flame_game.dart';
+import 'package:flutter/gestures.dart';
+import 'package:flutter/services.dart';
+import 'package:meta/meta.dart';
+
+@internal
+class CursorHoverDispatcher extends Component {
+  bool _eventHandlerRegistered = false;
+  FlameGame get game => parent! as FlameGame;
+
+  @mustCallSuper
+  void onMouseMove(CursorHoverEvent event) {
+    event.deliverAtPoint(
+      rootComponent: game,
+      eventHandler: (CursorHoverCallbacks component) {
+        component.onMouseMove(event);
+      },
+    );
+  }
+
+  @internal
+  void handleMouseMove(int pointerId, PointerHoverEvent pointerHoverEvent) {
+    onMouseMove(CursorHoverEvent(pointerId, pointerHoverEvent));
+  }
+
+  @override
+  void onMount() {
+    if (game.firstChild<CursorHoverDispatcher>() == null) {
+      // TODO: Add detector to game
+      // game.gestureDetectors.add(
+      //   PointerHoverEventListener.new,
+      //   () {},
+      // );
+    } else {
+      removeFromParent();
+    }
+  }
+}

packages/flame/lib/src/events/messages/cursor_hover_event.dart

@@ -0,0 +1,34 @@
+import 'package:flame/image_composition.dart';
+import 'package:flame/src/events/messages/position_event.dart';
+import 'package:flame/src/game/game.dart';
+import 'package:flame/src/gestures/events.dart';
+
+import 'package:flutter/gestures.dart';
+
+class CursorHoverEvent extends PositionEvent {
+  CursorHoverEvent(this.pointerId, PointerHoverEvent pointerHoverEvent)
+      : deviceKind = pointerHoverEvent.kind,
+        super(
+          canvasPosition: pointerHoverEvent.localPosition.toVector2(),
+          devicePosition: pointerHoverEvent.position.toVector2(),
+        );
+
+  final int pointerId;
+
+  final PointerDeviceKind deviceKind;
+
+  PointerHoverInfo asInfo(Game game) {
+    return PointerHoverInfo.fromDetails(
+      game,
+      PointerHoverEvent(
+        position: devicePosition.toOffset(),
+        kind: deviceKind,
+      ),
+    );
+  }
+
+  @override
+  String toString() => 'CursorHoverEvent(canvasPosition: $canvasPosition, '
+      'devicePosition: $devicePosition, '
+      'pointerId: $pointerId, deviceKind: $deviceKind)';
+}