Drag Events

Drag events occur when the user moves their finger across the screen of the device, or when they move the mouse while holding its button down.

Multiple drag events can occur at the same time, if the user is using multiple fingers. Such cases will be handled correctly by Flame, and you can even keep track of the events by using their pointerId property.

For those components that you want to respond to drags, add the DragCallbacks mixin.

• This mixin adds four overridable methods to your component: onDragStart, onDragUpdate, onDragEnd, and onDragCancel. By default, these methods do nothing; they need to be overridden in order to perform any function.

• In addition, the component must implement the containsLocalPoint() method (already implemented in PositionComponent, so most of the time you don’t need to do anything here). This method allows Flame to know whether the event occurred within the component or not.

class MyComponent extends PositionComponent with DragCallbacks {
  MyComponent() : super(size: Vector2(180, 120));

   @override
   void onDragStart(DragStartEvent event) {
     // Do something in response to a drag event
   }
}

Demo

In this example you can use drag gestures to either drag star-like shapes across the screen, or to draw curves inside the magenta rectangle.

drag_events.dart

import 'dart:math';

import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/geometry.dart';
import 'package:flutter/rendering.dart';

class DragEventsGame extends FlameGame {
  @override
  Future<void> onLoad() async {
    addAll([
      DragTarget(),
      Star(
        n: 5,
        radius1: 40,
        radius2: 20,
        sharpness: 0.2,
        color: const Color(0xffbae5ad),
        position: Vector2(70, 70),
      ),
      Star(
        n: 3,
        radius1: 50,
        radius2: 40,
        sharpness: 0.3,
        color: const Color(0xff6ecbe5),
        position: Vector2(70, 160),
      ),
      Star(
        n: 12,
        radius1: 10,
        radius2: 75,
        sharpness: 1.3,
        color: const Color(0xfff6df6a),
        position: Vector2(70, 270),
      ),
      Star(
        n: 10,
        radius1: 20,
        radius2: 17,
        sharpness: 0.85,
        color: const Color(0xfff82a4b),
        position: Vector2(110, 110),
      ),
    ]);
  }
}

/// This component is the pink-ish rectangle in the center of the game window.
/// It uses the [DragCallbacks] mixin in order to receive drag events.
class DragTarget extends PositionComponent with DragCallbacks {
  DragTarget() : super(anchor: Anchor.center);

  final _rectPaint = Paint()..color = const Color(0x88AC54BF);

  /// We will store all current circles into this map, keyed by the `pointerId`
  /// of the event that created the circle.
  final Map<int, Trail> _trails = {};

  @override
  void onGameResize(Vector2 size) {
    super.onGameResize(size);
    this.size = size - Vector2(100, 75);
    if (this.size.x < 100 || this.size.y < 100) {
      this.size = size * 0.9;
    }
    position = size / 2;
  }

  @override
  void render(Canvas canvas) {
    canvas.drawRect(size.toRect(), _rectPaint);
  }

  @override
  void onDragStart(DragStartEvent event) {
    super.onDragStart(event);
    final trail = Trail(event.localPosition);
    _trails[event.pointerId] = trail;
    add(trail);
  }

  @override
  void onDragUpdate(DragUpdateEvent event) {
    _trails[event.pointerId]!.addPoint(event.localEndPosition);
  }

  @override
  void onDragEnd(DragEndEvent event) {
    super.onDragEnd(event);
    _trails.remove(event.pointerId)!.end();
  }

  @override
  void onDragCancel(DragCancelEvent event) {
    super.onDragCancel(event);
    _trails.remove(event.pointerId)!.cancel();
  }
}

class Trail extends Component {
  Trail(Vector2 origin)
    : _paths = [Path()..moveTo(origin.x, origin.y)],
      _opacities = [1],
      _lastPoint = origin.clone(),
      _color = HSLColor.fromAHSL(
        1,
        random.nextDouble() * 360,
        1,
        0.8,
      ).toColor();

  final List<Path> _paths;
  final List<double> _opacities;
  Color _color;
  late final _linePaint = Paint()..style = PaintingStyle.stroke;
  late final _circlePaint = Paint()..color = _color;
  bool _released = false;
  double _timer = 0;
  final _vanishInterval = 0.03;
  final Vector2 _lastPoint;

  static final random = Random();
  static const lineWidth = 10.0;

  @override
  void render(Canvas canvas) {
    assert(_paths.length == _opacities.length);
    for (var i = 0; i < _paths.length; i++) {
      final path = _paths[i];
      final opacity = _opacities[i];
      if (opacity > 0) {
        _linePaint.color = _color.withValues(alpha: opacity);
        _linePaint.strokeWidth = lineWidth * opacity;
        canvas.drawPath(path, _linePaint);
      }
    }
    canvas.drawCircle(
      _lastPoint.toOffset(),
      (lineWidth - 2) * _opacities.last + 2,
      _circlePaint,
    );
  }

  @override
  void update(double dt) {
    assert(_paths.length == _opacities.length);
    _timer += dt;
    while (_timer > _vanishInterval) {
      _timer -= _vanishInterval;
      for (var i = 0; i < _paths.length; i++) {
        _opacities[i] -= 0.01;
        if (_opacities[i] <= 0) {
          _paths[i].reset();
        }
      }
      if (!_released) {
        _paths.add(Path()..moveTo(_lastPoint.x, _lastPoint.y));
        _opacities.add(1);
      }
    }
    if (_opacities.last < 0) {
      removeFromParent();
    }
  }

  void addPoint(Vector2 point) {
    if (!point.x.isNaN) {
      for (final path in _paths) {
        path.lineTo(point.x, point.y);
      }
      _lastPoint.setFrom(point);
    }
  }

  void end() => _released = true;

  void cancel() {
    _released = true;
    _color = const Color(0xFFFFFFFF);
  }
}

class Star extends PositionComponent with DragCallbacks {
  Star({
    required int n,
    required double radius1,
    required double radius2,
    required double sharpness,
    required this.color,
    super.position,
  }) {
    _path = Path()..moveTo(radius1, 0);
    for (var i = 0; i < n; i++) {
      final p1 = Vector2(radius2, 0)..rotate(tau / n * (i + sharpness));
      final p2 = Vector2(radius2, 0)..rotate(tau / n * (i + 1 - sharpness));
      final p3 = Vector2(radius1, 0)..rotate(tau / n * (i + 1));
      _path.cubicTo(p1.x, p1.y, p2.x, p2.y, p3.x, p3.y);
    }
    _path.close();
  }

  final Color color;
  final Paint _paint = Paint();
  final Paint _borderPaint = Paint()
    ..color = const Color(0xFFffffff)
    ..style = PaintingStyle.stroke
    ..strokeWidth = 3;
  final _shadowPaint = Paint()
    ..color = const Color(0xFF000000)
    ..maskFilter = const MaskFilter.blur(BlurStyle.normal, 4.0);
  late final Path _path;

  @override
  bool containsLocalPoint(Vector2 point) {
    return _path.contains(point.toOffset());
  }

  @override
  void render(Canvas canvas) {
    if (isDragged) {
      _paint.color = color.withValues(alpha: 0.5);
      canvas.drawPath(_path, _paint);
      canvas.drawPath(_path, _borderPaint);
    } else {
      _paint.color = color.withValues(alpha: 1);
      canvas.drawPath(_path, _shadowPaint);
      canvas.drawPath(_path, _paint);
    }
  }

  @override
  void onDragStart(DragStartEvent event) {
    super.onDragStart(event);
    priority = 10;
  }

  @override
  void onDragEnd(DragEndEvent event) {
    super.onDragEnd(event);
    priority = 0;
  }

  @override
  void onDragUpdate(DragUpdateEvent event) {
    position += event.localDelta;
  }
}

Code

Drag anatomy

onDragStart

This is the first event that occurs in a drag sequence. Usually, the event will be delivered to the topmost component at the point of touch with the DragCallbacks mixin. However, by setting the flag event.continuePropagation to true, you can allow the event to propagate to the components below.

The DragStartEvent object associated with this event will contain the coordinate of the point where the event has originated. This point is available in multiple coordinate system: devicePosition is given in the coordinate system of the entire device, canvasPosition is in the coordinate system of the game widget, and localPosition provides the position in the component’s local coordinate system.

Any component that receives onDragStart will later be receiving onDragUpdate and onDragEnd events as well.

A drag only starts once the pointer has moved further than the platform’s touch slop from the point where it went down, so a tap with a slightly wobbling finger is still delivered as a tap and not as a drag. When the drag starts, the movement accumulated before that point is delivered in the first onDragUpdate.

onDragUpdate

This event is fired continuously as user drags their finger across the screen. It will not fire if the user is holding their finger still.

The default implementation delivers this event to all the components that received the previous onDragStart with the same pointer id. If the point of touch is still within the component, then event.localPosition will give the position of that point in the local coordinate system. However, if the user moves their finger away from the component, the property event.localPosition will return a point whose coordinates are NaNs. Likewise, the event.renderingTrace in this case will be empty. However, the canvasPosition and devicePosition properties of the event will be valid.

In addition, the DragUpdateEvent will contain delta, the amount the finger has moved since the previous onDragUpdate, or since the onDragStart if this is the first drag-update after a drag-start.

The event.timestamp property measures the time elapsed since the beginning of the drag. It can be used, for example, to compute the speed of the movement.

onDragEnd

This event is fired when the user lifts their finger and thus stops the drag gesture. There is no position associated with this event.

onDragCancel

This event is fired when the drag gesture is interrupted before it ends naturally, for example when another gesture recognizer wins the gesture arena or a second pointer triggers a scale takeover. Unlike onDragEnd it carries no velocity information. The default implementation simply resets the drag state; override it and call onDragEnd(event.toDragEnd()) yourself if you want a cancellation handled identically to a natural drag end.

Mixins

DragCallbacks

The DragCallbacks mixin can be added to any Component in order for that component to start receiving drag events.

This mixin adds methods onDragStart, onDragUpdate, onDragEnd, and onDragCancel to the component, which by default don’t do anything, but can be overridden to implement any real functionality.

Another crucial detail is that a component will only receive drag events that originate within that component, as judged by the containsLocalPoint() function. The commonly-used PositionComponent class provides such an implementation based on its size property. Thus, if your component derives from a PositionComponent, then make sure that you set its size correctly. If, however, your component derives from the bare Component, then the containsLocalPoint() 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.

isDragged

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.

allowsMultiPointerDrag

Drags are tracked per pointer, so a component that is already being dragged will start a second, independent drag when another finger touches it. That is what you want when each drag manipulates something of its own, but not when they all drive a single piece of state (such as a camera or a draggable object), where a second finger just fights the first.

Override allowsMultiPointerDrag to false to accept only one drag at a time:

class MagnifyingGlass extends PositionComponent with DragCallbacks {
  @override
  bool get allowsMultiPointerDrag => false;

  @override
  void onDragUpdate(DragUpdateEvent event) {
    position = event.canvasEndPosition;
  }
}

While a drag is in progress, no other pointer gets an onDragStart on this component, and no onDragUpdate, onDragEnd or onDragCancel follow for it either; the event is offered to the components below instead. Once the accepted drag ends or is cancelled, the component is free to accept a new one.

Control is not handed over: if the accepted pointer is lifted while another is still down, the drag ends rather than continuing on the remaining finger.

This only gates drags. A component that also uses ScaleCallbacks keeps receiving scale events normally, so one-finger drag plus two-finger pinch still works.

Combining with ScaleCallbacks

DragCallbacks and ScaleCallbacks can be used at the same time: single-finger gestures produce drag events, and two-finger gestures produce both drag and scale events. See Combining with DragCallbacks for how to make the two work together, both on a component and for panning and zooming the camera.