diff --git a/doc/flame/inputs/gesture_input.md b/doc/flame/inputs/gesture_input.md index b4f92ee07e9..55feed89991 100644 --- a/doc/flame/inputs/gesture_input.md +++ b/doc/flame/inputs/gesture_input.md @@ -1,9 +1,15 @@ # Gesture Input -This is documentation for the legacy detector mixins, which are added directly to your game class. -New code should prefer the `Callbacks` mixins instead (e.g. [TapCallbacks](tap_events.md) and -[DragCallbacks](drag_events.md)) which can be added to any `Component`, including the `FlameGame` -itself. +Gesture input in Flame is handled by the `Callbacks` mixins. They can be added to any `Component`, +and since `FlameGame` is itself a `Component`, adding one to your game class works exactly as well — +no wrapper component required. Each family has its own page: + +- [Tap Events](tap_events.md): `TapCallbacks`, `DoubleTapCallbacks`, and the secondary/tertiary + button variants +- [Drag Events](drag_events.md): `DragCallbacks` +- [Scale Events](scale_events.md): `ScaleCallbacks` +- [Long Press Events](long_press_events.md): `LongPressCallbacks` +- [Pointer Events](pointer_events.md): `MouseMoveCallbacks`, `HoverCallbacks`, `ScrollCallbacks` For other input documents, see also: @@ -11,17 +17,16 @@ For other input documents, see also: - [Other Inputs](other_inputs.md): For joysticks, game pads, etc. -## Intro - -Inside `package:flame/input.dart` you can find a set of legacy `mixin`s which can be included on -your game class instance to be able to receive touch input events. Below you can see the full -list of these `mixin`s and its methods: +## PanDetector - -## Touch and mouse detectors +`PanDetector` is the last remaining detector mixin — the older style of input handling, added +directly to the game class instead of to a component. Everything else on that side has already been +replaced by the `Callbacks` mixins above. ```{warning} -Detectors will be deprecated in the future. Prefer `Callbacks` instead. +`PanDetector` will be removed. Prefer [`DragCallbacks`](drag_events.md), which +can be added to your `FlameGame` directly and additionally reports a +`pointerId` so that simultaneous drags can be told apart. ``` ```text @@ -33,14 +38,6 @@ Detectors will be deprecated in the future. Prefer `Callbacks` instead. - onPanCancel ``` -Mouse only events - -```text - - MouseMovementDetector - - onMouseMove -``` - - Flame's GestureApi is provided by Flutter's Gesture Widgets, including [GestureDetector widget](https://api.flutter.dev/flutter/widgets/GestureDetector-class.html), [RawGestureDetector widget](https://api.flutter.dev/flutter/widgets/RawGestureDetector-class.html) @@ -147,22 +144,3 @@ class MyGame extends FlameGame with PanDetector { } } ``` - - -### GestureHitboxes - -The `GestureHitboxes` mixin is used to more accurately recognize gestures on top of your -`Component`s. Say that you have a fairly round rock as a `SpriteComponent` for example, then you -don't want to register input that is in the corner of the image where the rock is not displayed, -since a `PositionComponent` is rectangular by default. Then you can use the `GestureHitboxes` mixin -to define a more accurate circle or polygon (or another shape) for which the input should be within -for the event to be registered on your component. - -You can add new hitboxes to the component that has the `GestureHitboxes` mixin just like they are -added in the below `Collidable` example. - -More information about how to define hitboxes can be found in the hitbox section of the -[collision detection](../collision_detection.md#shapehitbox) docs. - -An example of how to use it can be seen in the -[gesture hitboxes example](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/input/gesture_hitboxes_example.dart). diff --git a/doc/flame/inputs/inputs.md b/doc/flame/inputs/inputs.md index d3acefbee83..2176243e037 100644 --- a/doc/flame/inputs/inputs.md +++ b/doc/flame/inputs/inputs.md @@ -18,6 +18,27 @@ works, but adapted for Flame's component tree. - [Pointer Events](pointer_events.md) - [Hardware Keyboard Detector](hardware_keyboard_detector.md) + +## GestureHitboxes + +Every mixin whose events carry a position implements `PointerInputCallbacks` — that is all of the +above except keyboard — and they all decide whether an event belongs to a component by asking its +`containsLocalPoint()`, which for a `PositionComponent` is its rectangular bounds. The +`GestureHitboxes` mixin is used to recognize input on top of your `Component`s more accurately than +that. Say that you have a fairly round rock as a `SpriteComponent` for example, then you don't want +to register input that is in the corner of the image where the rock is not displayed. Then you can +use the `GestureHitboxes` mixin to define a more accurate circle or polygon (or another shape) for +which the input should be within for the event to be registered on your component. + +You can add new hitboxes to the component that has the `GestureHitboxes` mixin just like they are +added in the `Collidable` example. + +More information about how to define hitboxes can be found in the hitbox section of the +[collision detection](../collision_detection.md#shapehitbox) docs. + +An example of how to use it can be seen in the +[gesture hitboxes example](https://github.com/flame-engine/flame/blob/main/examples/lib/stories/input/gesture_hitboxes_example.dart). + ```{toctree} :hidden: diff --git a/doc/flame/inputs/pointer_events.md b/doc/flame/inputs/pointer_events.md index 7c7f46e7aaa..39b38110e48 100644 --- a/doc/flame/inputs/pointer_events.md +++ b/doc/flame/inputs/pointer_events.md @@ -8,16 +8,16 @@ which is still supported, is described in [](gesture_input.md). **Pointer events** are Flutter's generalized "mouse-movement"-type events (for desktop or web). If you want to interact with mouse movement events within your component or game, you can use the -`PointerMoveCallbacks` mixin. +`MouseMoveCallbacks` mixin. For example: ```dart -class MyComponent extends PositionComponent with PointerMoveCallbacks { +class MyComponent extends PositionComponent with MouseMoveCallbacks { MyComponent() : super(size: Vector2(80, 60)); @override - void onPointerMove(PointerMoveEvent event) { + void onMouseMove(MouseMoveEvent event) { // Do something in response to the mouse move (e.g. update coordinates) } } @@ -25,8 +25,8 @@ class MyComponent extends PositionComponent with PointerMoveCallbacks { The mixin adds two overridable methods to your component: -- `onPointerMove`: called when the mouse moves within the component -- `onPointerMoveStop`: called once if the component was being hovered and the mouse leaves +- `onMouseMove`: called when the mouse moves within the component +- `onMouseMoveStop`: called once if the component was being hovered and the mouse leaves By default, each of these methods does nothing, they need to be overridden in order to perform any function. @@ -36,7 +36,7 @@ In addition, the component must implement the `containsLocalPoint()` method (alr Flame to know whether the event occurred within the component or not. Note that only mouse events happening within your component will be proxied along. However, -`onPointerMoveStop` will be fired once on the first mouse movement that leaves your component, so +`onMouseMoveStop` will be fired once on the first mouse movement that leaves your component, so you can handle any exit conditions there. @@ -69,7 +69,7 @@ class MyComponent extends PositionComponent with HoverCallbacks { } ``` -Note that you can still listen to the "raw" onPointerMove methods for additional functionality, just +Note that you can still listen to the "raw" onMouseMove methods for additional functionality, just make sure to call the `super` version to enable the `HoverCallbacks` behavior. diff --git a/doc/flame/migration.md b/doc/flame/migration.md index 17bf96f38a9..0cd8e7450b1 100644 --- a/doc/flame/migration.md +++ b/doc/flame/migration.md @@ -251,6 +251,63 @@ scrolls that occur on top of it, as determined by `containsLocalPoint()`. Mixing See [Pointer Events](inputs/pointer_events.md) for the full replacement API. +### `MouseMovementDetector` removed and `PointerMove*` renamed to `MouseMove*` + +The `MouseMovementDetector` game mixin has been removed, together with the event class that only it +used. At the same time, the component-level API it is replaced by has been renamed from `PointerMove` +to `MouseMove`: + +| Removed / renamed | Use instead | +| --- | --- | +| `MouseMovementDetector` | `MouseMoveCallbacks` | +| `PointerHoverInfo` | `MouseMoveEvent` | +| `PointerMoveCallbacks` | `MouseMoveCallbacks` | +| `PointerMoveEvent` | `MouseMoveEvent` | +| `PointerMoveDispatcher` | `MouseMoveDispatcher` | +| `onPointerMove` | `onMouseMove` | +| `onPointerMoveStop` | `onMouseMoveStop` | + +The rename has two reasons. Flame's `PointerMoveEvent` collided with Flutter's class of the same +name, forcing a `hide` on any file that imported both `package:flame/events.dart` and +`package:flutter/material.dart`. And "mouse move" is simply more accurate: the event wraps Flutter's +`PointerHoverEvent` and is delivered from a `MouseRegion`, so it is mouse movement specifically, not +pointer movement in general. `MouseMoveDispatcherKey` was already named this way. + +Migrating from the detector, the callback keeps its `onMouseMove` name and only the parameter +changes, with the position read directly off the event instead of through the nested `eventPosition` +wrapper: + +```dart +// Before +class MyGame extends FlameGame with MouseMovementDetector { + @override + void onMouseMove(PointerHoverInfo info) { + target = info.eventPosition.widget; + } +} + +// After +class MyGame extends FlameGame with MouseMoveCallbacks { + @override + void onMouseMove(MouseMoveEvent event) { + target = event.canvasPosition; + } +} +``` + +Unlike the old detector, which received every mouse movement anywhere on the game surface, +`MouseMoveCallbacks` is routed by position like the other component callbacks: a component only +receives movements that occur on top of it, as determined by `containsLocalPoint()`. Mixing it into +your `FlameGame` subclass directly, as above, keeps the old whole-surface behavior. +`MouseMoveCallbacks` additionally offers `onMouseMoveStop`, which has no equivalent on the old +detector. + +`flame_test`'s `createMouseMoveEvent` helper now returns a `MouseMoveEvent`, and if you were using +`flame_behaviors`, note that it no longer re-exports the legacy `*Info` event classes. + +See [Pointer Events](inputs/pointer_events.md) for the full replacement API. + + ### `onDragCancel` no longer delegates to `onDragEnd` `DragCallbacks.onDragCancel` used to convert the cancellation into an `onDragEnd` event by default, diff --git a/examples/lib/stories/bridge_libraries/flame_forge2d/raycast_example.dart b/examples/lib/stories/bridge_libraries/flame_forge2d/raycast_example.dart index cbfb075c803..c2bd48585e8 100644 --- a/examples/lib/stories/bridge_libraries/flame_forge2d/raycast_example.dart +++ b/examples/lib/stories/bridge_libraries/flame_forge2d/raycast_example.dart @@ -5,11 +5,10 @@ import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/boundaries import 'package:examples/stories/bridge_libraries/flame_forge2d/utils/style.dart'; import 'package:flame/components.dart'; import 'package:flame/events.dart'; -import 'package:flame/input.dart'; import 'package:flame_forge2d/flame_forge2d.dart'; import 'package:flutter/material.dart' show Colors, Paint, Canvas; -class RaycastExample extends Forge2DExampleGame with MouseMovementDetector { +class RaycastExample extends Forge2DExampleGame with MouseMoveCallbacks { static const String description = ''' This example shows how ray casts can be used to find the nearest and farthest shapes. @@ -57,7 +56,7 @@ class RaycastExample extends Forge2DExampleGame with MouseMovementDetector { } @override - void onMouseMove(PointerHoverInfo info) { + void onMouseMove(MouseMoveEvent event) { final rayStart = screenToWorld( Vector2( camera.viewport.size.x / 4, @@ -65,14 +64,14 @@ class RaycastExample extends Forge2DExampleGame with MouseMovementDetector { ), ); - final worldPosition = screenToWorld(info.eventPosition.widget); + final worldPosition = screenToWorld(event.canvasPosition); final redRayTarget = worldPosition + Vector2(0, 2); fireRedRay(rayStart, redRayTarget); final blueRayTarget = worldPosition - Vector2(0, 2); fireBlueRay(rayStart, blueRayTarget); - super.onMouseMove(info); + super.onMouseMove(event); } void fireBlueRay(Vector2 rayStart, Vector2 rayTarget) { diff --git a/examples/lib/stories/collision_detection/raycast_light_example.dart b/examples/lib/stories/collision_detection/raycast_light_example.dart index b76c4c150f0..a970cf502fa 100644 --- a/examples/lib/stories/collision_detection/raycast_light_example.dart +++ b/examples/lib/stories/collision_detection/raycast_light_example.dart @@ -5,12 +5,11 @@ import 'package:flame/components.dart'; import 'package:flame/events.dart'; import 'package:flame/game.dart'; import 'package:flame/geometry.dart'; -import 'package:flame/input.dart'; import 'package:flame/palette.dart'; import 'package:flutter/material.dart'; class RaycastLightExample extends FlameGame - with HasCollisionDetection, TapCallbacks, MouseMovementDetector { + with HasCollisionDetection, TapCallbacks, MouseMoveCallbacks { static const description = ''' In this example the raycast functionality is showcased by using it as a light source, if you move the mouse around the canvas the rays will be cast from its @@ -95,8 +94,8 @@ with with mouse. } @override - void onMouseMove(PointerHoverInfo info) { - final origin = info.eventPosition.widget; + void onMouseMove(MouseMoveEvent event) { + final origin = event.canvasPosition; isOriginCasted = origin == this.origin; this.origin = origin; } diff --git a/examples/lib/stories/collision_detection/raytrace_example.dart b/examples/lib/stories/collision_detection/raytrace_example.dart index fd51e47948f..a96f2d6224c 100644 --- a/examples/lib/stories/collision_detection/raytrace_example.dart +++ b/examples/lib/stories/collision_detection/raytrace_example.dart @@ -9,7 +9,7 @@ import 'package:flame/palette.dart'; import 'package:flutter/material.dart'; class RaytraceExample extends FlameGame - with HasCollisionDetection, MouseMovementDetector, TapCallbacks { + with HasCollisionDetection, MouseMoveCallbacks, TapCallbacks { static const description = ''' In this example the raytrace functionality is showcased. Click to start sending out a ray which will bounce around to visualize how it @@ -124,8 +124,8 @@ bounce on will appear. } @override - void onMouseMove(PointerHoverInfo info) { - final origin = info.eventPosition.widget; + void onMouseMove(MouseMoveEvent event) { + final origin = event.canvasPosition; isOriginCasted = origin == this.origin; this.origin = origin; } diff --git a/examples/lib/stories/input/mouse_cursor_example.dart b/examples/lib/stories/input/mouse_cursor_example.dart index c352d5dcce3..7c704ccde63 100644 --- a/examples/lib/stories/input/mouse_cursor_example.dart +++ b/examples/lib/stories/input/mouse_cursor_example.dart @@ -1,12 +1,11 @@ import 'package:flame/events.dart'; import 'package:flame/extensions.dart'; import 'package:flame/game.dart'; -import 'package:flame/input.dart'; import 'package:flame/palette.dart'; import 'package:flutter/material.dart'; import 'package:flutter/widgets.dart'; -class MouseCursorExample extends FlameGame with MouseMovementDetector { +class MouseCursorExample extends FlameGame with MouseMoveCallbacks { static const String description = ''' Example showcasing the ability to change the game cursor in runtime hover the little square to see the cursor changing @@ -23,8 +22,8 @@ class MouseCursorExample extends FlameGame with MouseMovementDetector { bool onTarget = false; @override - void onMouseMove(PointerHoverInfo info) { - target = info.eventPosition.widget; + void onMouseMove(MouseMoveEvent event) { + target = event.canvasPosition; } Rect _toRect() => position.toPositionedRect(objSize); diff --git a/examples/lib/stories/input/mouse_movement_example.dart b/examples/lib/stories/input/mouse_movement_example.dart index 7864dba6d1b..701fb054209 100644 --- a/examples/lib/stories/input/mouse_movement_example.dart +++ b/examples/lib/stories/input/mouse_movement_example.dart @@ -1,13 +1,12 @@ import 'package:flame/events.dart'; import 'package:flame/extensions.dart'; import 'package:flame/game.dart'; -import 'package:flame/input.dart'; import 'package:flame/palette.dart'; import 'package:flutter/material.dart'; -class MouseMovementExample extends FlameGame with MouseMovementDetector { +class MouseMovementExample extends FlameGame with MouseMoveCallbacks { static const String description = ''' - In this example we show how you can use `MouseMovementDetector`.\n\n + In this example we show how you can use `MouseMoveCallbacks`.\n\n Move around the mouse on the canvas and the white square will follow it and turn into blue if it reaches the mouse, or the edge of the canvas. '''; @@ -23,8 +22,8 @@ class MouseMovementExample extends FlameGame with MouseMovementDetector { bool onTarget = false; @override - void onMouseMove(PointerHoverInfo info) { - target = info.eventPosition.widget; + void onMouseMove(MouseMoveEvent event) { + target = event.canvasPosition; } Rect _toRect() => position.toPositionedRect(objSize); diff --git a/examples/lib/stories/rendering/isometric_tile_map_example.dart b/examples/lib/stories/rendering/isometric_tile_map_example.dart index d80cf0751af..9313f891d24 100644 --- a/examples/lib/stories/rendering/isometric_tile_map_example.dart +++ b/examples/lib/stories/rendering/isometric_tile_map_example.dart @@ -4,10 +4,9 @@ import 'package:flame/components.dart'; import 'package:flame/events.dart'; import 'package:flame/extensions.dart'; import 'package:flame/game.dart'; -import 'package:flame/input.dart'; import 'package:flame/sprite.dart'; -class IsometricTileMapExample extends FlameGame with MouseMovementDetector { +class IsometricTileMapExample extends FlameGame with MouseMoveCallbacks { static const String description = ''' Shows an example of how to use the `IsometricTileMapComponent`.\n\n Move the mouse over the board to see a selector appearing on the tiles. @@ -72,8 +71,8 @@ class IsometricTileMapExample extends FlameGame with MouseMovementDetector { } @override - void onMouseMove(PointerHoverInfo info) { - final screenPosition = info.eventPosition.widget; + void onMouseMove(MouseMoveEvent event) { + final screenPosition = event.canvasPosition; final block = base.getBlock(screenPosition); selector.show = base.containsBlock(block); selector.position.setFrom(topLeft + base.getBlockRenderPosition(block)); diff --git a/packages/flame/lib/events.dart b/packages/flame/lib/events.dart index 6edee55237a..5ad9b802d0e 100644 --- a/packages/flame/lib/events.dart +++ b/packages/flame/lib/events.dart @@ -3,10 +3,9 @@ export 'src/events/callbacks/drag_callbacks.dart' show DragCallbacks; export 'src/events/callbacks/hover_callbacks.dart' show HoverCallbacks; export 'src/events/callbacks/input_callbacks.dart' show InputCallbacks; export 'src/events/callbacks/long_press_callbacks.dart' show LongPressCallbacks; +export 'src/events/callbacks/mouse_move_callbacks.dart' show MouseMoveCallbacks; export 'src/events/callbacks/pointer_input_callbacks.dart' show PointerInputCallbacks; -export 'src/events/callbacks/pointer_move_callbacks.dart' - show PointerMoveCallbacks; export 'src/events/callbacks/scale_callbacks.dart' show ScaleCallbacks; export 'src/events/callbacks/scroll_callbacks.dart' show ScrollCallbacks; export 'src/events/callbacks/secondary_tap_callbacks.dart' @@ -19,14 +18,14 @@ export 'src/events/dispatchers/double_tap_dispatcher.dart' show DoubleTapDispatcher, DoubleTapDispatcherKey; export 'src/events/dispatchers/long_press_dispatcher.dart' show LongPressDispatcher, LongPressDispatcherKey; +export 'src/events/dispatchers/mouse_move_dispatcher.dart' + show MouseMoveDispatcher, MouseMoveDispatcherKey; export 'src/events/dispatchers/multi_drag_scale_dispatcher.dart' show MultiDragScaleDispatcher, MultiDragScaleDispatcherKey; export 'src/events/dispatchers/multi_tap_dispatcher.dart' show MultiTapDispatcher, MultiTapDispatcherKey; export 'src/events/dispatchers/non_primary_tap_dispatcher.dart' show NonPrimaryTapDispatcher, NonPrimaryTapDispatcherKey; -export 'src/events/dispatchers/pointer_move_dispatcher.dart' - show PointerMoveDispatcher, MouseMoveDispatcherKey; export 'src/events/dispatchers/scroll_dispatcher.dart' show ScrollDispatcher, ScrollDispatcherKey; export 'src/events/hardware_keyboard_detector.dart' @@ -53,7 +52,7 @@ export 'src/events/messages/long_press_move_update_event.dart' show LongPressMoveUpdateEvent; export 'src/events/messages/long_press_start_event.dart' show LongPressStartEvent; -export 'src/events/messages/pointer_move_event.dart' show PointerMoveEvent; +export 'src/events/messages/mouse_move_event.dart' show MouseMoveEvent; export 'src/events/messages/position_event.dart' show PositionEvent; export 'src/events/messages/scale_end_event.dart' show ScaleEndEvent; export 'src/events/messages/scale_start_event.dart' show ScaleStartEvent; @@ -77,14 +76,13 @@ export 'src/events/multi_drag_scale_recognizer.dart' show MultiDragScaleGestureRecognizer; export 'src/game/mixins/keyboard.dart' show HasKeyboardHandlerComponents, KeyboardEvents; -export 'src/gestures/detectors.dart' show MouseMovementDetector, PanDetector; +export 'src/gestures/detectors.dart' show PanDetector; export 'src/gestures/events.dart' show DragDownInfo, DragEndInfo, DragStartInfo, DragUpdateInfo, - PointerHoverInfo, PositionInfo, TapDownInfo, TapUpInfo; diff --git a/packages/flame/lib/src/events/callbacks/hover_callbacks.dart b/packages/flame/lib/src/events/callbacks/hover_callbacks.dart index b57cbedff72..9957e8e4db7 100644 --- a/packages/flame/lib/src/events/callbacks/hover_callbacks.dart +++ b/packages/flame/lib/src/events/callbacks/hover_callbacks.dart @@ -12,8 +12,8 @@ import 'package:meta/meta.dart'; /// /// This mixin is the replacement of the Hoverable mixin. /// -/// This callback uses [PointerMoveDispatcher] to route events. -mixin HoverCallbacks on Component implements PointerMoveCallbacks { +/// This callback uses [MouseMoveDispatcher] to route events. +mixin HoverCallbacks on Component implements MouseMoveCallbacks { bool _isHovered = false; /// Returns true while the component is being dragged. @@ -43,7 +43,7 @@ mixin HoverCallbacks on Component implements PointerMoveCallbacks { onHoverExit(); } - /// Called by [PointerMoveDispatcher] when a pointer button is pressed while + /// Called by [MouseMoveDispatcher] when a pointer button is pressed while /// this component is hovered. Not intended to be called by user code. @internal void cancelHover() { @@ -54,7 +54,7 @@ mixin HoverCallbacks on Component implements PointerMoveCallbacks { } @override - void onPointerMove(PointerMoveEvent event) { + void onMouseMove(MouseMoveEvent event) { final position = event.localPosition; if (containsLocalPoint(position)) { if (!_isHovered) { @@ -68,7 +68,7 @@ mixin HoverCallbacks on Component implements PointerMoveCallbacks { } @override - void onPointerMoveStop(PointerMoveEvent event) { + void onMouseMoveStop(MouseMoveEvent event) { if (_isHovered) { _doHoverExit(); } @@ -78,6 +78,6 @@ mixin HoverCallbacks on Component implements PointerMoveCallbacks { @mustCallSuper void onMount() { super.onMount(); - PointerMoveDispatcher.addDispatcher(this); + MouseMoveDispatcher.addDispatcher(this); } } diff --git a/packages/flame/lib/src/events/callbacks/mouse_move_callbacks.dart b/packages/flame/lib/src/events/callbacks/mouse_move_callbacks.dart new file mode 100644 index 00000000000..8ea7f8fd41e --- /dev/null +++ b/packages/flame/lib/src/events/callbacks/mouse_move_callbacks.dart @@ -0,0 +1,20 @@ +import 'package:flame/components.dart'; +import 'package:flame/events.dart'; +import 'package:meta/meta.dart'; + +/// This mixin can be added to a [Component] allowing it to receive +/// mouse movement events. +/// +/// This callback uses [MouseMoveDispatcher] to route events. +mixin MouseMoveCallbacks on Component implements PointerInputCallbacks { + void onMouseMove(MouseMoveEvent event) {} + + void onMouseMoveStop(MouseMoveEvent event) {} + + @override + @mustCallSuper + void onMount() { + super.onMount(); + MouseMoveDispatcher.addDispatcher(this); + } +} diff --git a/packages/flame/lib/src/events/callbacks/pointer_move_callbacks.dart b/packages/flame/lib/src/events/callbacks/pointer_move_callbacks.dart deleted file mode 100644 index bb7b81452e0..00000000000 --- a/packages/flame/lib/src/events/callbacks/pointer_move_callbacks.dart +++ /dev/null @@ -1,20 +0,0 @@ -import 'package:flame/components.dart'; -import 'package:flame/events.dart'; -import 'package:meta/meta.dart'; - -/// This mixin can be added to a [Component] allowing it to receive -/// pointer movement events. -/// -/// This callback uses [PointerMoveDispatcher] to route events. -mixin PointerMoveCallbacks on Component implements PointerInputCallbacks { - void onPointerMove(PointerMoveEvent event) {} - - void onPointerMoveStop(PointerMoveEvent event) {} - - @override - @mustCallSuper - void onMount() { - super.onMount(); - PointerMoveDispatcher.addDispatcher(this); - } -} diff --git a/packages/flame/lib/src/events/dispatchers/pointer_move_dispatcher.dart b/packages/flame/lib/src/events/dispatchers/mouse_move_dispatcher.dart similarity index 72% rename from packages/flame/lib/src/events/dispatchers/pointer_move_dispatcher.dart rename to packages/flame/lib/src/events/dispatchers/mouse_move_dispatcher.dart index 02802c4bb79..5b9552423af 100644 --- a/packages/flame/lib/src/events/dispatchers/pointer_move_dispatcher.dart +++ b/packages/flame/lib/src/events/dispatchers/mouse_move_dispatcher.dart @@ -6,41 +6,41 @@ import 'package:flutter/gestures.dart' as flutter; import 'package:meta/meta.dart'; /// **MouseMoveDispatcher** facilitates dispatching of mouse move events to the -/// [PointerMoveCallbacks] components in the component tree. It will be attached +/// [MouseMoveCallbacks] components in the component tree. It will be attached /// to the [FlameGame] instance automatically whenever any -/// [PointerMoveCallbacks] components are mounted into the component tree. -class PointerMoveDispatcher extends Dispatcher { +/// [MouseMoveCallbacks] components are mounted into the component tree. +class MouseMoveDispatcher extends Dispatcher { /// The record of all components currently being hovered. - final Set> _records = {}; + final Set> _records = {}; @mustCallSuper - void onMouseMove(PointerMoveEvent event) { - final updated = >{}; + void onMouseMove(MouseMoveEvent event) { + final updated = >{}; event.deliverAtPoint( rootComponent: game, deliverToAll: true, - eventHandler: (PointerMoveCallbacks component) { + eventHandler: (MouseMoveCallbacks component) { final tagged = TaggedComponent(event.pointerId, component); _records.add(tagged); updated.add(tagged); - component.onPointerMove(event); + component.onMouseMove(event); }, ); - final toRemove = >{}; + final toRemove = >{}; for (final record in _records) { if (record.pointerId == event.pointerId && !updated.contains(record)) { // one last "exit" event - record.component.onPointerMoveStop(event); + record.component.onMouseMoveStop(event); toRemove.add(record); } } _records.removeAll(toRemove); } - void _handlePointerMove(flutter.PointerHoverEvent event) { - onMouseMove(PointerMoveEvent.fromPointerHoverEvent(game, event)); + void _handleMouseMove(flutter.PointerHoverEvent event) { + onMouseMove(MouseMoveEvent.fromPointerHoverEvent(game, event)); } /// Cancels the hover on every currently-hovered [HoverCallbacks] tracked by @@ -49,7 +49,7 @@ class PointerMoveDispatcher extends Dispatcher { /// without this hook hovered components would never learn the hover ended. /// See issue #2741. void _handlePointerPress(flutter.PointerDownEvent _) { - final cancelled = >[]; + final cancelled = >[]; for (final record in _records) { final component = record.component; if (component is HoverCallbacks && component.isHovered) { @@ -64,13 +64,13 @@ class PointerMoveDispatcher extends Dispatcher { Dispatcher.addDispatcher( component, const MouseMoveDispatcherKey(), - PointerMoveDispatcher.new, + MouseMoveDispatcher.new, ); } @override void onMount() { - game.mouseDetector = _handlePointerMove; + game.mouseDetector = _handleMouseMove; game.mousePressDetector = _handlePointerPress; } diff --git a/packages/flame/lib/src/events/messages/pointer_move_event.dart b/packages/flame/lib/src/events/messages/mouse_move_event.dart similarity index 80% rename from packages/flame/lib/src/events/messages/pointer_move_event.dart rename to packages/flame/lib/src/events/messages/mouse_move_event.dart index a9dbac76c8a..e5c8d574165 100644 --- a/packages/flame/lib/src/events/messages/pointer_move_event.dart +++ b/packages/flame/lib/src/events/messages/mouse_move_event.dart @@ -3,8 +3,8 @@ import 'package:flame/extensions.dart'; import 'package:flame/game.dart'; import 'package:flutter/services.dart'; -class PointerMoveEvent extends PositionEvent { - PointerMoveEvent( +class MouseMoveEvent extends PositionEvent { + MouseMoveEvent( this.pointerId, super.game, PointerHoverEvent rawEvent, @@ -28,16 +28,16 @@ class PointerMoveEvent extends PositionEvent { @override String toString() => - 'PointerMoveEvent(devicePosition: $devicePosition, ' + 'MouseMoveEvent(devicePosition: $devicePosition, ' 'canvasPosition: $canvasPosition, ' 'delta: $delta, ' 'pointerId: $pointerId, timestamp: $timestamp)'; - factory PointerMoveEvent.fromPointerHoverEvent( + factory MouseMoveEvent.fromPointerHoverEvent( Game game, PointerHoverEvent event, ) { - return PointerMoveEvent( + return MouseMoveEvent( event.pointer, game, event, diff --git a/packages/flame/lib/src/game/game.dart b/packages/flame/lib/src/game/game.dart index 38044e86bf9..87d9fdf56e4 100644 --- a/packages/flame/lib/src/game/game.dart +++ b/packages/flame/lib/src/game/game.dart @@ -38,7 +38,7 @@ abstract mixin class Game { refreshWidget, )..initializeGestures(this); - /// Set by the PointerMoveDispatcher to receive mouse events from the + /// Set by the MouseMoveDispatcher to receive mouse events from the /// game widget. void Function(PointerHoverEvent event)? get mouseDetector => _mouseDetector; void Function(PointerHoverEvent event)? _mouseDetector; @@ -47,7 +47,7 @@ abstract mixin class Game { refreshWidget(); } - /// Set by the PointerMoveDispatcher to receive mouse press events from the + /// Set by the MouseMoveDispatcher to receive mouse press events from the /// game widget so it can fire `onHoverCancel` on hovered `HoverCallbacks` /// components when the user presses a button while hovering. void Function(PointerDownEvent event)? get mousePressDetector => diff --git a/packages/flame/lib/src/game/game_widget/gesture_detector_builder.dart b/packages/flame/lib/src/game/game_widget/gesture_detector_builder.dart index 5d83f2e6e45..1cda759442d 100644 --- a/packages/flame/lib/src/game/game_widget/gesture_detector_builder.dart +++ b/packages/flame/lib/src/game/game_widget/gesture_detector_builder.dart @@ -60,14 +60,12 @@ class GestureDetectorBuilder { } bool hasMouseDetectors(Game game) { - return game is MouseMovementDetector || - game.mouseDetector != null || + return game.mouseDetector != null || game.mousePressDetector != null || game.scrollDetector != null; } Widget applyMouseDetectors(Game game, Widget child) { - final mouseMoveFn = game is MouseMovementDetector ? game.onMouseMove : null; final mouseDetector = game.mouseDetector; final mousePressDetector = game.mousePressDetector; final scrollDetector = game.scrollDetector; @@ -83,10 +81,7 @@ Widget applyMouseDetectors(Game game, Widget child) { } }, child: MouseRegion( - onHover: (PointerHoverEvent e) { - mouseMoveFn?.call(PointerHoverInfo.fromDetails(game, e)); - mouseDetector?.call(e); - }, + onHover: mouseDetector, child: child, ), ); diff --git a/packages/flame/lib/src/gestures/detectors.dart b/packages/flame/lib/src/gestures/detectors.dart index c8d5671bb16..55c3bdd2d10 100644 --- a/packages/flame/lib/src/gestures/detectors.dart +++ b/packages/flame/lib/src/gestures/detectors.dart @@ -25,7 +25,3 @@ mixin PanDetector on Game { onPanEnd(DragEndInfo.fromDetails(details)); } } - -mixin MouseMovementDetector on Game { - void onMouseMove(PointerHoverInfo info) {} -} diff --git a/packages/flame/lib/src/gestures/events.dart b/packages/flame/lib/src/gestures/events.dart index 9eab2054ca1..b4ce0149e2d 100644 --- a/packages/flame/lib/src/gestures/events.dart +++ b/packages/flame/lib/src/gestures/events.dart @@ -75,13 +75,6 @@ class TapUpInfo extends PositionInfo { ) : super(game, raw.globalPosition, raw); } -class PointerHoverInfo extends PositionInfo { - PointerHoverInfo.fromDetails( - Game game, - PointerHoverEvent raw, - ) : super(game, raw.position, raw); -} - class DragDownInfo extends PositionInfo { DragDownInfo.fromDetails( Game game, diff --git a/packages/flame/test/events/component_mixins/hover_callbacks_test.dart b/packages/flame/test/events/component_mixins/hover_callbacks_test.dart index c93c8be1dcf..e9060346c8c 100644 --- a/packages/flame/test/events/component_mixins/hover_callbacks_test.dart +++ b/packages/flame/test/events/component_mixins/hover_callbacks_test.dart @@ -100,7 +100,7 @@ void main() { } void _mouseEvent(FlameGame game, Vector2 position) { - game.firstChild()!.onMouseMove( + game.firstChild()!.onMouseMove( createMouseMoveEvent( game: game, position: position, @@ -110,7 +110,7 @@ void _mouseEvent(FlameGame game, Vector2 position) { void _hasDispatcher(FlameGame game) { expect( - game.children.whereType(), + game.children.whereType(), hasLength(1), ); } diff --git a/packages/flame/test/events/component_mixins/input_test_helper.dart b/packages/flame/test/events/component_mixins/input_test_helper.dart index 110782e3a7f..84bb0df6446 100644 --- a/packages/flame/test/events/component_mixins/input_test_helper.dart +++ b/packages/flame/test/events/component_mixins/input_test_helper.dart @@ -1,5 +1,5 @@ import 'package:flame/components.dart'; -import 'package:flame/events.dart' hide PointerMoveEvent; +import 'package:flame/events.dart'; import 'package:flame/game.dart'; import 'package:flutter/gestures.dart'; import 'package:flutter_test/flutter_test.dart'; diff --git a/packages/flame/test/events/component_mixins/pointer_move_callbacks_test.dart b/packages/flame/test/events/component_mixins/mouse_move_callbacks_test.dart similarity index 74% rename from packages/flame/test/events/component_mixins/pointer_move_callbacks_test.dart rename to packages/flame/test/events/component_mixins/mouse_move_callbacks_test.dart index b5af07a35ab..025618fcad5 100644 --- a/packages/flame/test/events/component_mixins/pointer_move_callbacks_test.dart +++ b/packages/flame/test/events/component_mixins/mouse_move_callbacks_test.dart @@ -5,11 +5,11 @@ import 'package:flame_test/flame_test.dart'; import 'package:flutter_test/flutter_test.dart'; void main() { - group('PointerMoveCallbacks', () { + group('MouseMoveCallbacks', () { testWithFlameGame( - 'make sure PointerMoveCallbacks components can be added to a FlameGame', + 'make sure MouseMoveCallbacks components can be added to a FlameGame', (game) async { - await game.ensureAdd(_PointerMoveCallbacksComponent()); + await game.ensureAdd(_MouseMoveCallbacksComponent()); await game.ready(); _hasDispatcher(game); @@ -17,12 +17,12 @@ void main() { ); testWithFlameGame('receive pointer move events on component', (game) async { - final c1 = _PointerMoveCallbacksComponent( + final c1 = _MouseMoveCallbacksComponent( position: Vector2.all(10), size: Vector2.all(10), ); game.add(c1); - final c2 = _PointerMoveCallbacksComponent( + final c2 = _MouseMoveCallbacksComponent( position: Vector2.all(15), size: Vector2.all(10), ); @@ -51,7 +51,7 @@ void main() { testWithGame( 'receive pointer move events on game', - _PointerMoveCallbacksGame.new, + _MouseMoveCallbacksGame.new, (game) async { _hasDispatcher(game); @@ -72,7 +72,7 @@ void main() { } void _mouseEvent(FlameGame game, Vector2 position) { - game.firstChild()!.onMouseMove( + game.firstChild()!.onMouseMove( createMouseMoveEvent( game: game, position: position, @@ -82,12 +82,12 @@ void _mouseEvent(FlameGame game, Vector2 position) { void _hasDispatcher(FlameGame game) { expect( - game.children.whereType(), + game.children.whereType(), hasLength(1), ); } -mixin _PointerMoveInspector on PointerMoveCallbacks { +mixin _MouseMoveInspector on MouseMoveCallbacks { List receivedEventsAt = []; Vector2 removeSingle() { @@ -96,19 +96,19 @@ mixin _PointerMoveInspector on PointerMoveCallbacks { } @override - void onPointerMove(PointerMoveEvent event) { + void onMouseMove(MouseMoveEvent event) { expect(event.raw, isNotNull); receivedEventsAt.add(event.localPosition); } } -class _PointerMoveCallbacksComponent extends PositionComponent - with PointerMoveCallbacks, _PointerMoveInspector { - _PointerMoveCallbacksComponent({ +class _MouseMoveCallbacksComponent extends PositionComponent + with MouseMoveCallbacks, _MouseMoveInspector { + _MouseMoveCallbacksComponent({ super.position, super.size, }); } -class _PointerMoveCallbacksGame extends FlameGame - with PointerMoveCallbacks, _PointerMoveInspector {} +class _MouseMoveCallbacksGame extends FlameGame + with MouseMoveCallbacks, _MouseMoveInspector {} diff --git a/packages/flame/test/events/component_mixins/scale_callbacks_test.dart b/packages/flame/test/events/component_mixins/scale_callbacks_test.dart index c937cc6b365..b51d05f21a6 100644 --- a/packages/flame/test/events/component_mixins/scale_callbacks_test.dart +++ b/packages/flame/test/events/component_mixins/scale_callbacks_test.dart @@ -1,6 +1,6 @@ import 'dart:math'; -import 'package:flame/events.dart' hide PointerMoveEvent; +import 'package:flame/events.dart'; import 'package:flame/game.dart'; import 'package:flame_test/flame_test.dart'; import 'package:flutter/material.dart'; diff --git a/packages/flame/test/gestures/detectors_test.dart b/packages/flame/test/gestures/detectors_test.dart index 7eeae6d08e9..432fcd26cdb 100644 --- a/packages/flame/test/gestures/detectors_test.dart +++ b/packages/flame/test/gestures/detectors_test.dart @@ -1,4 +1,4 @@ -import 'package:flame/events.dart' hide PointerMoveEvent; +import 'package:flame/events.dart'; import 'package:flame/game.dart'; import 'package:flame_test/flame_test.dart'; import 'package:flutter/gestures.dart'; @@ -66,24 +66,6 @@ void main() { }, ); }); - - group('MouseMovementDetector', () { - final mouseMoveGame = FlameTester(_MouseMovementDetectorGame.new); - - mouseMoveGame.testGameWidget( - 'Can register Mouse movements', - setUp: (game, tester) async { - final gesture = await tester.createGesture( - kind: PointerDeviceKind.mouse, - ); - await gesture.addPointer(location: Offset.zero); - await gesture.moveTo(const Offset(10, 10)); - }, - verify: (game, tester) async { - expect(game.hasReceivedMouseMove, isTrue); - }, - ); - }); } class _PanDetectorGame extends FlameGame with PanDetector { @@ -118,12 +100,3 @@ class _PanDetectorGame extends FlameGame with PanDetector { hasPanStart = true; } } - -class _MouseMovementDetectorGame extends FlameGame with MouseMovementDetector { - bool hasReceivedMouseMove = false; - - @override - void onMouseMove(PointerHoverInfo info) { - hasReceivedMouseMove = true; - } -} diff --git a/packages/flame_behaviors/lib/src/behaviors/events/events.dart b/packages/flame_behaviors/lib/src/behaviors/events/events.dart index ed3c748d50d..5b9edcfacae 100644 --- a/packages/flame_behaviors/lib/src/behaviors/events/events.dart +++ b/packages/flame_behaviors/lib/src/behaviors/events/events.dart @@ -1,12 +1,3 @@ -export 'package:flame/events.dart' - show - DragEndInfo, - DragStartInfo, - DragUpdateInfo, - PointerHoverInfo, - TapDownInfo, - TapUpInfo; - export 'draggable_behavior.dart'; export 'hoverable_behavior.dart'; export 'tappable_behavior.dart'; diff --git a/packages/flame_test/lib/flame_test.dart b/packages/flame_test/lib/flame_test.dart index 5bba88df177..5088cea9feb 100644 --- a/packages/flame_test/lib/flame_test.dart +++ b/packages/flame_test/lib/flame_test.dart @@ -13,7 +13,7 @@ export 'src/flame_test.dart'; export 'src/mock_gesture_events.dart'; export 'src/mock_image.dart'; export 'src/mock_long_press_events.dart'; -export 'src/mock_pointer_move_event.dart'; +export 'src/mock_mouse_move_event.dart'; export 'src/mock_scroll_event.dart'; export 'src/mock_tap_drag_events.dart'; export 'src/random_test.dart'; diff --git a/packages/flame_test/lib/src/mock_pointer_move_event.dart b/packages/flame_test/lib/src/mock_mouse_move_event.dart similarity index 87% rename from packages/flame_test/lib/src/mock_pointer_move_event.dart rename to packages/flame_test/lib/src/mock_mouse_move_event.dart index 4ec13ef1d33..f8c20c39960 100644 --- a/packages/flame_test/lib/src/mock_pointer_move_event.dart +++ b/packages/flame_test/lib/src/mock_mouse_move_event.dart @@ -3,14 +3,14 @@ import 'package:flame/extensions.dart'; import 'package:flame/game.dart'; import 'package:flutter/gestures.dart' as flutter; -PointerMoveEvent createMouseMoveEvent({ +MouseMoveEvent createMouseMoveEvent({ required Game game, int? pointerId, Vector2? position, Vector2? delta, Duration? timestamp, }) { - return PointerMoveEvent( + return MouseMoveEvent( pointerId ?? 1, game, flutter.PointerHoverEvent(