Trackpad gestures can trigger GestureRecognizer

Trackpad gestures on most platforms now send PointerPanZoom sequences and can trigger pan, drag, and scale GestureRecognizer callbacks.

Scrolling on Flutter Desktop prior to version 3.3.0 used PointerScrollEvent messages to represent discrete scroll deltas. This system worked well for mouse scroll wheels, but wasn't a good fit for trackpad scrolling. Trackpad scrolling is expected to cause momentum, which depends not only on the scroll deltas, but also the timing of when fingers are released from the trackpad. In addition, trackpad pinching-to-zoom could not be represented.

Three new PointerEvents have been introduced: PointerPanZoomStartEvent, PointerPanZoomUpdateEvent, and PointerPanZoomEndEvent. Relevant GestureRecognizers have been updated to register interest in trackpad gesture sequences, and will emit onDrag, onPan, and/or onScale callbacks in response to movements of two or more fingers on the trackpad.

This means both that code designed only for touch interactions might trigger upon trackpad interaction, and that code designed to handle all desktop scrolling might now only trigger upon mouse scrolling, and not trackpad scrolling.

The Flutter engine has been updated on all possible platforms to recognize trackpad gestures and send them to the framework as PointerPanZoom events instead of as PointerScrollSignal events. PointerScrollSignal events will still be used to represent scrolling on a mouse wheel.

Depending on the platform and specific trackpad model, the new system might not be used, if not enough data is provided to the Flutter engine by platform APIs. This includes on Windows, where trackpad gesture support is dependent on the trackpad's driver, and the Web platform, where not enough data is provided by browser APIs, and trackpad scrolling must still use the old PointerScrollSignal system.

Developers should be prepared to receive both types of events and ensure their apps or packages handle them in the appropriate manner.

Listener now has three new callbacks: onPointerPanZoomStart, onPointerPanZoomUpdate, and onPointerPanZoomEnd which can be used to observe trackpad scrolling and zooming events.

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerSignal: (PointerSignalEvent event) {
        if (event is PointerScrollEvent) {
          debugPrint('mouse scrolled ${event.scrollDelta}');
        }
      },
      onPointerPanZoomStart: (PointerPanZoomStartEvent event) {
        debugPrint('trackpad scroll started');
      },
      onPointerPanZoomUpdate: (PointerPanZoomUpdateEvent event) {
        debugPrint('trackpad scrolled ${event.panDelta}');
      },
      onPointerPanZoomEnd: (PointerPanZoomEndEvent event) {
        debugPrint('trackpad scroll ended');
      },
      child: Container()
    );
  }
}

PointerPanZoomUpdateEvent contains a pan field to represent the cumulative pan of the current gesture, a panDelta field to represent the difference in pan since the last event, a scale event to represent the cumulative zoom of the current gesture, and a rotation event to represent the cumulative rotation (in radians) of the current gesture.

GestureRecognizers now have methods to all the trackpad events from one continuous trackpad gesture. Calling the addPointerPanZoom method on a GestureRecognizer with a PointerPanZoomStartEvent will cause the recognizer to register its interest in that trackpad interaction, and resolve conflicts between multiple GestureRecognizers that could potentially respond to the gesture.

The following example shows the proper use of Listener and GestureRecognizer to respond to trackpad interactions.

dartvoid main() => runApp(Foo());

class Foo extends StatefulWidget {
  late final PanGestureRecognizer recognizer;

  @override
  void initState() {
    super.initState();
    recognizer = PanGestureRecognizer()
    ..onStart = _onPanStart
    ..onUpdate = _onPanUpdate
    ..onEnd = _onPanEnd;
  }

  void _onPanStart(DragStartDetails details) {
    debugPrint('onStart');
  }

  void _onPanUpdate(DragUpdateDetails details) {
    debugPrint('onUpdate');
  }

  void _onPanEnd(DragEndDetails details) {
    debugPrint('onEnd');
  }

  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerDown: recognizer.addPointer,
      onPointerPanZoomStart: recognizer.addPointerPanZoom,
      child: Container()
    );
  }
}

When using GestureDetector, this is done automatically, so code such as the following example will issue its gesture update callbacks in response to both touch and trackpad panning.

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanStart: (details) {
        debugPrint('onStart');
      },
      onPanUpdate: (details) {
        debugPrint('onUpdate');
      },
      onPanEnd: (details) {
        debugPrint('onEnd');
      }
      child: Container()
    );
  }
}

Migration steps depend on whether you want each gesture interaction in your app to be usable via a trackpad, or whether it should be restricted to only touch and mouse usage.

No change is needed, GestureDetector automatically processes trackpad gesture events and triggers callbacks if recognized.

Ensure that onPointerPanZoomStart is passed through to each recognizer from the Listener. The addPointerPanZoom method of `GestureRecognizer must be called for it to show interest and start tracking each trackpad gesture.

Code before migration:

dartvoid main() => runApp(Foo());

class Foo extends StatefulWidget {
  late final PanGestureRecognizer recognizer;

  @override
  void initState() {
    super.initState();
    recognizer = PanGestureRecognizer()
    ..onStart = _onPanStart
    ..onUpdate = _onPanUpdate
    ..onEnd = _onPanEnd;
  }

  void _onPanStart(DragStartDetails details) {
    debugPrint('onStart');
  }

  void _onPanUpdate(DragUpdateDetails details) {
    debugPrint('onUpdate');
  }

  void _onPanEnd(DragEndDetails details) {
    debugPrint('onEnd');
  }

  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerDown: recognizer.addPointer,
      child: Container()
    );
  }
}

Code after migration:

dartvoid main() => runApp(Foo());

class Foo extends StatefulWidget {
  late final PanGestureRecognizer recognizer;

  @override
  void initState() {
    super.initState();
    recognizer = PanGestureRecognizer()
    ..onStart = _onPanStart
    ..onUpdate = _onPanUpdate
    ..onEnd = _onPanEnd;
  }

  void _onPanStart(DragStartDetails details) {
    debugPrint('onStart');
  }

  void _onPanUpdate(DragUpdateDetails details) {
    debugPrint('onUpdate');
  }

  void _onPanEnd(DragEndDetails details) {
    debugPrint('onEnd');
  }

  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerDown: recognizer.addPointer,
      onPointerPanZoomStart: recognizer.addPointerPanZoom,
      child: Container()
    );
  }
}

The following code using PointerScrollSignal will no longer be called upon all desktop scrolling. PointerPanZoomUpdate events should be captured to receive trackpad gesture data.

Code before migration:

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerSignal: (PointerSignalEvent event) {
        if (event is PointerScrollEvent) {
          debugPrint('scroll wheel event');
        }
      }
      child: Container()
    );
  }
}

Code after migration:

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerSignal: (PointerSignalEvent event) {
        if (event is PointerScrollEvent) {
          debugPrint('scroll wheel event');
        }
      },
      onPointerPanZoomUpdate: (PointerPanZoomUpdateEvent event) {
        debugPrint('trackpad scroll event');
      }
      child: Container()
    );
  }
}

Please note: Use of raw Listener in this way could cause conflicts with other gesture interactions as it doesn't participate in the gesture disambiguation arena.

If using Flutter 3.3.0, RawGestureDetector could be used instead of GestureDetector to ensure each GestureRecognizer created by the GestureDetector has supportedDevices set to exclude PointerDeviceKind.trackpad. Starting in version 3.4.0, there is a supportedDevices parameter directly on GestureDetector.

Code before migration:

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onPanStart: (details) {
        debugPrint('onStart');
      },
      onPanUpdate: (details) {
        debugPrint('onUpdate');
      },
      onPanEnd: (details) {
        debugPrint('onEnd');
      }
      child: Container()
    );
  }
}

Code after migration (Flutter 3.3.0):

dart// Example of code after the change.
void main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RawGestureDetector(
      gestures: {
        PanGestureRecognizer:
            GestureRecognizerFactoryWithHandlers<PanGestureRecognizer>(
          () => PanGestureRecognizer(
            supportedDevices: {
              PointerDeviceKind.touch,
              PointerDeviceKind.mouse,
              PointerDeviceKind.stylus,
              PointerDeviceKind.invertedStylus,
              // Do not include PointerDeviceKind.trackpad
            }
          ),
          (recognizer) {
            recognizer
              ..onStart = (details) {
                debugPrint('onStart');
              }
              ..onUpdate = (details) {
                debugPrint('onUpdate');
              }
              ..onEnd = (details) {
                debugPrint('onEnd');
              };
          },
        ),
      },
      child: Container()
    );
  }
}

Code after migration: (Flutter 3.4.0):

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      supportedDevices: {
        PointerDeviceKind.touch,
        PointerDeviceKind.mouse,
        PointerDeviceKind.stylus,
        PointerDeviceKind.invertedStylus,
        // Do not include PointerDeviceKind.trackpad
      },
      onPanStart: (details) {
        debugPrint('onStart');
      },
      onPanUpdate: (details) {
        debugPrint('onUpdate');
      },
      onPanEnd: (details) {
        debugPrint('onEnd');
      }
      child: Container()
    );
  }
}

Explicitly ensure that supportedDevices doesn't include PointerDeviceKind.trackpad.

Code before migration:

dartvoid main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RawGestureDetector(
      gestures: {
        PanGestureRecognizer:
            GestureRecognizerFactoryWithHandlers<PanGestureRecognizer>(
          () => PanGestureRecognizer(),
          (recognizer) {
            recognizer
              ..onStart = (details) {
                debugPrint('onStart');
              }
              ..onUpdate = (details) {
                debugPrint('onUpdate');
              }
              ..onEnd = (details) {
                debugPrint('onEnd');
              };
          },
        ),
      },
      child: Container()
    );
  }
}

Code after migration:

dart// Example of code after the change.
void main() => runApp(Foo());

class Foo extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return RawGestureDetector(
      gestures: {
        PanGestureRecognizer:
            GestureRecognizerFactoryWithHandlers<PanGestureRecognizer>(
          () => PanGestureRecognizer(
            supportedDevices: {
              PointerDeviceKind.touch,
              PointerDeviceKind.mouse,
              PointerDeviceKind.stylus,
              PointerDeviceKind.invertedStylus,
              // Do not include PointerDeviceKind.trackpad
            }
          ),
          (recognizer) {
            recognizer
              ..onStart = (details) {
                debugPrint('onStart');
              }
              ..onUpdate = (details) {
                debugPrint('onUpdate');
              }
              ..onEnd = (details) {
                debugPrint('onEnd');
              };
          },
        ),
      },
      child: Container()
    );
  }
}

After upgrading to Flutter 3.3.0, there won't be a change in behavior, as addPointerPanZoom must be called on each GestureRecognizer to allow it to track gestures. The following code won't receive pan gesture callbacks when the trackpad is scrolled:

dartvoid main() => runApp(Foo());

class Foo extends StatefulWidget {
  late final PanGestureRecognizer recognizer;

  @override
  void initState() {
    super.initState();
    recognizer = PanGestureRecognizer()
    ..onStart = _onPanStart
    ..onUpdate = _onPanUpdate
    ..onEnd = _onPanEnd;
  }

  void _onPanStart(DragStartDetails details) {
    debugPrint('onStart');
  }

  void _onPanUpdate(DragUpdateDetails details) {
    debugPrint('onUpdate');
  }

  void _onPanEnd(DragEndDetails details) {
    debugPrint('onEnd');
  }

  @override
  Widget build(BuildContext context) {
    return Listener(
      onPointerDown: recognizer.addPointer,
      // recognizer.addPointerPanZoom is not called
      child: Container()
    );
  }
}

Landed in version: 3.3.0-0.0.pre
In stable release: 3.3.0

API documentation:

Design document:

Flutter Trackpad Gestures

Relevant issues:

Issue 23604

Relevant PRs:

本页内容对你有帮助吗？

感谢你的反馈！

提供详细信息

感谢你的反馈！欢迎告诉我们该如何改进。

提供详细信息

除非另有说明，本文档之所提及适用于 Flutter 的最新稳定版本，本页面最后更新时间: 2024-05-14。查看文档源码或者为本页面内容提出建议.

Trackpad gestures can trigger GestureRecognizer

Summary

Context

Description of change

Migration guide

For gesture interactions suitable for trackpad usage

Using `GestureDetector`

Using `GestureRecognizer` and `Listener`

Using raw `Listener`

For gesture interactions not suitable for trackpad usage

Using `GestureDetector`

Using `RawGestureRecognizer`

Using `GestureRecognizer` and `Listener`

Timeline

References

Summary

Context

Description of change

Migration guide

For gesture interactions suitable for trackpad usage

Using GestureDetector

Using GestureRecognizer and Listener

Using raw Listener

For gesture interactions not suitable for trackpad usage

Using GestureDetector

Using RawGestureRecognizer

Using GestureRecognizer and Listener

Timeline

References

Using `GestureDetector`

Using `GestureRecognizer` and `Listener`

Using raw `Listener`

Using `GestureDetector`

Using `RawGestureRecognizer`

Using `GestureRecognizer` and `Listener`