StrokeInput
public final class StrokeInput
A single input specifying position, time since the start of the stream, and optionally pressure, tiltRadians, and orientationRadians.
This data type is used as an input to StrokeInputBatch and InProgressStroke. If these are to be created as part of real-time input, it is recommended to use some sort of object pool so that new usages can make use of existing objects that have been recycled, rather than allocating new ones which could introduce unpredictable garbage collection related delays to the time-sensitive input path. This class has the update method for that purpose, rather than being immutable.
Summary
Constants |
|
|---|---|
static final float |
|
static final float |
|
static final float |
NO_STROKE_UNIT_LENGTH = 0.0f |
static final float |
Public constructors |
|---|
Public methods |
|
|---|---|
static final @NonNull StrokeInput |
@VisibleForTestingAllocate and return a new |
boolean |
|
final long |
Time elapsed since the start of the stroke. |
final float |
The angle that indicates the direction in which the stylus is pointing in relation to the positive x axis. |
final float |
Pressure value in the normalized, unitless range of 0, 1 indicating the force exerted during input. |
final float |
The physical distance in centimeters that the pointer must travel in order to produce an input motion of one stroke unit. |
final float |
The angle between a stylus and the line perpendicular to the plane of the screen. |
final @NonNull InputToolType |
The input device used to generate this stroke input. |
final float |
getX()The x-coordinate of the input position in stroke space. |
final float |
getY()The y-coordinate of the input position in stroke space. |
final boolean |
Whether the |
final boolean |
Whether the |
final boolean |
hasTilt()Whether the |
int |
hashCode() |
@NonNull String |
toString() |
final void |
update(Set new values on this instance, clearing values corresponding to optional parameters that are not specified. |
Constants
Public constructors
Public methods
create
@VisibleForTesting
public static final @NonNull StrokeInput create(
float x,
float y,
@IntRange(from = 0) long elapsedTimeMillis,
@NonNull InputToolType toolType,
float strokeUnitLengthCm,
float pressure,
float tiltRadians,
float orientationRadians
)
Allocate and return a new StrokeInput. Only intended for test code - real code should use a recycling pattern to avoid allocating during latency-sensitive real-time input, using update on an instance allocated with the zero-argument constructor.
getElapsedTimeMillis
public final long getElapsedTimeMillis()
Time elapsed since the start of the stroke.
getOrientationRadians
public final float getOrientationRadians()
The angle that indicates the direction in which the stylus is pointing in relation to the positive x axis. The value should be normalized to fall between 0 and 2π in radians, where 0 means the ray from the stylus tip to the end is along positive x and values increase towards the positive y-axis.
When tiltRadians is equal to π/2, the value for orientationRadians is indeterminant.
NO_ORIENTATION indicates that orientation is not reported, which can be checked with hasOrientation. Note, that this is a separate condition from the orientation being indeterminant when tiltRadians is π/2.
getPressure
public final float getPressure()
Pressure value in the normalized, unitless range of 0, 1 indicating the force exerted during input.
A value of NO_PRESSURE indicates that pressure is not reported, which can be checked with hasPressure.
getStrokeUnitLengthCm
public final float getStrokeUnitLengthCm()
The physical distance in centimeters that the pointer must travel in order to produce an input motion of one stroke unit. For stylus/touch, this is the real-world distance that the stylus/fingertip must move in physical space; for mouse, this is the visual distance that the mouse pointer must travel along the surface of the display.
A value of NO_STROKE_UNIT_LENGTH indicates that the relationship between stroke space and physical space is unknown or ill-defined.
getTiltRadians
public final float getTiltRadians()
The angle between a stylus and the line perpendicular to the plane of the screen. The value should be normalized to fall between 0 and π/2 in radians, where 0 is perpendicular to the screen and π/2 is flat against the drawing surface.
NO_TILT indicates that tilt is not reported, which can be checked with hasTilt.
getToolType
public final @NonNull InputToolType getToolType()
The input device used to generate this stroke input.
getX
public final float getX()
The x-coordinate of the input position in stroke space.
getY
public final float getY()
The y-coordinate of the input position in stroke space.
hasOrientation
public final boolean hasOrientation()
Whether the orientationRadians field contains a valid orientation value.
hasPressure
public final boolean hasPressure()
Whether the pressure field contains a valid pressure value.
hasTilt
public final boolean hasTilt()
Whether the tiltRadians field contains a valid tilt value.
update
public final void update(
float x,
float y,
@IntRange(from = 0) long elapsedTimeMillis,
@NonNull InputToolType toolType,
float strokeUnitLengthCm,
float pressure,
float tiltRadians,
float orientationRadians
)
Set new values on this instance, clearing values corresponding to optional parameters that are not specified.
| Parameters | |
|---|---|
float x |
The |
float y |
The |
@IntRange(from = 0) long elapsedTimeMillis |
Marks the number of milliseconds since the stroke started. It is a non-negative timestamp in the |
@NonNull InputToolType toolType |
The type of tool used to create this input data. |
float strokeUnitLengthCm |
The physical distance in centimeters that the pointer must travel in order to produce an input motion of one stroke unit. For stylus/touch, this is the real-world distance that the stylus/fingertip must move in physical space; for mouse, this is the visual distance that the mouse pointer must travel along the surface of the display. A value of |
float pressure |
Should be within 0, 1 but it's not enforced until added to a |
float tiltRadians |
The angle in radians between a stylus and the line perpendicular to the plane of the screen. 0 is perpendicular to the screen and PI/2 is flat against the drawing surface. Absence of |
float orientationRadians |
Indicates the direction in which the stylus is pointing in relation to the positive x axis in radians. A value of 0 means the ray from the stylus tip to the end is along positive x and values increase towards the positive y-axis. Absence of |