firka/flutter
firka/flutter
5
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clean up PointerEvent documentation. (#24002)

Browse Source
This commit is contained in:
Stanislav Baranov 2018-11-09 14:26:21 -08:00 committed by GitHub
parent 43407e4e01
commit e32cd85446
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 63 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

101
packages/flutter/lib/src/gestures/events.dart
View File

@ -136,61 +136,80 @@ abstract class PointerEvent {
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 @@ abstract class PointerEvent {
/// 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 @@ abstract class PointerEvent {
/// 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 @@ abstract class PointerEvent {
/// 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 @@ abstract class PointerEvent {
/// 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.