docs: Deprecate TapDetector in favour of TapCallbacks (#2886)

Deprecate `TapDetector` in favour of `TapCallbacks`
This commit is contained in:
Luan Nico
2025-10-02 13:21:05 -07:00
committed by GitHub
parent 36eb3929aa
commit b173697bfb
35 changed files with 90 additions and 83 deletions

View File

@ -21,7 +21,7 @@ void main() async {
runApp(const GameWidget.controlled(gameFactory: SpineExample.new));
}
class FlameSpineExample extends FlameGame with TapDetector {
class FlameSpineExample extends FlameGame {
late final SpineComponent spineboy;
@override

View File

@ -9,7 +9,7 @@ import 'package:flame/palette.dart';
import 'package:flutter/material.dart';
class RayTraceExample extends FlameGame
with HasCollisionDetection, TapDetector {
with HasCollisionDetection, TapCallbacks {
Paint paint = Paint()..color = Colors.red.withValues(alpha: 0.6);
bool isClicked = false;
@ -79,8 +79,7 @@ class RayTraceExample extends FlameGame
}
@override
void onTap() {
super.onTap();
void onTapUp(TapUpEvent event) {
if (!isClicked) {
isClicked = true;
return;

View File

@ -4,7 +4,7 @@ import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
class RemoveEffectGame extends FlameGame with TapDetector {
class RemoveEffectGame extends FlameGame with TapCallbacks {
static const double delayTime = 3;
late EmberPlayer ember;
late TextComponent textComponent;
@ -22,7 +22,7 @@ class RemoveEffectGame extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapUp(TapUpEvent event) {
if (children.contains(ember)) {
ember.add(effect);
} else {

View File

@ -4,7 +4,7 @@ import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame_rive/flame_rive.dart';
class RiveExampleGame extends FlameGame with TapDetector {
class RiveExampleGame extends FlameGame with TapCallbacks {
late SMIInput<double>? levelInput;
@override
@ -26,8 +26,7 @@ class RiveExampleGame extends FlameGame with TapDetector {
}
@override
void onTap() {
super.onTap();
void onTapDown(_) {
if (levelInput != null) {
levelInput!.value = (levelInput!.value + 1) % 3;
}

View File

@ -64,7 +64,6 @@ Countdown example:
```dart
import 'package:flame/components.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class MyGame extends Game {
@ -99,7 +98,6 @@ Interval example:
```dart
import 'package:flame/components.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class MyGame extends Game {

View File

@ -1,15 +1,15 @@
import 'dart:ui';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
enum RobotState {
idle,
running,
}
class AnimationGroupExample extends FlameGame with TapDetector {
class AnimationGroupExample extends FlameGame with TapCallbacks {
static const description = '''
This example shows how to create a component that can be switched between
different states to change the animation that is playing.\n\n
@ -59,7 +59,7 @@ class AnimationGroupExample extends FlameGame with TapDetector {
}
@override
void onTapCancel() {
void onTapCancel(_) {
robot.current = RobotState.idle;
}

View File

@ -3,7 +3,7 @@ import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame_spine/flame_spine.dart';
class FlameSpineExample extends FlameGame with TapDetector {
class FlameSpineExample extends FlameGame with TapCallbacks {
static const String description = '''
This example shows how to load a Spine animation. Tap on the screen to try
different states of the animation.
@ -45,7 +45,7 @@ class FlameSpineExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
_stateIndex = (_stateIndex + 1) % states.length;
spineboy.animationState.setAnimationByName(0, states[_stateIndex], true);
}

View File

@ -4,7 +4,7 @@ import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame_spine/flame_spine.dart';
class SharedDataSpineExample extends FlameGame with TapDetector {
class SharedDataSpineExample extends FlameGame with TapCallbacks {
static const String description = '''
This example shows how to preload assets and share data between Spine
components.
@ -45,7 +45,7 @@ class SharedDataSpineExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
for (final spineboy in spineboys) {
spineboy.animationState.setAnimationByName(0, 'jump', false);
spineboy.animationState.setListener((type, track, event) {

View File

@ -10,7 +10,7 @@ import 'package:flame/palette.dart';
import 'package:flutter/material.dart';
class RaycastLightExample extends FlameGame
with HasCollisionDetection, TapDetector, MouseMovementDetector {
with HasCollisionDetection, TapCallbacks, MouseMovementDetector {
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
@ -88,9 +88,8 @@ with with mouse.
}
@override
void onTapDown(TapDownInfo info) {
super.onTapDown(info);
final origin = info.eventPosition.widget;
void onTapDown(TapDownEvent event) {
final origin = event.canvasPosition;
isTapOriginCasted = origin == tapOrigin;
tapOrigin = origin;
}

View File

@ -9,11 +9,7 @@ import 'package:flame/palette.dart';
import 'package:flutter/material.dart';
class RaytraceExample extends FlameGame
with
HasCollisionDetection,
TapDetector,
MouseMovementDetector,
TapDetector {
with HasCollisionDetection, MouseMovementDetector, 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
@ -54,8 +50,9 @@ bounce on will appear.
bool isClicked = false;
final extraChildren = <Component>[];
@override
void onTap() {
void onTapDown(_) {
if (!isClicked) {
isClicked = true;
return;

View File

@ -4,10 +4,9 @@ import 'package:flame/events.dart';
import 'package:flame/experimental.dart';
import 'package:flame/extensions.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flame/math.dart';
class SpawnComponentExample extends FlameGame with TapDetector {
class SpawnComponentExample extends FlameGame {
static const String description =
'Tap on the screen to start spawning Embers within different shapes.';

View File

@ -2,10 +2,9 @@ import 'package:examples/commons/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class ColorEffectExample extends FlameGame with TapDetector {
class ColorEffectExample extends FlameGame {
static const String description = '''
In this example we show how the `ColorEffect` can be used.
Ember will constantly pulse in and out of a blue color.

View File

@ -1,10 +1,10 @@
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class DualEffectRemovalExample extends FlameGame with TapDetector {
class DualEffectRemovalExample extends FlameGame with TapCallbacks {
static const String description = '''
In this example we show how a dual effect can be used and removed.
To remove an effect, tap anywhere on the screen and the first tap will
@ -48,7 +48,7 @@ class DualEffectRemovalExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
// apply(0) sends the animation to its initial starting state.
// If this isn't called, the effect would be removed and leave the
// component at its current state.

View File

@ -1,14 +1,14 @@
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
enum RobotState {
idle,
running,
}
class FunctionEffectExample extends FlameGame with TapDetector {
class FunctionEffectExample extends FlameGame with TapCallbacks {
static const String description = '''
This example shows how to use the FunctionEffect to create custom effects.

View File

@ -1,14 +1,14 @@
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
void main() {
runApp(GameWidget(game: GlowEffectExample()));
}
class GlowEffectExample extends FlameGame with TapDetector {
class GlowEffectExample extends FlameGame with TapCallbacks {
static const String description = '''
In this example we show how the `GlowEffect` can be used.
''';

View File

@ -1,10 +1,10 @@
import 'package:examples/commons/ember.dart';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
class OpacityEffectExample extends FlameGame with TapDetector {
class OpacityEffectExample extends FlameGame with TapCallbacks {
static const String description = '''
In this example we show how the `OpacityEffect` can be used in two ways.
The left Ember will constantly pulse in and out of opacity and the right
@ -41,7 +41,7 @@ class OpacityEffectExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
final opacity = sprite.paint.color.a;
if (opacity >= 0.5) {
sprite.add(OpacityEffect.fadeOut(EffectController(duration: 1)));

View File

@ -3,13 +3,13 @@ import 'dart:ui';
import 'package:flame/components.dart';
import 'package:flame/effects.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/animation.dart';
class ScaleEffectExample extends FlameGame with TapDetector {
class ScaleEffectExample extends FlameGame with TapCallbacks {
static const String description = '''
In this example you can tap the screen and the component will scale up or
down, depending on its current state.
@ -56,7 +56,7 @@ class ScaleEffectExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
final s = grow ? 3.0 : 1.0;
grow = !grow;

View File

@ -2,12 +2,12 @@ import 'dart:ui';
import 'package:flame/components.dart';
import 'package:flame/effects.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flame/palette.dart';
import 'package:flutter/animation.dart';
class SizeEffectExample extends FlameGame with TapDetector {
class SizeEffectExample extends FlameGame with TapCallbacks {
static const String description = '''
The `SizeEffect` changes the size of the component, the sizes of the
children will stay the same.
@ -31,7 +31,7 @@ class SizeEffectExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
shape.add(
SizeEffect.to(
Vector2.all(grow ? 300.0 : 100.0),

View File

@ -1,9 +1,10 @@
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
class NineTileBoxCustomGridExample extends FlameGame
with TapDetector, DoubleTapDetector {
with TapCallbacks, DoubleTapDetector {
static const String description = '''
If you want to create a background for something that can stretch you can
use the `NineTileBox` which is showcased here. In this example a custom
@ -35,7 +36,7 @@ class NineTileBoxCustomGridExample extends FlameGame
}
@override
void onTap() {
void onTapDown(_) {
nineTileBoxComponent.scale.scale(1.2);
}

View File

@ -1,8 +1,9 @@
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
class NineTileBoxExample extends FlameGame with TapDetector, DoubleTapDetector {
class NineTileBoxExample extends FlameGame
with TapCallbacks, DoubleTapDetector {
static const String description = '''
If you want to create a background for something that can stretch you can
use the `NineTileBox` which is showcased here.\n\n
@ -27,7 +28,7 @@ class NineTileBoxExample extends FlameGame with TapDetector, DoubleTapDetector {
}
@override
void onTap() {
void onTapDown(_) {
nineTileBoxComponent.scale.scale(1.2);
}

View File

@ -1,10 +1,10 @@
import 'package:dashbook/dashbook.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class OverlaysExample extends FlameGame with TapDetector {
class OverlaysExample extends FlameGame with TapCallbacks {
static const String description = '''
In this example we show how the overlays system can be used.\n\n
If you tap the canvas the game will start and if you tap it again it will
@ -37,7 +37,11 @@ class OverlaysExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
toggleMenu();
}
void toggleMenu() {
if (overlays.isActive('PauseMenu')) {
overlays.remove('PauseMenu');
resumeEngine();
@ -98,7 +102,7 @@ Widget overlayBuilder(DashbookContext ctx) {
'PauseMenu': (context, game) => _pauseMenuBuilder(
context,
game,
() => game.onTap(),
() => game.toggleMenu(),
),
'SecondaryMenu': _secondaryMenuBuilder,
},

View File

@ -1,8 +1,10 @@
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
class PauseResumeExample extends FlameGame with TapDetector, DoubleTapDetector {
class PauseResumeExample extends FlameGame
with TapCallbacks, DoubleTapDetector {
static const description = '''
Demonstrate how to use the pause and resume engine methods and paused
attribute.
@ -36,7 +38,7 @@ class PauseResumeExample extends FlameGame with TapDetector, DoubleTapDetector {
}
@override
void onTap() {
void onTapDown(_) {
if (paused) {
resumeEngine();
} else {

View File

@ -1,10 +1,10 @@
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class TimerComponentExample extends FlameGame
with TapDetector, DoubleTapDetector {
with TapCallbacks, DoubleTapDetector {
static const String description = '''
This examples showcases the `TimerComponent`.\n\n
Tap to start a timer that lives for one second and double tap to start
@ -15,7 +15,7 @@ class TimerComponentExample extends FlameGame
RenderedTimeComponent? doubleTapComponent;
@override
void onTap() {
void onTapDown(_) {
tapComponent?.removeFromParent();
tapComponent = RenderedTimeComponent(1);
add(tapComponent!);

View File

@ -1,9 +1,9 @@
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flame/timer.dart';
import 'package:flutter/material.dart';
class TimerExample extends FlameGame with TapDetector {
class TimerExample extends FlameGame with TapCallbacks {
static const String description = '''
This example shows how to use the `Timer`.\n\n
Tap down to start the countdown timer, it will then count to 5 and then stop

View File

@ -1,10 +1,10 @@
import 'package:dashbook/dashbook.dart';
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flutter/material.dart';
class CustomPainterExample extends FlameGame with TapDetector {
class CustomPainterExample extends FlameGame with TapCallbacks {
static const description = '''
Example demonstration of how to use the CustomPainterComponent.
@ -19,7 +19,7 @@ class CustomPainterExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
if (overlays.isActive('Smiley')) {
overlays.remove('Smiley');
} else {

View File

@ -47,7 +47,6 @@ export 'src/gestures/detectors.dart'
ScrollDetector,
TertiaryTapDetector,
SecondaryTapDetector,
TapDetector,
VerticalDragDetector;
export 'src/gestures/events.dart'
show

View File

@ -10,6 +10,9 @@ import 'package:meta/meta.dart';
/// In addition to adding this mixin, the component must also implement the
/// [containsLocalPoint] method -- the component will only be considered
/// "tapped" if the point where the tap has occurred is inside the component.
///
/// Note that FlameGame _is_ a [Component] and does implement
/// [containsLocalPoint]; so this can be used at the game level.
mixin TapCallbacks on Component {
void onTapDown(TapDownEvent event) {}
void onLongTapDown(TapDownEvent event) {}

View File

@ -1,4 +1,5 @@
import 'package:flame/events.dart';
import 'package:flame/input.dart';
import 'package:flame/src/game/game.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter/widgets.dart';
@ -48,12 +49,16 @@ class GestureDetectorBuilder {
}
void initializeGestures(Game game) {
// support for deprecated detectors
// ignore: deprecated_member_use_from_same_package
if (game is TapDetector ||
game is SecondaryTapDetector ||
game is TertiaryTapDetector) {
add(
TapGestureRecognizer.new,
(TapGestureRecognizer instance) {
// support for deprecated detectors
// ignore: deprecated_member_use_from_same_package
if (game is TapDetector) {
instance.onTap = game.onTap;
instance.onTapCancel = game.onTapCancel;

View File

@ -2,7 +2,7 @@ import 'package:flame/src/game/game.dart';
import 'package:flame/src/gestures/events.dart';
import 'package:flutter/gestures.dart';
// Basic touch detectors
@Deprecated('Use TapCallbacks instead')
mixin TapDetector on Game {
void onTap() {}
void onTapCancel() {}

View File

@ -5,6 +5,8 @@ import 'package:flame/input.dart';
import 'package:flame_test/flame_test.dart';
import 'package:flutter_test/flutter_test.dart';
// testing the deprecated TapDetector
// ignore: deprecated_member_use_from_same_package
class _TapGame extends FlameGame with TapDetector {
bool tapRegistered = false;

View File

@ -1,5 +1,6 @@
import 'package:flame/events.dart' hide PointerMoveEvent;
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flame_test/flame_test.dart';
import 'package:flutter/gestures.dart';
import 'package:flutter_test/flutter_test.dart';
@ -777,6 +778,8 @@ void main() {
});
}
// testing the deprecated TapDetector mixin
// ignore: deprecated_member_use_from_same_package
class _TapDetectorGame extends FlameGame with TapDetector {
bool hasOnTapUp = false;
bool hasOnTapDown = false;

View File

@ -2,7 +2,6 @@ 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/palette.dart';
import 'package:flame_audio/flame_audio.dart';
import 'package:flutter/widgets.dart' hide Animation;
@ -18,7 +17,7 @@ void main() {
/// 2. Uses a custom AudioPool for extremely efficient audio loading and pooling
/// for tapping elsewhere.
/// 3. Uses the Bgm utility for background music.
class AudioGame extends FlameGame with TapDetector {
class AudioGame extends FlameGame with TapCallbacks {
static final Paint black = BasicPalette.black.paint();
static final Paint gray = const PaletteEntry(Color(0xFFCCCCCC)).paint();
static final TextPaint text = TextPaint(
@ -75,8 +74,8 @@ class AudioGame extends FlameGame with TapDetector {
}
@override
void onTapDown(TapDownInfo info) {
if (button.containsPoint(info.eventPosition.widget)) {
void onTapDown(TapDownEvent event) {
if (button.containsPoint(event.canvasPosition)) {
fireTwo();
} else {
fireOne();

View File

@ -1,7 +1,6 @@
import 'package:flame/components.dart';
import 'package:flame/events.dart';
import 'package:flame/game.dart';
import 'package:flame/input.dart';
import 'package:flame_fire_atlas/flame_fire_atlas.dart';
import 'package:flutter/material.dart';
@ -12,7 +11,7 @@ void main() {
runApp(GameWidget(game: game));
}
class ExampleGame extends FlameGame with TapDetector {
class ExampleGame extends FlameGame with TapCallbacks {
late FireAtlas _atlas;
@override
@ -53,7 +52,7 @@ class ExampleGame extends FlameGame with TapDetector {
}
@override
void onTapUp(TapUpInfo info) {
void onTapUp(TapUpEvent event) {
add(
SpriteAnimationComponent(
size: Vector2(100, 100),
@ -61,7 +60,7 @@ class ExampleGame extends FlameGame with TapDetector {
removeOnFinish: true,
)
..anchor = Anchor.center
..position = info.eventPosition.widget,
..position = event.canvasPosition,
);
}
}

View File

@ -4,7 +4,6 @@ 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_network_assets/flame_network_assets.dart';
import 'package:flutter/material.dart' hide Image;
@ -12,7 +11,7 @@ void main() {
runApp(const GameWidget.controlled(gameFactory: MyGame.new));
}
class MyGame extends FlameGame with TapDetector {
class MyGame extends FlameGame with TapCallbacks {
final networkImages = FlameNetworkImages();
late Image playerSprite;
@ -24,7 +23,7 @@ class MyGame extends FlameGame with TapDetector {
}
@override
void onTapUp(TapUpInfo info) {
void onTapUp(TapUpEvent event) {
add(
SpriteAnimationComponent.fromFrameData(
playerSprite,
@ -35,7 +34,7 @@ class MyGame extends FlameGame with TapDetector {
),
size: Vector2(100, 50),
anchor: Anchor.center,
position: info.eventPosition.widget,
position: event.canvasPosition,
),
);
}

View File

@ -10,7 +10,7 @@ void main() async {
runApp(const GameWidget.controlled(gameFactory: SpineExample.new));
}
class SpineExample extends FlameGame with TapDetector {
class SpineExample extends FlameGame with TapCallbacks {
late final SpineComponent spineboy;
final states = [
@ -46,7 +46,7 @@ class SpineExample extends FlameGame with TapDetector {
}
@override
void onTap() {
void onTapDown(_) {
_stateIndex = (_stateIndex + 1) % states.length;
spineboy.animationState.setAnimationByName(0, states[_stateIndex], true);
}