Unverified Commit e32cd854 authored by Stanislav Baranov's avatar Stanislav Baranov Committed by GitHub

Clean up PointerEvent documentation. (#24002)

parent 43407e4e
...@@ -136,61 +136,80 @@ abstract class PointerEvent { ...@@ -136,61 +136,80 @@ abstract class PointerEvent {
final Offset position; final Offset position;
/// Distance in logical pixels that the pointer moved since the last /// 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; final Offset delta;
/// Bit field using the *Button constants (primaryMouseButton, /// Bit field using the *Button constants such as [kPrimaryMouseButton],
/// secondaryStylusButton, etc). For example, if this has the value 6 and the /// [kSecondaryStylusButton], etc.
///
/// For example, if this has the value 6 and the
/// [kind] is [PointerDeviceKind.invertedStylus], then this indicates an /// [kind] is [PointerDeviceKind.invertedStylus], then this indicates an
/// upside-down stylus with both its primary and secondary buttons pressed. /// upside-down stylus with both its primary and secondary buttons pressed.
final int buttons; final int buttons;
/// Set if the pointer is currently down. For touch and stylus pointers, this /// Set if the pointer is currently down.
/// means the object (finger, pen) is in contact with the input surface. For ///
/// mice, it means a button is pressed. /// 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; final bool down;
/// Set if an application from a different security domain is in any way /// Set if an application from a different security domain is in any way
/// obscuring this application's window. (Aspirational; not currently /// obscuring this application's window.
/// implemented.) ///
/// This is not currently implemented.
final bool obscured; final bool obscured;
/// The pressure of the touch as a number ranging from 0.0, indicating a touch /// The pressure of the touch.
/// with no discernible pressure, to 1.0, indicating a touch with "normal" ///
/// pressure, and possibly beyond, indicating a stronger touch. For devices /// This value is a number ranging from 0.0, indicating a touch with no
/// that do not detect pressure (e.g. mice), returns 1.0. /// 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; final double pressure;
/// The minimum value that [pressure] can return for this pointer. For devices /// The minimum value that [pressure] can return for this pointer.
/// that do not detect pressure (e.g. mice), returns 1.0. This will always be ///
/// a number less than or equal to 1.0. /// 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; final double pressureMin;
/// The maximum value that [pressure] can return for this pointer. For devices /// The maximum value that [pressure] can return for this pointer.
/// that do not detect pressure (e.g. mice), returns 1.0. This will always be ///
/// a greater than or equal to 1.0. /// 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; final double pressureMax;
/// The distance of the detected object from the input surface (e.g. the /// The distance of the detected object from the input surface.
/// 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 /// For instance, this value could be the distance of a stylus or finger
/// is 0.0 by definition. /// 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; 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; double get distanceMin => 0.0;
/// The maximum value that a distance can return for this pointer. If this /// The maximum value that [distance] can return for this pointer.
/// input device cannot detect "hover touch" input events, then this will be ///
/// 0.0. /// If this input device cannot detect "hover touch" input events,
/// then this will be 0.0.
final double distanceMax; final double distanceMax;
/// The area of the screen being pressed, scaled to a value between 0 and 1. /// The area of the screen being pressed.
/// 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 /// This value is scaled to a range between 0 and 1. It can be used to
/// the range of detectable values. So, for example, the value of 0.1 could /// determine fat touch events. This value is only set on Android and is
/// mean a touch with the tip of the finger, 0.2 a touch with full finger, /// a device specific approximation within the range of detectable values.
/// and 0.3 the full palm. /// 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; final double size;
/// The radius of the contact ellipse along the major axis, in logical pixels. /// The radius of the contact ellipse along the major axis, in logical pixels.
...@@ -199,17 +218,19 @@ abstract class PointerEvent { ...@@ -199,17 +218,19 @@ abstract class PointerEvent {
/// The radius of the contact ellipse along the minor axis, in logical pixels. /// The radius of the contact ellipse along the minor axis, in logical pixels.
final double radiusMinor; 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. /// for this pointer, in logical pixels.
final double radiusMin; 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. /// for this pointer, in logical pixels.
final double radiusMax; 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 /// -pi/2 < orientation <= pi/2
/// ///
...@@ -219,7 +240,7 @@ abstract class PointerEvent { ...@@ -219,7 +240,7 @@ abstract class PointerEvent {
/// top-right / bottom-left diagonal, and zero indicating an orientation /// top-right / bottom-left diagonal, and zero indicating an orientation
/// parallel with the y-axis). /// 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: /// The angle of the stylus, in radians in the range:
/// ///
...@@ -234,7 +255,9 @@ abstract class PointerEvent { ...@@ -234,7 +255,9 @@ abstract class PointerEvent {
/// indicate that the stylus goes to the left, etc). /// indicate that the stylus goes to the left, etc).
final double orientation; 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: /// The angle of the stylus, in radians in the range:
/// ///
...@@ -249,6 +272,8 @@ abstract class PointerEvent { ...@@ -249,6 +272,8 @@ abstract class PointerEvent {
/// Opaque platform-specific data associated with the event. /// Opaque platform-specific data associated with the event.
final int platformData; final int platformData;
/// Set if the event was synthesized by Flutter.
///
/// We occasionally synthesize PointerEvents that aren't exact translations /// We occasionally synthesize PointerEvents that aren't exact translations
/// of [ui.PointerData] from the engine to cover small cross-OS discrepancies /// of [ui.PointerData] from the engine to cover small cross-OS discrepancies
/// in pointer behaviors. /// in pointer behaviors.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment