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 l'écran tactile et la saisie dans Compose.

On parle de geste multipoint lorsque plusieurs pointeurs (doigts) appuient simultanément sur l'écran. Ce document explique comment détecter des gestes qui impliquent plusieurs pointeurs.

Suivre plusieurs pointeurs

Lorsque plusieurs pointeurs appuient simultanément sur l'écran, le système génère les événements tactiles suivants:

  • ACTION_DOWN : envoyé lorsque le premier pointeur appuie sur l'écran. Cela déclenche le geste. Les données de ce pointeur se trouvent toujours à l'index 0 dans 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 tomber en panne à l'aide de getActionIndex().
  • ACTION_MOVE : envoyé lorsqu'une modification se produit dans un geste, impliquant un nombre illimité de pointeurs.
  • ACTION_POINTER_UP : envoyé lorsqu'un pointeur non principal augmente. Vous pouvez obtenir l'index du pointeur qui vient d'augmenter à 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é.

Gestes de début et de fin

Un geste est une série d'événements qui commencent par un événement ACTION_DOWN et se terminent par un événement ACTION_UP ou ACTION_CANCEL. Il n'y a qu'un seul geste 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 vers le bas à ce moment précis.

Gardez une trace des pointeurs

Utilisez l'index et l'ID du pointeur pour suivre la position de chaque pointeur dans une MotionEvent.

  • Index: un MotionEvent stocke les informations de pointeur dans un tableau. L'index d'un pointeur est sa position dans ce tableau. La plupart des méthodes MotionEvent utilisent l'index de pointeur comme paramètre plutôt que son ID.
  • 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 de pointeur d'un 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 pour tous les événements de mouvement ultérieurs d'un geste. Ensuite, pour les événements de mouvement successif, utilisez la méthode findPointerIndex() afin d'obtenir l'index de pointeur pour un ID de pointeur donné dans cet événement de mouvement. Par 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 accepter plusieurs pointeurs tactiles, vous pouvez mettre en cache tous les pointeurs actifs avec leur ID au moment de l'événement ACTION_POINTER_DOWN et ACTION_DOWN. 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 identifier les pointeurs déplacés.

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

Récupérer les actions MotionEvent

Utilisez la méthode getActionMasked() 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çu pour fonctionner avec plusieurs pointeurs. Elle renvoie l'action sans les index du pointeur. Pour les actions ayant un index de pointeur valide, utilisez getActionIndex() pour renvoyer l'index des pointeurs associés à l'action, comme indiqué 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 multipoint

Ressources supplémentaires

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