ShapeWorkflow


@ExperimentalInkCustomShapeWorkflowApi
public interface ShapeWorkflow<ShapeSpecT extends Object, InProgressShapeT extends InProgressShape<@NonNull ShapeSpecT, @NonNull CompletedShapeT>, CompletedShapeT extends Object>


An interface that can be implemented to provide custom inking functionality which replaces or augments the standard Jetpack Ink behavior. Providing an implementation of this is an advanced feature that isn't recommended for most apps - most use cases should prefer to use androidx.ink.brush.StockBrushes, or perhaps create a custom brush with androidx.ink.storage.BrushFamilySerialization.decode. But if those don't satisfy the need for fully custom programmatic geometry of stroke-like objects based on pointer input data, this interface can be implemented to control that, but in a way that can still take advantage of Ink's low latency drawing capabilities without needing to implement that from scratch.

The primary purpose of this object is to manage the recycling lifecycle of InProgressShape instances. A new instance will only be requested via create when the internal recycling logic determines it's necessary, and most of the time it will reuse existing recycled instances via InProgressShape.start.

Parameters
<ShapeSpecT extends Object>

A styling specification type, typically pure declarative data, that indicates how pointer inputs are turned into geometry and rendered pixels. A standard, pure Ink implementation would use androidx.ink.brush.Brush for this.

<InProgressShapeT extends InProgressShape<@NonNull ShapeSpecT, @NonNull CompletedShapeT>>

A specific type of InProgressShape that includes the logic for how a ShapeSpecT and incrementally added pointer events are turned into geometry and rendered pixels. A standard, pure Ink implementation would be based on androidx.ink.strokes.InProgressStroke.

<CompletedShapeT extends Object>

A type that represents the end result of an InProgressShapeT, after all inputs have been delivered to it and it has been fully processed. This is often different from an InProgressShapeT as it can be immutable, and may therefore represent its underlying data in a more optimized form. A standard, pure Ink implementation would use androidx.ink.strokes.Stroke for this.

Summary

Public methods

abstract @NonNull InProgressShapeT
create(int shapeType)

Called when a new InProgressShape is needed for the given shapeType to represent a shape.

abstract @NonNull CompletedShapeRenderer<@NonNull CompletedShapeT>

An object that is called to render a CompletedShapeT instance to an android.graphics.Canvas.

abstract @NonNull InProgressShapeRenderer<@NonNull InProgressShapeT>

An object that is called to render an InProgressShapeT instance to an android.graphics.Canvas.

abstract int
getShapeType(@NonNull ShapeSpecT shapeSpec)

Return the shape type of an item being drawn with the given ShapeSpecT for the purposes of recycling the InProgressShapeT instances.

Public methods

create

Added in 1.0.0
abstract @NonNull InProgressShapeT create(int shapeType)

Called when a new InProgressShape is needed for the given shapeType to represent a shape.

The new InProgressShape will be used to represent a particular in-progress drawn object using InProgressShape.start. Since this object will be reused more than once, it is a good idea to do more expensive initialization once in this function at creation time to avoid unnecessary work in InProgressShape.start and the functions that are called at a high frequency in InProgressShape like InProgressShape.enqueueInputs and InProgressShape.update.

This will typically be called on a separate render thread, but before Build.VERSION_CODES.Q, there is no separate render thread and the UI thread is used instead.

getCompletedShapeRenderer

Added in 1.0.0
abstract @NonNull CompletedShapeRenderer<@NonNull CompletedShapeT> getCompletedShapeRenderer()

An object that is called to render a CompletedShapeT instance to an android.graphics.Canvas. This will only ever be used on the UI thread. A standard, pure Ink implementation would be based on androidx.ink.rendering.android.canvas.CanvasStrokeRenderer.

getInProgressShapeRenderer

Added in 1.0.0
abstract @NonNull InProgressShapeRenderer<@NonNull InProgressShapeT> getInProgressShapeRenderer()

An object that is called to render an InProgressShapeT instance to an android.graphics.Canvas. This will typically be called on a separate render thread, but before Build.VERSION_CODES.Q, there is no separate render thread and the UI thread is used instead. A standard, pure Ink implementation would be based on androidx.ink.rendering.android.canvas.CanvasStrokeRenderer.

getShapeType

Added in 1.0.0
abstract int getShapeType(@NonNull ShapeSpecT shapeSpec)

Return the shape type of an item being drawn with the given ShapeSpecT for the purposes of recycling the InProgressShapeT instances. The simplest implementation of this can use a single shape type, but multiple shape types are supported. The returned integer value serves as a unique identifier - there are no limits on its value, and the numeric value of one type compared to another is meaningless beyond the fact that they are distinct.

This will typically be called on a separate render thread, but before Build.VERSION_CODES.Q, there is no separate render thread and the UI thread is used instead.