MutableStrokeInputBatch

public final class MutableStrokeInputBatch extends StrokeInputBatch

java.lang.Object
   ↳ androidx.ink.strokes.StrokeInputBatch
     ↳ androidx.ink.strokes.MutableStrokeInputBatch

A mutable implementation of StrokeInputBatch. For an immutable alternative, see ImmutableStrokeInputBatch.

Each appended StrokeInput value is validated compared to the existing batch contents. This means:

  1. All floating point values are required to be finite and the format of all inputs must be consistent. This means all inputs must have the same set of optional member variables that hold a value. For example, every input holds a pressure value if-and-only-if every other input holds a pressure value. This is also true for tiltRadians and orientationRadians.

  2. The sequence of StrokeInput values must not contain repeated x-y-t triplets, and the time values must be non-negative and non-decreasing.

  3. Values of strokeUnitLengthCm must be finite and positive, or be StrokeInput.NO_STROKE_UNIT_LENGTH.

  4. Values of StrokeInput.pressure must fall within the range of 0, 1 or be StrokeInput.NO_PRESSURE

  5. Values of StrokeInput.tiltRadians must fall within the range of 0, π/2 or be StrokeInput.NO_TILT.

  6. Values of StrokeInput.orientationRadians must fall within the range of [0, 2π) or be StrokeInput.NO_ORIENTATION.

  7. The toolType and strokeUnitLengthCm values must be the same across all inputs.

Summary

Public constructors

Public methods
final @NonNull MutableStrokeInputBatch

Validates and appends an inputBatch.
final @NonNull MutableStrokeInputBatch

Adds an input to the batch if valid.
final @NonNull MutableStrokeInputBatch

Validates and appends a collection of StrokeInput.
final @NonNull MutableStrokeInputBatch
add(
    @NonNull InputToolType type,
    float x,
    float y,
    long elapsedTimeMillis,
    float strokeUnitLengthCm,
    float pressure,
    float tiltRadians,
    float orientationRadians
)

Variant of add that takes individual parameters instead of a StrokeInput.
final void
final void

Sets the per-stroke seed value that should be used when regenerating a stroke from this input batch.
@NonNull String

Inherited methods
From androidx.ink.strokes.StrokeInputBatch
final void
final @NonNull StrokeInput
get(int index)

Gets the value of the i-th input.
final long

The duration between the first and last input in milliseconds.
final int

Number of StrokeInput objects in the batch.
final float

The physical distance in centimeters that the pointer must travel in order to produce an input motion of one stroke unit.
final @NonNull InputToolType

How this input stream should be interpreted, as coming from a InputToolType.MOUSE, InputToolType.TOUCH, or InputToolType.STYLUS.
final boolean

Whether all of the individual inputs have a defined value for StrokeInput.orientationRadians.
final boolean

Whether all of the individual inputs have a defined value for StrokeInput.pressure.
final boolean

Whether strokeUnitLengthCm has a valid value, which is something other than StrokeInput.NO_STROKE_UNIT_LENGTH.
final boolean

Whether all of the individual inputs have a defined value for StrokeInput.tiltRadians.
final boolean

true if there are no StrokeInput objects in the batch, and false otherwise.
final @NonNull StrokeInput
populate(int index, @NonNull StrokeInput outStrokeInput)

Gets the value of the i-th input and overwrites outStrokeInput, which it then returns.

Public constructors

MutableStrokeInputBatch

Added in 1.0.0-alpha05
public MutableStrokeInputBatch()

Public methods

add

Added in 1.0.0-alpha05
public final @NonNull MutableStrokeInputBatch add(@NonNull StrokeInputBatch inputBatch)

Validates and appends an inputBatch. Invalid inputBatch will result in no change. An exception will be thrown for invalid additions.

add

Added in 1.0.0-alpha05
public final @NonNull MutableStrokeInputBatch add(@NonNull StrokeInput input)

Adds an input to the batch if valid.

Inputs are invalid if they contain values out of the valid range, duplicate a previous input, have an elapsed time before a previous input, or have a different tool type or set different optional fields (pressure, tilt, or orientation) than the inputs already in the batch.

Returns this instance to allow call chaining.

Parameters
@NonNull StrokeInput input

The StrokeInput to add to the batch.
Returns
@NonNull MutableStrokeInputBatch

this
Throws
kotlin.IllegalArgumentException

If the input is not valid. Note that this can be a common occurrence with real user input on certain devices, in particular due to duplicate or out-of-order inputs. Therefore, users should either catch and handle this exception or sanitize the input to avoid ensure validity before passing it to this function.

add

Added in 1.0.0-alpha05
public final @NonNull MutableStrokeInputBatch add(@NonNull Collection<@NonNull StrokeInput> inputs)

Validates and appends a collection of StrokeInput. Invalid inputs will result in no change. An exception will be thrown for invalid additions.

Returns this instance to allow call chaining.

Parameters
@NonNull Collection<@NonNull StrokeInput> inputs

Collection of StrokeInputs to add to the batch.
Returns
@NonNull MutableStrokeInputBatch

this
Throws
kotlin.IllegalArgumentException

If the input is not valid. Note that this can be a common occurrence with real user input on certain devices, in particular due to duplicate or out-of-order inputs. Therefore, users should either catch and handle this exception or sanitize the input to avoid ensure validity before passing it to this function.

add

Added in 1.0.0-alpha05
public final @NonNull MutableStrokeInputBatch add(
    @NonNull InputToolType type,
    float x,
    float y,
    long elapsedTimeMillis,
    float strokeUnitLengthCm,
    float pressure,
    float tiltRadians,
    float orientationRadians
)

Variant of add that takes individual parameters instead of a StrokeInput.

Returns this instance to allow call chaining.

Parameters
@NonNull InputToolType type

The InputToolType to use for the 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.
long elapsedTimeMillis

Marks the number of milliseconds since the stroke started. It is a non-negative timestamp in the android.os.SystemClock.elapsedRealtime time base.
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 StrokeInput.NO_STROKE_UNIT_LENGTH indicates that the relationship between stroke space and physical space is unknown or ill-defined.
float pressure

Should be within 0, 1 but it's not enforced until added to a StrokeInputBatch object. Absence of pressure data is represented with StrokeInput.NO_PRESSURE.
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 tiltRadians data is represented with StrokeInput.NO_TILT.
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 orientationRadians data is represented with StrokeInput.NO_ORIENTATION.
Returns
@NonNull MutableStrokeInputBatch

this
Throws
kotlin.IllegalArgumentException

If the input is not valid. Note that this can be a common occurrence with real user input on certain devices, in particular due to duplicate or out-of-order inputs. Therefore, users should either catch and handle this exception or sanitize the input to avoid ensure validity before passing it to this function.

clear

Added in 1.0.0-alpha05
public final void clear()

setNoiseSeed

Added in 1.0.0-alpha05
@ExperimentalInkCustomBrushApi
public final void setNoiseSeed(int seed)

Sets the per-stroke seed value that should be used when regenerating a stroke from this input batch.

toString

public @NonNull String toString()