refactor!: Remove events handled property

doc/flame/migration.md

@@ -7,6 +7,58 @@ major versions of Flame, together with the steps required to migrate your code.
 ## Migrating from v1.38.0 to v2.0.0
 
 
+### `Event.handled` removed in favour of `continuePropagation`
+
+Events used to carry two independent booleans: `handled`, which Flame never set nor read, and
+`continuePropagation`, which actually controls whether an event keeps traversing down the component
+tree. The former has been removed; `continuePropagation` is now the single propagation flag on every
+event.
+
+By default, an event stops at the first component that can handle it, so a component that "consumes"
+an event does not need to do anything at all — the components below it will not see it:
+
+```dart
+// Before
+class Square extends RectangleComponent with TapCallbacks {
+  @override
+  void onTapDown(TapDownEvent event) {
+    removeFromParent();
+    event.handled = true;
+  }
+}
+
+class MyWorld extends World with TapCallbacks {
+  @override
+  void onTapDown(TapDownEvent event) {
+    if (!event.handled) {
+      add(Square(event.localPosition));
+    }
+  }
+}
+
+// After
+class Square extends RectangleComponent with TapCallbacks {
+  @override
+  void onTapDown(TapDownEvent event) {
+    removeFromParent();
+  }
+}
+
+class MyWorld extends World with TapCallbacks {
+  @override
+  void onTapDown(TapDownEvent event) {
+    add(Square(event.localPosition));
+  }
+}
+```
+
+If you were using `handled` to let an event reach several components, set
+`event.continuePropagation = true` in the components that should pass it along instead.
+
+The equivalent field on the deprecated `*Info` event classes (`TapDownInfo.handled` and friends) has
+been removed as well.
+
+
 ### `GameWidget.controlled` renamed to `GameWidget.managed`
 
 The `GameWidget.controlled` constructor has been renamed to `GameWidget.managed`. The behavior is

packages/flame/example/lib/main.dart

@@ -26,10 +26,7 @@ class MyWorld extends World with TapCallbacks {
   @override
   void onTapDown(TapDownEvent event) {
     super.onTapDown(event);
-    if (!event.handled) {
-      final touchPoint = event.localPosition;
-      add(Square(touchPoint));
-    }
+    add(Square(event.localPosition));
   }
 }
 
@@ -77,6 +74,5 @@ class Square extends RectangleComponent with TapCallbacks {
   @override
   void onTapDown(TapDownEvent event) {
     removeFromParent();
-    event.handled = true;
   }
 }

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

@@ -14,14 +14,6 @@ abstract class Event<R> {
   /// The original Flutter raw event that triggered this Flame event.
   R raw;
 
-  /// Flag that can be used to indicate that the event was handled by one of the
-  /// components.
-  ///
-  /// This flag is neither set nor read by Flame. Instead, it can be set by the
-  /// user in a component that handles an event, and then read by the user in a
-  /// different component, or at the root Game level.
-  bool handled = false;
-
   /// If this flag is false (default), the event will be delivered to the first
   /// component that can handle it. If that component sets this flag to true,
   /// the event will propagate further down the component tree to other eligible

packages/flame/lib/src/gestures/events.dart

@@ -61,14 +61,14 @@ abstract class PositionInfo<T> extends BaseInfo<T> {
   ) : super(raw);
 }
 
-class TapDownInfo extends PositionInfo<TapDownDetails> with _HandledField {
+class TapDownInfo extends PositionInfo<TapDownDetails> {
   TapDownInfo.fromDetails(
     Game game,
     TapDownDetails raw,
   ) : super(game, raw.globalPosition, raw);
 }
 
-class TapUpInfo extends PositionInfo<TapUpDetails> with _HandledField {
+class TapUpInfo extends PositionInfo<TapUpDetails> {
   TapUpInfo.fromDetails(
     Game game,
     TapUpDetails raw,
@@ -116,8 +116,7 @@ class PointerScrollInfo extends PositionInfo<PointerScrollEvent> {
   ) : super(game, raw.position, raw);
 }
 
-class PointerHoverInfo extends PositionInfo<PointerHoverEvent>
-    with _HandledField {
+class PointerHoverInfo extends PositionInfo<PointerHoverEvent> {
   PointerHoverInfo.fromDetails(
     Game game,
     PointerHoverEvent raw,
@@ -131,15 +130,14 @@ class DragDownInfo extends PositionInfo<DragDownDetails> {
   ) : super(game, raw.globalPosition, raw);
 }
 
-class DragStartInfo extends PositionInfo<DragStartDetails> with _HandledField {
+class DragStartInfo extends PositionInfo<DragStartDetails> {
   DragStartInfo.fromDetails(
     Game game,
     DragStartDetails raw,
   ) : super(game, raw.globalPosition, raw);
 }
 
-class DragUpdateInfo extends PositionInfo<DragUpdateDetails>
-    with _HandledField {
+class DragUpdateInfo extends PositionInfo<DragUpdateDetails> {
   late final EventDelta delta = EventDelta(raw.delta);
 
   DragUpdateInfo.fromDetails(
@@ -148,7 +146,7 @@ class DragUpdateInfo extends PositionInfo<DragUpdateDetails>
   ) : super(game, raw.globalPosition, raw);
 }
 
-class DragEndInfo extends BaseInfo<DragEndDetails> with _HandledField {
+class DragEndInfo extends BaseInfo<DragEndDetails> {
   late final Vector2 velocity = raw.velocity.pixelsPerSecond.toVector2();
   double? get primaryVelocity => raw.primaryVelocity;
 
@@ -185,7 +183,3 @@ class ScaleUpdateInfo extends PositionInfo<ScaleUpdateDetails> {
     ScaleUpdateDetails raw,
   ) : super(game, raw.focalPoint, raw);
 }
-
-mixin _HandledField {
-  bool handled = false;
-}

packages/flame/test/events/component_mixins/input_test_helper.dart

@@ -22,7 +22,6 @@ mixin DragCounter on DragCallbacks {
   @override
   void onDragStart(DragStartEvent event) {
     super.onDragStart(event);
-    event.handled = true;
     dragStartEvent++;
     if (_wasDragged != isDragged) {
       ++isDraggedStateChange;
@@ -33,14 +32,12 @@ mixin DragCounter on DragCallbacks {
   @override
   void onDragUpdate(DragUpdateEvent event) {
     super.onDragUpdate(event);
-    event.handled = true;
     dragUpdateEvent++;
   }
 
   @override
   void onDragEnd(DragEndEvent event) {
     super.onDragEnd(event);
-    event.handled = true;
     dragEndEvent++;
     if (_wasDragged != isDragged) {
       ++isDraggedStateChange;
@@ -51,7 +48,6 @@ mixin DragCounter on DragCallbacks {
   @override
   void onDragCancel(DragCancelEvent event) {
     super.onDragCancel(event);
-    event.handled = true;
     dragCancelEvent++;
   }
 }
@@ -69,7 +65,6 @@ mixin ScaleCounter on ScaleCallbacks {
   void onScaleStart(ScaleStartEvent event) {
     super.onScaleStart(event);
     expect(event.raw, isNotNull);
-    event.handled = true;
     scaleStartEvent++;
     if (_wasScaled != isScaling) {
       ++isScaledStateChange;
@@ -81,15 +76,13 @@ mixin ScaleCounter on ScaleCallbacks {
   void onScaleUpdate(ScaleUpdateEvent event) {
     super.onScaleUpdate(event);
     expect(event.raw, isNotNull);
-    event.handled = true;
     scaleUpdateEvent++;
   }
 
   @override
   void onScaleEnd(ScaleEndEvent event) {
     super.onScaleEnd(event);
     expect(event.raw, isNotNull);
-    event.handled = true;
     scaleEndEvent++;
     if (_wasScaled != isScaling) {
       ++isScaledStateChange;

packages/flame/test/events/component_mixins/tap_callbacks_test.dart

@@ -540,27 +540,23 @@ mixin _TapCounter on TapCallbacks {
   @override
   void onTapDown(TapDownEvent event) {
     expect(event.raw, isNotNull);
-    event.handled = true;
     tapDownEvent++;
   }
 
   @override
   void onLongTapDown(TapDownEvent event) {
     expect(event.raw, isNotNull);
-    event.handled = true;
     longTapDownEvent++;
   }
 
   @override
   void onTapUp(TapUpEvent event) {
     expect(event.raw, isNotNull);
-    event.handled = true;
     tapUpEvent++;
   }
 
   @override
   void onTapCancel(TapCancelEvent event) {
-    event.handled = true;
     tapCancelEvent++;
   }
 }

packages/flame_behaviors/example/lib/behaviors/spawning_behavior.dart

@@ -20,9 +20,6 @@ class SpawningBehavior extends TappableBehavior<ExampleGame> {
 
   @override
   void onTapDown(TapDownEvent event) {
-    if (event.handled) {
-      return;
-    }
     parent.add(nextRandomEntity(event.canvasPosition));
   }
 

packages/flame_behaviors/example/lib/entities/circle/behaviors/tapping_behavior.dart

@@ -4,9 +4,11 @@ import 'package:flame_behaviors_example/entities/entities.dart';
 
 /// This behavior ensures that SpawningBehavior of the game does not spawn
 /// anything when we click on a circle (for dragging).
+///
+/// It does so simply by existing: the tap is delivered to this behavior, and
+/// since it does not set `continuePropagation`, it never reaches the game-level
+/// SpawningBehavior underneath.
 class TappingBehavior extends TappableBehavior<Circle> {
   @override
-  void onTapDown(TapDownEvent event) {
-    event.handled = true;
-  }
+  void onTapDown(TapDownEvent event) {}
 }

packages/flame_behaviors/example/lib/entities/rectangle/behaviors/freezing_behavior.dart

@@ -22,6 +22,5 @@ class FreezingBehavior extends TappableBehavior<Rectangle> {
       originalVelocity = movement?.velocity.clone();
       movement?.velocity.setFrom(Vector2.zero());
     }
-    event.handled = true;
   }
 }