Clean up PointerEvent documentation. (#24002)
diff --git a/packages/flutter/lib/src/gestures/events.dart b/packages/flutter/lib/src/gestures/events.dart
index 6fb4294..0e38982 100644
--- a/packages/flutter/lib/src/gestures/events.dart
+++ b/packages/flutter/lib/src/gestures/events.dart
@@ -136,61 +136,80 @@
final Offset position;
/// Distance in logical pixels that the pointer moved since the last
- /// PointerMoveEvent. Always 0.0 for down, up, and cancel events.
+ /// [PointerMoveEvent].
+ ///
+ /// This value is always 0.0 for down, up, and cancel events.
final Offset delta;
- /// Bit field using the *Button constants (primaryMouseButton,
- /// secondaryStylusButton, etc). For example, if this has the value 6 and the
+ /// Bit field using the *Button constants such as [kPrimaryMouseButton],
+ /// [kSecondaryStylusButton], etc.
+ ///
+ /// For example, if this has the value 6 and the
/// [kind] is [PointerDeviceKind.invertedStylus], then this indicates an
/// upside-down stylus with both its primary and secondary buttons pressed.
final int buttons;
- /// Set if the pointer is currently down. For touch and stylus pointers, this
- /// means the object (finger, pen) is in contact with the input surface. For
- /// mice, it means a button is pressed.
+ /// Set if the pointer is currently down.
+ ///
+ /// For touch and stylus pointers, this means the object (finger, pen) is in
+ /// contact with the input surface. For mice, it means a button is pressed.
final bool down;
/// Set if an application from a different security domain is in any way
- /// obscuring this application's window. (Aspirational; not currently
- /// implemented.)
+ /// obscuring this application's window.
+ ///
+ /// This is not currently implemented.
final bool obscured;
- /// The pressure of the touch as a number ranging from 0.0, indicating a touch
- /// with no discernible pressure, to 1.0, indicating a touch with "normal"
- /// pressure, and possibly beyond, indicating a stronger touch. For devices
- /// that do not detect pressure (e.g. mice), returns 1.0.
+ /// The pressure of the touch.
+ ///
+ /// This value is a number ranging from 0.0, indicating a touch with no
+ /// discernible pressure, to 1.0, indicating a touch with "normal" pressure,
+ /// and possibly beyond, indicating a stronger touch. For devices that do not
+ /// detect pressure (e.g. mice), returns 1.0.
final double pressure;
- /// The minimum value that [pressure] can return for this pointer. For devices
- /// that do not detect pressure (e.g. mice), returns 1.0. This will always be
- /// a number less than or equal to 1.0.
+ /// The minimum value that [pressure] can return for this pointer.
+ ///
+ /// For devices that do not detect pressure (e.g. mice), returns 1.0.
+ /// This will always be a number less than or equal to 1.0.
final double pressureMin;
- /// The maximum value that [pressure] can return for this pointer. For devices
- /// that do not detect pressure (e.g. mice), returns 1.0. This will always be
- /// a greater than or equal to 1.0.
+ /// The maximum value that [pressure] can return for this pointer.
+ ///
+ /// For devices that do not detect pressure (e.g. mice), returns 1.0.
+ /// This will always be a greater than or equal to 1.0.
final double pressureMax;
- /// The distance of the detected object from the input surface (e.g. the
- /// distance of a stylus or finger from a touch screen), in arbitrary units on
- /// an arbitrary (not necessarily linear) scale. If the pointer is down, this
- /// is 0.0 by definition.
+ /// The distance of the detected object from the input surface.
+ ///
+ /// For instance, this value could be the distance of a stylus or finger
+ /// from a touch screen, in arbitrary units on an arbitrary (not necessarily
+ /// linear) scale. If the pointer is down, this is 0.0 by definition.
final double distance;
- /// The minimum value that a distance can return for this pointer (always 0.0).
+ /// The minimum value that [distance] can return for this pointer.
+ ///
+ /// This value is always 0.0.
double get distanceMin => 0.0;
- /// The maximum value that a distance can return for this pointer. If this
- /// input device cannot detect "hover touch" input events, then this will be
- /// 0.0.
+ /// The maximum value that [distance] can return for this pointer.
+ ///
+ /// If this input device cannot detect "hover touch" input events,
+ /// then this will be 0.0.
final double distanceMax;
- /// The area of the screen being pressed, scaled to a value between 0 and 1.
- /// The value of size can be used to determine fat touch events. This value
- /// is only set on Android, and is a device specific approximation within
- /// the range of detectable values. So, for example, the value of 0.1 could
- /// mean a touch with the tip of the finger, 0.2 a touch with full finger,
- /// and 0.3 the full palm.
+ /// The area of the screen being pressed.
+ ///
+ /// This value is scaled to a range between 0 and 1. It can be used to
+ /// determine fat touch events. This value is only set on Android and is
+ /// a device specific approximation within the range of detectable values.
+ /// So, for example, the value of 0.1 could mean a touch with the tip of
+ /// the finger, 0.2 a touch with full finger, and 0.3 the full palm.
+ ///
+ /// Because this value uses device-specific range and is uncalibrated,
+ /// it is of limited use and is primarily retained in order to be able
+ /// to reconstruct original pointer events for [AndroidView].
final double size;
/// The radius of the contact ellipse along the major axis, in logical pixels.
@@ -199,17 +218,19 @@
/// The radius of the contact ellipse along the minor axis, in logical pixels.
final double radiusMinor;
- /// The minimum value that could be reported for radiusMajor and radiusMinor
+ /// The minimum value that could be reported for [radiusMajor] and [radiusMinor]
/// for this pointer, in logical pixels.
final double radiusMin;
- /// The minimum value that could be reported for radiusMajor and radiusMinor
+ /// The minimum value that could be reported for [radiusMajor] and [radiusMinor]
/// for this pointer, in logical pixels.
final double radiusMax;
- /// For PointerDeviceKind.touch events:
+ /// The orientation angle of the detected object, in radians.
///
- /// The angle of the contact ellipse, in radius in the range:
+ /// For [PointerDeviceKind.touch] events:
+ ///
+ /// The angle of the contact ellipse, in radians in the range:
///
/// -pi/2 < orientation <= pi/2
///
@@ -219,7 +240,7 @@
/// top-right / bottom-left diagonal, and zero indicating an orientation
/// parallel with the y-axis).
///
- /// For PointerDeviceKind.stylus and PointerDeviceKind.invertedStylus events:
+ /// For [PointerDeviceKind.stylus] and [PointerDeviceKind.invertedStylus] events:
///
/// The angle of the stylus, in radians in the range:
///
@@ -234,7 +255,9 @@
/// indicate that the stylus goes to the left, etc).
final double orientation;
- /// For PointerDeviceKind.stylus and PointerDeviceKind.invertedStylus events:
+ /// The tilt angle of the detected object, in radians.
+ ///
+ /// For [PointerDeviceKind.stylus] and [PointerDeviceKind.invertedStylus] events:
///
/// The angle of the stylus, in radians in the range:
///
@@ -249,6 +272,8 @@
/// Opaque platform-specific data associated with the event.
final int platformData;
+ /// Set if the event was synthesized by Flutter.
+ ///
/// We occasionally synthesize PointerEvents that aren't exact translations
/// of [ui.PointerData] from the engine to cover small cross-OS discrepancies
/// in pointer behaviors.
