Draw a stroke

To achieve optimal drawing performance, use the startStroke(), addToStroke(), and finishStroke() methods of the InProgressStrokesView class, passing MotionEvent objects as input.

1. Set up UI component

   Incorporate an AndroidView composable into your drawing composable function.

   @Composable
   fun DrawingView()
   {
     Box(modifier = Modifier.fillMaxSize()) {
       AndroidView(
         modifier = Modifier.fillMaxSize(),
         factory = { context ->
           val rootView = FrameLayout(context)
           //...
         },
       ) {
   
       }
     }
   }
   

2. Instantiate InProgressStrokesView

   Within your activity's onCreate() method, obtain a reference to the InProgressStrokesView and establish a touch listener for managing user input.

   class MainActivity : ComponentActivity(){
     private lateinit var inProgressStrokesView: InProgressStrokesView
   
     // ... other variables
   
     override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       inProgressStrokesView = InProgressStrokesView(this)
   
       setContent {
         // ...
         DrawingView(inProgressStrokesView = inProgressStrokesView)
       }
     }
   }
   
   @Composable
   fun DrawingView(
     inProgressStrokesView: InProgressStrokesView,
   ) {
   
     Box(modifier = Modifier.fillMaxSize()) {
       AndroidView(
         modifier = Modifier.fillMaxSize(),
         factory = { context ->
           val rootView = FrameLayout(context)
           inProgressStrokesView.apply {
             layoutParams =
             FrameLayout.LayoutParams(
               FrameLayout.LayoutParams.MATCH_PARENT,
               FrameLayout.LayoutParams.MATCH_PARENT,
             )
           }
           val predictor = MotionEventPredictor.newInstance(rootView)
           val touchListener =
           View.OnTouchListener { view, event ->
             // ... (handle touch events)
           }
   
           rootView.setOnTouchListener(touchListener)
           rootView.addView(inProgressStrokesView)
           rootView
         },
       ) {}
     }
   }
   

   Note: Employing the MotionEventPredictor interface improves stroke latency by predicting upcoming touch events. Use MotionEventPredictor for optimal performance.

3. Handle touch events

   Having established the UI components, you can now initiate drawing based on touch events.

   MotionEvent action	InProgressStrokesView method	Description
   ACTION_DOWN	startStroke()	Begin stroke rendering
   ACTION_MOVE	addToStroke()	Continue rendering the stroke
   ACTION_UP	finishStroke()	Finalize the stroke rendering
   ACTION_CANCEL or FLAG_CANCELED	cancelStroke()	Implement palm rejection; cancel the stroke

   @SuppressLint("ClickableViewAccessibility")
   @Composable
   fun DrawingSurface(
       inProgressStrokesView: InProgressStrokesView
   ) {
       val currentPointerId = remember { mutableStateOf<Int?>(null) }
       val currentStrokeId = remember { mutableStateOf<InProgressStrokeId?>(null) }
       val defaultBrush = Brush.createWithColorIntArgb(
           family = StockBrushes.pressurePenLatest,
           colorIntArgb = Color.Black.toArgb(),
           size = 5F,
           epsilon = 0.1F
       )
   
       Box(modifier = Modifier.fillMaxSize()) {
           AndroidView(
               modifier = Modifier.fillMaxSize(),
               factory = { context ->
                   val rootView = FrameLayout(context)
                   inProgressStrokesView.apply {
                       layoutParams =
                           FrameLayout.LayoutParams(
                               FrameLayout.LayoutParams.MATCH_PARENT,
                               FrameLayout.LayoutParams.MATCH_PARENT,
                           )
                   }
                   val predictor = MotionEventPredictor.newInstance(rootView)
                   val touchListener =
                       View.OnTouchListener { view, event ->
                           predictor.record(event)
                           val predictedEvent = predictor.predict()
   
                           try {
                               when (event.actionMasked) {
                                   MotionEvent.ACTION_DOWN -> {
                                       // First pointer - treat it as inking.
                                       view.requestUnbufferedDispatch(event)
                                       val pointerIndex = event.actionIndex
                                       val pointerId = event.getPointerId(pointerIndex)
                                       currentPointerId.value = pointerId
                                       currentStrokeId.value =
                                           inProgressStrokesView.startStroke(
                                               event = event,
                                               pointerId = pointerId,
                                               brush = defaultBrush
                                           )
                                       true
                                   }
   
                                   MotionEvent.ACTION_MOVE -> {
                                       val pointerId = checkNotNull(currentPointerId.value)
                                       val strokeId = checkNotNull(currentStrokeId.value)
   
                                       for (pointerIndex in 0 until event.pointerCount) {
                                           if (event.getPointerId(pointerIndex) != pointerId) continue
                                           inProgressStrokesView.addToStroke(
                                               event,
                                               pointerId,
                                               strokeId,
                                               predictedEvent
                                           )
                                       }
                                       true
                                   }
   
                                   MotionEvent.ACTION_UP -> {
                                       val pointerIndex = event.actionIndex
                                       val pointerId = event.getPointerId(pointerIndex)
                                       check(pointerId == currentPointerId.value)
                                       val currentStrokeId = checkNotNull(currentStrokeId.value)
                                       inProgressStrokesView.finishStroke(
                                           event,
                                           pointerId,
                                           currentStrokeId
                                       )
                                       view.performClick()
                                       true
                                   }
   
                                   MotionEvent.ACTION_CANCEL -> {
                                       val pointerIndex = event.actionIndex
                                       val pointerId = event.getPointerId(pointerIndex)
                                       check(pointerId == currentPointerId.value)
   
                                       val currentStrokeId = checkNotNull(currentStrokeId.value)
                                       inProgressStrokesView.cancelStroke(currentStrokeId, event)
                                       true
                                   }
   
                                   else -> false
                               }
                           } finally {
                               predictedEvent?.recycle()
                           }
   
                       }
                   rootView.setOnTouchListener(touchListener)
                   rootView.addView(inProgressStrokesView)
                   rootView
               },
           ) {
   
           }
       }
   }
   

4. Handle finished strokes

   Upon calling finishStroke(), the stroke is marked for completion. However, the finalization process isn't instantaneous. The stroke is fully processed and becomes accessible to your application shortly after finishStroke() is called, specifically when there are no other strokes in progress. This ensures that all drawing operations are concluded before the stroke is handed off to the client as finished.

   To retrieve finished strokes, you have two options:

   • Implement the InProgressStrokesFinishedListener interface within your activity or ViewModel, and register the listener with the InProgressStrokesView with addFinishedStrokesListener.
   • Use the getFinishedStrokes() method of InProgressStrokesView to obtain all finished strokes directly.

   class MyActivity : ComponentActivity(), InProgressStrokesFinishedListener {
     ...
   
     private val finishedStrokesState = mutableStateOf(emptySet<Stroke>())
   
     override fun onCreate(savedInstanceState: Bundle?) {
       ...
       inProgressStrokesView.addFinishedStrokesListener(this)
     }
   
     // ... (handle touch events)
   
     @UiThread
     override fun onStrokesFinished(strokes: Map<InProgressStrokeId, Stroke>) {
       finishedStrokesState.value += strokes.values
       inProgressStrokesView.removeFinishedStrokes(strokes.keys)
     }
   }
   

   Once you have retrieved the finished strokes, you can use CanvasStrokesRenderer to commit them to the screen.

   class MainActivity : ComponentActivity(), InProgressStrokesFinishedListener {
     private lateinit var inProgressStrokesView: InProgressStrokesView
     private val finishedStrokesState = MutableState<emptySet<Stroke>()>
   
     override fun onCreate(savedInstanceState: Bundle?) {
       inProgressStrokesView = InProgressStrokesView(this)
       inProgressStrokesView.addFinishedStrokesListener(this)
       canvasStrokeRenderer = CanvasStrokeRenderer.create()
       //...
       DrawingSurface(
         inProgressStrokesView = inProgressStrokesView,
         canvasStrokeRenderer = canvasStrokeRenderer,
         finishedStrokesState = finishedStrokesState
       )
       //...
       }
     //...
   }
   
   @SuppressLint("ClickableViewAccessibility")
   @Composable
   fun DrawingSurface(
       inProgressStrokesView: InProgressStrokesView,
       finishedStrokesState: Set<Stroke>
   ) {
       val canvasStrokeRenderer = CanvasStrokeRenderer.create()
       //...
   
       Box(modifier = Modifier.fillMaxSize()) {
           AndroidView(
               //...
           )
   
           Canvas(modifier = Modifier) {
               val canvasTransform = Matrix()
               drawContext.canvas.nativeCanvas.concat(canvasTransform)
               val canvas = drawContext.canvas.nativeCanvas
   
               finishedStrokesState.value.forEach { stroke ->
                   canvasStrokeRenderer.draw(stroke = stroke, canvas = canvas, strokeToScreenTransform = canvasTransform)
               }
           }
       }
   }