Pointer Events

Note

This document describes the new events API. The old (legacy) approach, which is still supported, is described in Gesture Input.

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.

For example:

class MyComponent extends PositionComponent with PointerMoveCallbacks {
  MyComponent() : super(size: Vector2(80, 60));

  @override
  void onPointerMove(PointerMoveEvent event) {
    // Do something in response to the mouse move (e.g. update coordinates)
  }
}

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

By default, each of these methods does 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.

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 you can handle any exit conditions there.

HoverCallbacks

If you want to specifically know if your component is being hovered or not, or if you want to hook into hover enter and exit events, you can use a more dedicated mixin called HoverCallbacks.

For example:

class MyComponent extends PositionComponent with HoverCallbacks {

  MyComponent() : super(size: Vector2(80, 60));

  @override
  void update(double dt) {
    // use `isHovered` to know if the component is being hovered
  }

  @override
  void onHoverEnter() {
    // Do something in response to the mouse entering the component
  }

  @override
  void onHoverExit() {
    // Do something in response to the mouse leaving the component
  }
}

Note that you can still listen to the “raw” onPointerMove methods for additional functionality, just make sure to call the super version to enable the HoverCallbacks behavior.

Hover Demo

Play with the demo below to see the pointer hover events in action.

pointer_events.dart

import 'dart:math';

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

class PointerEventsGame extends FlameGame with TapCallbacks {
  @override
  Future<void> onLoad() async {
    add(HoverTarget(Vector2(100, 200)));
    add(HoverTarget(Vector2(300, 300)));
    add(HoverTarget(Vector2(400, 50)));
  }

  @override
  void onTapDown(TapDownEvent event) {
    add(HoverTarget(event.localPosition));
  }
}

class HoverTarget extends PositionComponent with HoverCallbacks {
  static final Random _random = Random();

  HoverTarget(Vector2 position)
    : super(
        position: position,
        size: Vector2.all(50),
        anchor: Anchor.center,
      );

  final _paint = Paint()
    ..color = HSLColor.fromAHSL(
      1,
      _random.nextDouble() * 360,
      1,
      0.8,
    ).toColor().withValues(alpha: 0.5);

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

  @override
  void onHoverEnter() {
    _paint.color = _paint.color.withValues(alpha: 1);
  }

  @override
  void onHoverExit() {
    _paint.color = _paint.color.withValues(alpha: 0.5);
  }
}

Code

ScrollCallbacks

If you want to handle mouse-wheel or trackpad scroll events at the component level, use the ScrollCallbacks mixin.

class ScrollableSquare extends RectangleComponent with ScrollCallbacks {
  @override
  void onScroll(ScrollEvent event) {
    final factor = switch (event.scrollDelta.y.sign) {
      1 => 0.9,
      -1 => 1.1,
      _ => 1.0, // ignore horizontal-only scrolls
    };
    scale.scale(factor);
    scale.clampScalar(0.3, 5.0);
    event.continuePropagation = false;
  }
}

The mixin adds one overridable method:

• onScroll: called when a scroll event hits the component.

The ScrollEvent provides:

• scrollDelta: a Vector2 with the scroll offset (typically you only need scrollDelta.y).

• canvasPosition / localPosition: the pointer position in canvas and local coordinates.

• continuePropagation: set to false to prevent the event from reaching components further down the hit-test list (or the game itself).

Scroll events are delivered to all components under the pointer (not just the topmost one), unless set continuePropagation = false is set to stop it from bubbling further.

You can also mix ScrollCallbacks directly into your FlameGame to handle scrolling at the game level.

Scroll Demo