Gérer les gestes tactiles multipoints

Essayer Compose
Jetpack Compose est le kit d'outils d'interface utilisateur recommandé pour Android. Découvrez comment utiliser les entrées tactiles et autres dans Compose.
Gestes multitouch →

Un geste multitouch se produit lorsque plusieurs pointeurs (doigts) appuient sur l'écran en même temps. Ce document explique comment détecter les gestes impliquant plusieurs pointeurs.

Suivre plusieurs pointeurs

Lorsque plusieurs pointeurs appuient sur l'écran en même temps, le système génère les événements tactiles suivants :

  • ACTION_DOWN: envoyé lorsque le premier pointeur appuie sur l'écran. Cela lance le geste. Les données de pointeur pour ce pointeur se trouvent toujours à l'index 0 dans le MotionEvent.
  • ACTION_POINTER_DOWN: envoyé lorsque des pointeurs supplémentaires entrent dans l'écran après le premier. Vous pouvez obtenir l'index du pointeur qui vient de s'afficher à l'aide de getActionIndex().
  • ACTION_MOVE: envoyé lorsqu'une modification se produit dans un geste, impliquant un nombre quelconque de pointeurs.
  • ACTION_POINTER_UP: envoyé lorsqu'un pointeur non principal s'affiche. Vous pouvez obtenir l'index du pointeur qui vient de s'afficher à l'aide de getActionIndex().
  • ACTION_UP: envoyé lorsque le dernier pointeur quitte l'écran.
  • ACTION_CANCEL: indique que l'ensemble du geste, y compris tous les pointeurs, est annulé.

Démarrer et terminer des gestes

Un geste est une série d'événements commençant par un événement ACTION_DOWN et se terminant par un événement ACTION_UP ou ACTION_CANCEL. Un seul geste est actif à la fois. Les actions DOWN, MOVE, UP et CANCEL s'appliquent à l'ensemble du geste. Par exemple, un événement avec ACTION_MOVE peut indiquer un mouvement pour tous les pointeurs à ce moment-là.

Suivre les pointeurs

Utilisez l'index et l'ID du pointeur pour suivre les positions des pointeurs individuels dans un MotionEvent.

  • Index: un MotionEvent stocke les informations du pointeur dans un tableau. L'index d'un pointeur est sa position dans ce tableau. La plupart des méthodes MotionEvent utilisent l'index du pointeur comme paramètre, plutôt que l'ID du pointeur.
  • ID : chaque pointeur possède également un mappage d'ID qui reste persistant entre les événements tactiles pour permettre le suivi d'un pointeur individuel tout au long du geste.

Les pointeurs individuels apparaissent dans un événement de mouvement dans un ordre non défini. Ainsi, l'index d'un pointeur peut changer d'un événement à l'autre, mais l'ID du pointeur reste constant tant que le pointeur reste actif. Utilisez la méthode getPointerId() pour obtenir l'ID d'un pointeur afin de le suivre dans tous les événements de mouvement suivants d'un geste. Ensuite, pour les événements de mouvement successifs, utilisez la méthode findPointerIndex() pour obtenir l'index du pointeur pour un ID de pointeur donné dans cet événement de mouvement. Exemple :

Kotlin

private var mActivePointerId: Int = 0

override fun onTouchEvent(event: MotionEvent): Boolean {
    ...
    // Get the pointer ID.
    mActivePointerId = event.getPointerId(0)

    // ... Many touch events later...

    // Use the pointer ID to find the index of the active pointer
    // and fetch its position.
    val (x: Float, y: Float) = event.findPointerIndex(mActivePointerId).let { pointerIndex ->
        // Get the pointer's current position.
        event.getX(pointerIndex) to event.getY(pointerIndex)
    }
    ...
}

Java

private int mActivePointerId;

public boolean onTouchEvent(MotionEvent event) {
    ...
    // Get the pointer ID.
    mActivePointerId = event.getPointerId(0);

    // ... Many touch events later...

    // Use the pointer ID to find the index of the active pointer
    // and fetch its position.
    int pointerIndex = event.findPointerIndex(mActivePointerId);
    // Get the pointer's current position.
    float x = event.getX(pointerIndex);
    float y = event.getY(pointerIndex);
    ...
}

Pour prendre en charge plusieurs pointeurs tactiles, vous pouvez mettre en cache tous les pointeurs actifs avec leurs ID au moment de leur événement ACTION_POINTER_DOWN et ACTION_DOWN individuel. Supprimez les pointeurs de votre cache lors de leurs événements ACTION_POINTER_UP et ACTION_UP. Ces ID mis en cache peuvent vous aider à gérer correctement d'autres événements d'action. Par exemple, lors du traitement d'un événement ACTION_MOVE, recherchez l'index de chaque ID de pointeur actif mis en cache, récupérez les coordonnées du pointeur à l'aide des fonctions getX() et getY(), puis comparez ces coordonnées avec vos coordonnées mises en cache pour découvrir quels pointeurs ont été déplacés.

N'utilisez la fonction getActionIndex() qu'avec les événements ACTION_POINTER_UP et ACTION_POINTER_DOWN. N'utilisez pas cette fonction avec les événements ACTION_MOVE, car elle renvoie toujours 0.

Récupérer les actions MotionEvent

Utilisez la getActionMasked() méthode ou la version de compatibilité MotionEventCompat.getActionMasked() pour récupérer l'action d'un MotionEvent. Contrairement à la méthode getAction() précédente, getActionMasked() est conçue pour fonctionner avec plusieurs pointeurs. Elle renvoie l'action sans les index de pointeur. Pour les actions avec un index de pointeur valide, utilisez getActionIndex() pour renvoyer l'index des pointeurs associés à l'action, comme illustré dans l'extrait de code suivant :

Kotlin

val (xPos: Int, yPos: Int) = MotionEventCompat.getActionMasked(event).let { action ->
    Log.d(DEBUG_TAG, "The action is ${actionToString(action)}")
    // Get the index of the pointer associated with the action.
    MotionEventCompat.getActionIndex(event).let { index ->
        // The coordinates of the current screen contact, relative to
        // the responding View or Activity.
        MotionEventCompat.getX(event, index).toInt() to MotionEventCompat.getY(event, index).toInt()
    }
}

if (event.pointerCount > 1) {
    Log.d(DEBUG_TAG, "Multitouch event")

} else {
    // Single touch event.
    Log.d(DEBUG_TAG, "Single touch event")
}

...

// Given an action int, returns a string description.
fun actionToString(action: Int): String {
    return when (action) {
        MotionEvent.ACTION_DOWN -> "Down"
        MotionEvent.ACTION_MOVE -> "Move"
        MotionEvent.ACTION_POINTER_DOWN -> "Pointer Down"
        MotionEvent.ACTION_UP -> "Up"
        MotionEvent.ACTION_POINTER_UP -> "Pointer Up"
        MotionEvent.ACTION_OUTSIDE -> "Outside"
        MotionEvent.ACTION_CANCEL -> "Cancel"
        else -> ""
    }
}

Java

int action = MotionEventCompat.getActionMasked(event);
// Get the index of the pointer associated with the action.
int index = MotionEventCompat.getActionIndex(event);
int xPos = -1;
int yPos = -1;

Log.d(DEBUG_TAG,"The action is " + actionToString(action));

if (event.getPointerCount() > 1) {
    Log.d(DEBUG_TAG,"Multitouch event");
    // The coordinates of the current screen contact, relative to
    // the responding View or Activity.
    xPos = (int)MotionEventCompat.getX(event, index);
    yPos = (int)MotionEventCompat.getY(event, index);

} else {
    // Single touch event.
    Log.d(DEBUG_TAG,"Single touch event");
    xPos = (int)MotionEventCompat.getX(event, index);
    yPos = (int)MotionEventCompat.getY(event, index);
}
...

// Given an action int, returns a string description
public static String actionToString(int action) {
    switch (action) {

        case MotionEvent.ACTION_DOWN: return "Down";
	case MotionEvent.ACTION_MOVE: return "Move";
	case MotionEvent.ACTION_POINTER_DOWN: return "Pointer Down";
	case MotionEvent.ACTION_UP: return "Up";
	case MotionEvent.ACTION_POINTER_UP: return "Pointer Up";
	case MotionEvent.ACTION_OUTSIDE: return "Outside";
	case MotionEvent.ACTION_CANCEL: return "Cancel";
    }
    return "";
}
Figure 1. Modèles de dessin multitouch patterns.

Ressources supplémentaires

Pour en savoir plus sur les événements d'entrée, consultez les références suivantes :