feat!: Update scale event with custom recognizer

doc/flame/inputs/drag_events.md

@@ -113,26 +113,39 @@ method must be implemented manually.
 If your component is a part of a larger hierarchy, then it will only receive drag events if its
 ancestors have all implemented the `containsLocalPoint` correctly.
 
-```dart
-class MyComponent extends PositionComponent with DragCallbacks {
-  MyComponent({super.size});
 
-  final _paint = Paint();
-  bool _isDragged = false;
+### isDragged
 
-  @override
-  void onDragStart(DragStartEvent event) => _isDragged = true;
+The `DragCallbacks` mixin provides an `isDragged` getter that returns `true` while the component is
+actively being dragged. This is set to `true` at `onDragStart` and back to `false` at `onDragEnd`.
+It can be used, for example, to change the component's visual appearance during a drag.
+
+
+## Combining with ScaleCallbacks
+
+A component can use both `DragCallbacks` and `ScaleCallbacks` at the same time. When both mixins are
+present, single-finger gestures produce drag events and two-finger gestures produce both drag and
+scale events. This is useful for components that should be draggable with one finger and
+pinch-to-zoom or rotatable with two fingers.
+
+```dart
+class InteractiveRect extends RectangleComponent
+    with ScaleCallbacks, DragCallbacks {
 
   @override
-  void onDragUpdate(DragUpdateEvent event) => position += event.delta;
+  void onDragUpdate(DragUpdateEvent event) {
+    position += event.localDelta;
+  }
 
   @override
-  void onDragEnd(DragEndEvent event) => _isDragged = false;
+  void onScaleStart(ScaleStartEvent event) {
+    super.onScaleStart(event);
+    // store initial angle/scale for relative updates
+  }
 
   @override
-  void render(Canvas canvas) {
-    _paint.color = _isDragged? Colors.red : Colors.white;
-    canvas.drawRect(size.toRect(), _paint);
+  void onScaleUpdate(ScaleUpdateEvent event) {
+    angle = initialAngle + event.rotation;
   }
 }
 ```

doc/flame/inputs/inputs.md

@@ -10,6 +10,7 @@ works, but adapted for Flame's component tree.
 
 - [Tap Events](tap_events.md)
 - [Drag Events](drag_events.md)
+- [Scale Events](scale_events.md)
 - [Long Press Events](long_press_events.md)
 - [Gesture Input](gesture_input.md)
 - [Keyboard Input](keyboard_input.md)
@@ -22,6 +23,7 @@ works, but adapted for Flame's component tree.
 
 Tap Events                <tap_events.md>
 Drag Events               <drag_events.md>
+Scale Events              <scale_events.md>
 Long Press Events         <long_press_events.md>
 Gesture Input             <gesture_input.md>
 Keyboard Input            <keyboard_input.md>

doc/flame/inputs/scale_events.md

@@ -100,85 +100,40 @@ method must be implemented manually.
 If your component is a part of a larger hierarchy, then it will only receive scale events if its
 ancestors have all implemented the `containsLocalPoint` correctly.
 
+
+### isScaling
+
+The `ScaleCallbacks` mixin provides an `isScaling` getter that returns `true` while the component is
+actively being scaled. This is set to `true` at the start of `onScaleStart` and back to `false` at
+`onScaleEnd`. It can be used, for example, to change the component's visual appearance during a scale
+gesture.
+
+
+## Combining with DragCallbacks
+
+A component can use both `ScaleCallbacks` and `DragCallbacks` at the same time. When both mixins are
+present, single-finger gestures produce drag events and two-finger gestures produce both scale and
+drag events. This is useful for components that should be draggable with one finger and
+pinch-to-zoom or rotatable with two fingers.
+
 ```dart
-class ScaleOnlyRectangle extends RectangleComponent with ScaleCallbacks {
-  ScaleOnlyRectangle({
-    required Vector2 position,
-    required Vector2 size,
-    Color color = Colors.blue,
-    Anchor anchor = Anchor.center,
-  }) : super(
-         position: position,
-         size: size,
-         anchor: anchor,
-         paint: Paint()..color = color,
-       );
+class InteractiveRect extends RectangleComponent
+    with ScaleCallbacks, DragCallbacks {
 
   @override
-  Future<void> onLoad() async {
-    final text = TextComponent(
-      text: 'scale',
-      textRenderer: TextPaint(
-        style: const TextStyle(fontSize: 25, color: Colors.white),
-      ),
-      position: size / 2,
-      anchor: Anchor.center,
-    );
-    add(text);
+  void onDragUpdate(DragUpdateEvent event) {
+    position += event.localDelta;
   }
 
-  bool isScaling = false;
-  double initialAngle = 0;
-  Vector2 initialScale = Vector2.all(1);
-  double lastScale = 1.0;
-
-  /// ScaleCallbacks overrides
   @override
   void onScaleStart(ScaleStartEvent event) {
     super.onScaleStart(event);
-    isScaling = true;
-    initialAngle = angle;
-    initialScale = scale;
-    lastScale = 1.0;
-    debugPrint('Scale started at ${event.devicePosition}');
+    // store initial angle/scale for relative updates
   }
 
   @override
   void onScaleUpdate(ScaleUpdateEvent event) {
-    super.onScaleUpdate(event);
-    // scale rectangle size by pinch
     angle = initialAngle + event.rotation;
-    // delta scale since last frame
-    if (lastScale == 0) {
-      return;
-    }
-    final scaleDelta = event.scale / lastScale;
-    lastScale = event.scale; // update for next frame
-
-    // apply delta gently
-    scale *= sqrt(scaleDelta);
-
-    // clamp
-    scale.clamp(Vector2.all(0.8), Vector2.all(3));
-  }
-
-  @override
-  void onScaleEnd(ScaleEndEvent event) {
-    super.onScaleEnd(event);
-    isScaling = false;
-    debugPrint('Scale ended with velocity ${event.velocity}');
   }
 }
-
 ```
-
-
-## Scale and drag gestures interactions
-
-A multi drag gesture can sometimes look exactly like a scale gesture.
-This is the case for instance, if you try to move two components toward each other at the same time.
-If you added both a component using ScaleCallbacks and
-one using DragCallbacks (or one using both), this issue will arise.
-The Scale gesture will win over the drag gesture
-and prevent your user to perform the multi drag gesture as they wanted. This is a limitation
-with the current implementation that devs need to be aware of.