InProgressStrokesView

public InProgressStrokesView(
    @NonNull Context context,
    AttributeSet attrs,
    @AttrRes int defStyleAttr
)

public final void addFinishedStrokesListener(
    @NonNull InProgressStrokesFinishedListener listener
)

Add a listener to be notified when strokes are finished. These strokes will continue to be rendered within this view until removeFinishedStrokes is called. All of the strokes that have been delivered to listeners but have not yet been removed with removeFinishedStrokes are available through getFinishedStrokes.

public final void addToStroke(
    @NonNull StrokeInputBatch inputs,
    @NonNull InProgressStrokeId strokeId,
    @NonNull StrokeInputBatch prediction
)

Add input data from a StrokeInputBatch to an existing stroke.

public final void addToStroke(
    @NonNull MotionEvent event,
    int pointerId,
    @NonNull InProgressStrokeId strokeId,
    MotionEvent prediction
)

Add input data, from a particular pointer within a MotionEvent, to an existing stroke.

public final void cancelStroke(@NonNull InProgressStrokeId strokeId, MotionEvent event)

Cancel the building of a stroke. It will no longer be visible within this InProgressStrokesView, and no completed Stroke object will come through InProgressStrokesFinishedListener.

This is typically done for one of three reasons:

1. A MotionEvent with MotionEvent.getActionMasked of MotionEvent.ACTION_CANCEL. This tends to be when an entire gesture has been canceled, for example when a parent View uses android.view.ViewGroup.onInterceptTouchEvent to intercept and handle the gesture itself.

2. A MotionEvent with MotionEvent.getFlags containing MotionEvent.FLAG_CANCELED. This tends to be when the system has detected an unintentional touch, such as from the user resting their palm on the screen while writing or drawing, after some events from that unintentional pointer have already been delivered.

3. An app's business logic reinterprets a gesture previously used for inking as something else, and the earlier inking may be seen as unintentional. For example, an app that uses single-pointer gestures for inking and dual-pointer gestures for pan/zoom/rotate will start inking when the first pointer goes down, but when the second pointer goes down it may want to cancel the stroke from the first pointer rather than leave the small ink marks on the screen.

public final void eagerInit()

Eagerly initialize rather than waiting for the first stroke to be drawn. Since initialization can be somewhat heavyweight, doing this as soon as it's likely for the user to start drawing can prevent initialization from introducing latency to the first stroke.

public final void finishStroke(
    @NonNull StrokeInput input,
    @NonNull InProgressStrokeId strokeId
)

Complete the building of a stroke, with the last input data coming from a StrokeInput.

public final void finishStroke(
    @NonNull MotionEvent event,
    int pointerId,
    @NonNull InProgressStrokeId strokeId
)

Complete the building of a stroke, with the last input data coming from a particular pointer of a MotionEvent.

When the stroke no longer needs to be rendered by this InProgressStrokesView and can instead be rendered anywhere in the View hierarchy using CanvasStrokeRenderer, the resulting Stroke object will be passed to the InProgressStrokesFinishedListener instances registered with this InProgressStrokesView using addFinishedStrokesListener.

public final @NonNull Map<@NonNull InProgressStrokeId, @NonNull Stroke> getFinishedStrokes()

Returns all the finished strokes that are still being rendered by this view. The IDs of these strokes should be passed to removeFinishedStrokes when they are handed off to another view.

public final CountingIdlingResource getInProgressStrokeCounter()

Allows a test to easily wait until all in-progress strokes are completed and handed off. There is no reason to set this in non-test code.

public final Path getMaskPath()

Denote an area of this InProgressStrokesView where no ink should be visible. This is useful for UI elements that float on top of (in Z order) the drawing surface - without this, a user would be able to draw in-progress ("wet") strokes on top of those UI elements, but then when the stroke is finished, it will appear as a dry stroke underneath of the UI element. If this mask is set to the shape and position of the floating UI element, then the ink will never be rendered in that area, making it appear as if it's being drawn underneath the UI element.

This technique is most convincing when the UI element is opaque. Often there are parts of the UI element that are translucent, such as drop shadows, or anti-aliasing along the edges. The result will look a little different between wet and dry strokes for those cases, but it can be a worthwhile tradeoff compared to the alternative of drawing wet strokes on top of that UI element.

public final @NonNull Matrix getMotionEventToViewTransform()

The transform matrix to convert MotionEvent coordinates, as passed to startStroke, addToStroke, and finishStroke, into coordinates of this InProgressStrokesView for rendering. Defaults to the identity matrix, for the recommended case where InProgressStrokesView exactly overlays the android.view.View that has the touch listener from which MotionEvent instances are being forwarded.

public final @NonNull Function0<@NonNull CanvasStrokeRenderer> getRendererFactory()

A function that creates a CanvasStrokeRenderer when invoked. The default implementation of this will automatically account for the Android OS version of the device. If you choose to replace the default with an alternate implementation, then you must set this variable before the first call to startStroke or eagerInit.

public final void removeFinishedStrokes(@NonNull Set<@NonNull InProgressStrokeId> strokeIds)

Stop this view from rendering the strokes with the given IDs.

This should be called in the same UI thread run loop (HWUI frame) as when the strokes start being rendered elsewhere in the view hierarchy. This means they are saved in a location where they will be picked up in a view's next call to onDraw, and that view's invalidate method has been called. If these two operations are not done within the same UI thread run loop (usually side by side - see example below), then there will be brief rendering errors - either a visual gap where the stroke is not drawn during a frame, or a double draw where the stroke is drawn twice and translucent strokes appear more opaque than they should.

public final void removeFinishedStrokesListener(
    @NonNull InProgressStrokesFinishedListener listener
)

Removes a listener that had previously been added with addFinishedStrokesListener.

public final void setInProgressStrokeCounter(
    @VisibleForTesting CountingIdlingResource inProgressStrokeCounter
)

Allows a test to easily wait until all in-progress strokes are completed and handed off. There is no reason to set this in non-test code.

public final void setMaskPath(Path maskPath)

Denote an area of this InProgressStrokesView where no ink should be visible. This is useful for UI elements that float on top of (in Z order) the drawing surface - without this, a user would be able to draw in-progress ("wet") strokes on top of those UI elements, but then when the stroke is finished, it will appear as a dry stroke underneath of the UI element. If this mask is set to the shape and position of the floating UI element, then the ink will never be rendered in that area, making it appear as if it's being drawn underneath the UI element.

This technique is most convincing when the UI element is opaque. Often there are parts of the UI element that are translucent, such as drop shadows, or anti-aliasing along the edges. The result will look a little different between wet and dry strokes for those cases, but it can be a worthwhile tradeoff compared to the alternative of drawing wet strokes on top of that UI element.

public final void setMotionEventToViewTransform(
    @NonNull Matrix motionEventToViewTransform
)