StrokeInput

Kotlin |Java

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
`const Float`	`NO_ORIENTATION`
`const Float`	`NO_PRESSURE`
`const Float`	`NO_STROKE_UNIT_LENGTH = 0.0f`
`const Float`	`NO_TILT`

Public companion functions
`StrokeInput`	`@VisibleForTesting create( x: Float, y: Float, elapsedTimeMillis: @IntRange(from = 0) Long, toolType: InputToolType, strokeUnitLengthCm: Float, pressure: Float, tiltRadians: Float, orientationRadians: Float )` Allocate and return a new `StrokeInput`.

Public constructors
`StrokeInput()`

Public functions
`open operator Boolean`	`equals(other: Any?)`
`open Int`	`hashCode()`
`open String`	`toString()`
`Unit`	`update( x: Float, y: Float, elapsedTimeMillis: @IntRange(from = 0) Long, toolType: InputToolType, strokeUnitLengthCm: Float, pressure: Float, tiltRadians: Float, orientationRadians: Float )` Set new values on this instance, clearing values corresponding to optional parameters that are not specified.

Public properties
`Long`	`elapsedTimeMillis` Time elapsed since the start of the stroke.
`Boolean`	`hasOrientation` Whether the `orientationRadians` field contains a valid orientation value.
`Boolean`	`hasPressure` Whether the `pressure` field contains a valid pressure value.
`Boolean`	`hasTilt` Whether the `tiltRadians` field contains a valid tilt value.
`Float`	`orientationRadians` The angle that indicates the direction in which the stylus is pointing in relation to the positive x axis.
`Float`	`pressure` Pressure value in the normalized, unitless range of 0, 1 indicating the force exerted during input.
`Float`	`strokeUnitLengthCm` The physical distance in centimeters that the pointer must travel in order to produce an input motion of one stroke unit.
`Float`	`tiltRadians` The angle between a stylus and the line perpendicular to the plane of the screen.
`InputToolType`	`toolType` The input device used to generate this stroke input.
`Float`	`x` The x-coordinate of the input position in stroke space.
`Float`	`y` The y-coordinate of the input position in stroke space.

Constants

NO_ORIENTATION

const val NO_ORIENTATION: Float

NO_PRESSURE

const val NO_PRESSURE: Float

NO_STROKE_UNIT_LENGTH

const val NO_STROKE_UNIT_LENGTH = 0.0f: Float

NO_TILT

const val NO_TILT: Float

Public companion functions

create

Added in 1.0.0-alpha02

@VisibleForTesting
fun create(
    x: Float,
    y: Float,
    elapsedTimeMillis: @IntRange(from = 0) Long,
    toolType: InputToolType = InputToolType.UNKNOWN,
    strokeUnitLengthCm: Float = NO_STROKE_UNIT_LENGTH,
    pressure: Float = NO_PRESSURE,
    tiltRadians: Float = NO_TILT,
    orientationRadians: Float = NO_ORIENTATION
): StrokeInput

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.

Public constructors

StrokeInput

Added in 1.0.0-alpha02

StrokeInput()

Public functions

equals

open operator fun equals(other: Any?): Boolean

hashCode

open fun hashCode(): Int

toString

open fun toString(): String

update

Added in 1.0.0-alpha02

fun update(
    x: Float,
    y: Float,
    elapsedTimeMillis: @IntRange(from = 0) Long,
    toolType: InputToolType = InputToolType.UNKNOWN,
    strokeUnitLengthCm: Float = NO_STROKE_UNIT_LENGTH,
    pressure: Float = NO_PRESSURE,
    tiltRadians: Float = NO_TILT,
    orientationRadians: Float = NO_ORIENTATION
): Unit

Set new values on this instance, clearing values corresponding to optional parameters that are not specified.

Parameters
`x: Float`	The `x` position coordinate of the input in the stroke's coordinate space.
`y: Float`	The `y` position coordinate of the input in the stroke's coordinate space.
`elapsedTimeMillis: @IntRange(from = 0) Long`	Marks the number of milliseconds since the stroke started. It is a non-negative timestamp in the `android.os.SystemClock.elapsedRealtime` time base.
`toolType: InputToolType = InputToolType.UNKNOWN`	The type of tool used to create this input data.
`strokeUnitLengthCm: Float = NO_STROKE_UNIT_LENGTH`	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.
`pressure: Float = NO_PRESSURE`	Should be within 0, 1 but it's not enforced until added to a `StrokeInputBatch` object. Absence of `pressure` data is represented with `NO_PRESSURE`.
`tiltRadians: Float = NO_TILT`	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 `tiltRadians` data is represented with `NO_TILT`.
`orientationRadians: Float = NO_ORIENTATION`	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 `orientationRadians` data is represented with `NO_ORIENTATION`.

Public properties

elapsedTimeMillis

Added in 1.0.0-alpha02

val elapsedTimeMillis: Long

Time elapsed since the start of the stroke.

hasOrientation

Added in 1.0.0-alpha02

val hasOrientation: Boolean

Whether the orientationRadians field contains a valid orientation value.

hasPressure

Added in 1.0.0-alpha02

val hasPressure: Boolean

Whether the pressure field contains a valid pressure value.

hasTilt

Added in 1.0.0-alpha02

val hasTilt: Boolean

Whether the tiltRadians field contains a valid tilt value.

orientationRadians

Added in 1.0.0-alpha02

val orientationRadians: Float

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.

pressure

Added in 1.0.0-alpha02

val pressure: Float

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.

strokeUnitLengthCm

Added in 1.0.0-alpha02

val strokeUnitLengthCm: Float

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.

tiltRadians

Added in 1.0.0-alpha02

val tiltRadians: Float

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.

toolType

Added in 1.0.0-alpha02

val toolType: InputToolType

The input device used to generate this stroke input.

x

Added in 1.0.0-alpha02

val x: Float

The x-coordinate of the input position in stroke space.

y

Added in 1.0.0-alpha02

val y: Float

The y-coordinate of the input position in stroke space.