Prevent PointerEnter[or Exit]Event from erasing event.down value (#40637) (#41332)

* MouseRegion documentation claimed that onEnter and onExit
  would track entry and exit regardless of whether the pointer was
  down or up
* It did such, but when grabbing the value of `event.down` from
  the passed event, the value was always `false`
* PointerEnterEvent and PointerExitEvent were overriding the value
  passed from PointerEvent in constructors, even if the value was true
  e.g. in invocations of .fromMouseEvent((PointerMoveEvent...))
* This change now passes the value along to PointerEnter/ExitEvents
  while providing it a default of false, and updates documentation

Fixes #40637

packages/flutter/lib/src/gestures/events.dart

@@ -804,8 +804,8 @@ class PointerHoverEvent extends PointerEvent {
   }
 }
 
-/// The pointer has moved with respect to the device while the pointer is not
-/// in contact with the device, and it has entered a target object.
+/// The pointer has moved with respect to the device while the pointer is or is
+/// not in contact with the device, and it has entered a target object.
 ///
 /// See also:
 ///
@@ -839,6 +839,7 @@ class PointerEnterEvent extends PointerEvent {
     double radiusMax = 0.0,
     double orientation = 0.0,
     double tilt = 0.0,
+    bool down = false,
     bool synthesized = false,
     Matrix4 transform,
     PointerEnterEvent original,
@@ -851,7 +852,7 @@ class PointerEnterEvent extends PointerEvent {
          delta: delta,
          localDelta: localDelta,
          buttons: buttons,
-         down: false,
+         down: down,
          obscured: obscured,
          pressure: 0.0,
          pressureMin: pressureMin,
@@ -900,6 +901,7 @@ class PointerEnterEvent extends PointerEvent {
     radiusMax: event?.radiusMax,
     orientation: event?.orientation,
     tilt: event?.tilt,
+    down: event?.down,
     synthesized: event?.synthesized,
     transform: event?.transform,
     original: event?.original,
@@ -937,6 +939,7 @@ class PointerEnterEvent extends PointerEvent {
       radiusMax: radiusMax,
       orientation: orientation,
       tilt: tilt,
+      down: down,
       synthesized: synthesized,
       transform: transform,
       original: original ?? this,
@@ -944,8 +947,8 @@ class PointerEnterEvent extends PointerEvent {
   }
 }
 
-/// The pointer has moved with respect to the device while the pointer is not
-/// in contact with the device, and entered a target object.
+/// The pointer has moved with respect to the device while the pointer is or is
+/// not in contact with the device, and entered a target object.
 ///
 /// See also:
 ///
@@ -979,6 +982,7 @@ class PointerExitEvent extends PointerEvent {
     double radiusMax = 0.0,
     double orientation = 0.0,
     double tilt = 0.0,
+    bool down = false,
     bool synthesized = false,
     Matrix4 transform,
     PointerExitEvent original,
@@ -991,7 +995,7 @@ class PointerExitEvent extends PointerEvent {
          delta: delta,
          localDelta: localDelta,
          buttons: buttons,
-         down: false,
+         down: down,
          obscured: obscured,
          pressure: 0.0,
          pressureMin: pressureMin,
@@ -1040,6 +1044,7 @@ class PointerExitEvent extends PointerEvent {
     radiusMax: event?.radiusMax,
     orientation: event?.orientation,
     tilt: event?.tilt,
+    down: event?.down,
     synthesized: event?.synthesized,
     transform: event?.transform,
     original: event?.original,
@@ -1077,6 +1082,7 @@ class PointerExitEvent extends PointerEvent {
       radiusMax: radiusMax,
       orientation: orientation,
       tilt: tilt,
+      down: down,
       synthesized: synthesized,
       transform: transform,
       original: original ?? this,

packages/flutter/test/gestures/events_test.dart

@@ -57,8 +57,27 @@ void main() {
       tilt: 1.1,
       synthesized: true,
     );
+    const PointerEvent move = PointerMoveEvent(
+      timeStamp: Duration(days: 1),
+      kind: PointerDeviceKind.unknown,
+      device: 10,
+      position: Offset(101.0, 202.0),
+      buttons: 7,
+      obscured: true,
+      pressureMax: 2.1,
+      pressureMin: 1.1,
+      distanceMax: 110,
+      size: 11,
+      radiusMajor: 11,
+      radiusMinor: 9,
+      radiusMin: 1.1,
+      radiusMax: 22,
+      orientation: 1.1,
+      tilt: 1.1,
+      synthesized: true,
+    );
 
-    test('PointerEnterEvent.fromMouseEvent', () {
+    test('PointerEnterEvent.fromMouseEvent(hover)', () {
       final PointerEnterEvent event = PointerEnterEvent.fromMouseEvent(hover);
       const PointerEnterEvent empty = PointerEnterEvent();
       expect(event.timeStamp,   hover.timeStamp);
@@ -85,7 +104,7 @@ void main() {
       expect(event.synthesized, hover.synthesized);
     });
 
-    test('PointerExitEvent.fromMouseEvent', () {
+    test('PointerExitEvent.fromMouseEvent(hover)', () {
       final PointerExitEvent event = PointerExitEvent.fromMouseEvent(hover);
       const PointerExitEvent empty = PointerExitEvent();
       expect(event.timeStamp,   hover.timeStamp);
@@ -111,6 +130,60 @@ void main() {
       expect(event.tilt,        hover.tilt);
       expect(event.synthesized, hover.synthesized);
     });
+
+    test('PointerEnterEvent.fromMouseEvent(move)', () {
+      final PointerEnterEvent event = PointerEnterEvent.fromMouseEvent(move);
+      const PointerEnterEvent empty = PointerEnterEvent();
+      expect(event.timeStamp,   move.timeStamp);
+      expect(event.pointer,     empty.pointer);
+      expect(event.kind,        move.kind);
+      expect(event.device,      move.device);
+      expect(event.position,    move.position);
+      expect(event.buttons,     move.buttons);
+      expect(event.down,        move.down);
+      expect(event.obscured,    move.obscured);
+      expect(event.pressure,    empty.pressure);
+      expect(event.pressureMin, move.pressureMin);
+      expect(event.pressureMax, move.pressureMax);
+      expect(event.distance,    move.distance);
+      expect(event.distanceMax, move.distanceMax);
+      expect(event.distanceMax, move.distanceMax);
+      expect(event.size,        move.size);
+      expect(event.radiusMajor, move.radiusMajor);
+      expect(event.radiusMinor, move.radiusMinor);
+      expect(event.radiusMin,   move.radiusMin);
+      expect(event.radiusMax,   move.radiusMax);
+      expect(event.orientation, move.orientation);
+      expect(event.tilt,        move.tilt);
+      expect(event.synthesized, move.synthesized);
+    });
+
+    test('PointerExitEvent.fromMouseEvent(move)', () {
+      final PointerExitEvent event = PointerExitEvent.fromMouseEvent(move);
+      const PointerExitEvent empty = PointerExitEvent();
+      expect(event.timeStamp,   move.timeStamp);
+      expect(event.pointer,     empty.pointer);
+      expect(event.kind,        move.kind);
+      expect(event.device,      move.device);
+      expect(event.position,    move.position);
+      expect(event.buttons,     move.buttons);
+      expect(event.down,        move.down);
+      expect(event.obscured,    move.obscured);
+      expect(event.pressure,    empty.pressure);
+      expect(event.pressureMin, move.pressureMin);
+      expect(event.pressureMax, move.pressureMax);
+      expect(event.distance,    move.distance);
+      expect(event.distanceMax, move.distanceMax);
+      expect(event.distanceMax, move.distanceMax);
+      expect(event.size,        move.size);
+      expect(event.radiusMajor, move.radiusMajor);
+      expect(event.radiusMinor, move.radiusMinor);
+      expect(event.radiusMin,   move.radiusMin);
+      expect(event.radiusMax,   move.radiusMax);
+      expect(event.orientation, move.orientation);
+      expect(event.tilt,        move.tilt);
+      expect(event.synthesized, move.synthesized);
+    });
   });
 
   group('Default values of PointerEvents:', () {