Rifiuti del palmo della mano dello stilo

Icona di valutazione a cinque stelle

Uno stilo può essere uno strumento eccezionalmente produttivo e creativo. Tuttavia, quando gli utenti disegnano, scrivono o interagiscono con un'app utilizzando uno stilo, a volte toccano lo schermo con il palmo della mano. L'evento touch può essere segnalato alla tua app prima che il sistema lo riconosca e lo ignori come tocco accidentale del palmo.

Best practice

La tua app deve identificare gli eventi touch estranei e ignorarli. In Jetpack Compose, puoi accedere all'oggetto MotionEvent Android sottostante da un PointerEvent. Controlla MotionEvent per ACTION_CANCEL, che indica che un gesto deve essere interrotto e potrebbe essere necessario eseguirne il rollback. Su Android 13 (livello API 33) e versioni successive, controlla il flag FLAG_CANCELED negli eventi ACTION_CANCEL e ACTION_POINTER_UP, che fornisce un forte indicatore del fatto che il tocco non era intenzionale, ad esempio un tocco con il palmo della mano.

Ingredienti

  • Modifier.pointerInput(): il modificatore di Compose utilizzato per elaborare l'input del puntatore.
  • PointerEvent: rappresenta un evento di puntatore in Compose, che contiene una o più modifiche.
  • PointerEvent.motionEvent: proprietà di estensione che fornisce l'accesso all'oggetto MotionEvent Android sottostante (nullable).
  • MotionEvent: rappresenta gli eventi di tocco e movimento. Contiene le informazioni necessarie per determinare se un evento deve essere ignorato.
  • ACTION_CANCEL: costante MotionEvent che indica che un gesto è stato annullato; il gesto deve essere interrotto e potrebbe essere necessario eseguirne il rollback.
  • ACTION_POINTER_UP: costante MotionEvent che indica che un puntatore diverso dal primo è stato sollevato (ovvero non è più a contatto con lo schermo del dispositivo).
  • FLAG_CANCELED: costante MotionEvent che indica che il puntatore che si sposta verso l'alto ha causato un evento touch involontario. Aggiunto agli eventi ACTION_POINTER_UP e ACTION_CANCEL su Android 13 (livello API 33) e versioni successive.

Passaggi

Esamina gli oggetti MotionEvent inviati alla tua app. Utilizza le API MotionEvent per determinare le caratteristiche degli eventi:

  • Eventi con un solo puntatore: controlla la presenza di ACTION_CANCEL, che indica che il gesto deve essere interrotto. Su Android 13 e versioni successive, controlla anche la presenza di FLAG_CANCELED per confermare che il tocco non era intenzionale.
  • Eventi con più puntatori: su Android 13 e versioni successive, controlla ACTION_POINTER_UP e FLAG_CANCELED per identificare i tocchi involontari.

Rispondi a questi eventi interrompendo il gesto e annullando eventuali modifiche temporanee.

1. Acquisisci oggetti di eventi di movimento

Utilizza Modifier.pointerInput per elaborare l'input del puntatore su un componibile. All'interno dell'ambito di input del puntatore, utilizza awaitPointerEventScope e awaitPointerEvent per ricevere gli eventi e recupera l'oggetto MotionEvent Android sottostante utilizzando la proprietà motionEvent:

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent
                        if (motionEvent != null) {
                            // Process motion event.
                        }
                    }
                }
            }
    )

2. Determina l'azione e i flag dell'evento

Controlla MotionEvent per ACTION_CANCEL, che indica un evento con un singolo puntatore su tutti i livelli API. Su Android 13 e versioni successive, controlla ACTION_POINTER_UP per FLAG_CANCELED:

import androidx.compose.ui.input.pointer.pointerInput
    Box(
        modifier = Modifier
            .fillMaxSize()
            .pointerInput(Unit) {
                awaitPointerEventScope {
                    while (true) {
                        val event = awaitPointerEvent()
                        val motionEvent = event.motionEvent ?: continue

                        when (motionEvent.actionMasked) {
                            MotionEvent.ACTION_CANCEL -> {
                                // Process canceled single-pointer motion event for all SDK versions.
                            }
                            MotionEvent.ACTION_POINTER_UP -> {
                                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU &&
                                    (motionEvent.flags and MotionEvent.FLAG_CANCELED) == MotionEvent.FLAG_CANCELED
                                ) {
                                    // Process canceled multi-pointer motion event for Android 13 and higher.
                                }
                            }
                        }
                    }
                }
            }
    )

3. Annulla il gesto

Una volta identificato un tocco con il palmo, puoi annullare gli effetti sullo schermo del gesto.

L'app deve conservare una cronologia delle azioni dell'utente in modo che gli input involontari, come i tocchi con il palmo della mano, possano essere annullati. Per un esempio, consulta Implementa un'app di disegno di base nel codelab Migliora il supporto dello stilo in un'app per Android.

Risultati

Ora la tua app può identificare e rifiutare i tocchi con il palmo per gli eventi con più puntatori su Android 13 e livelli API successivi e per gli eventi con un solo puntatore su tutti i livelli API.

Risorse aggiuntive

Per ulteriori informazioni, consulta le seguenti risorse: