Gestes dans les widgets et la vue graphique

Qt comprend un cadre pour la programmation de gestes qui permet de former des gestes à partir d'une série d'événements, indépendamment des méthodes d'entrée utilisées. Un geste peut être un mouvement particulier de la souris, une action sur l'écran tactile ou une série d'événements provenant d'une autre source. La nature de l'entrée, l'interprétation du geste et l'action entreprise relèvent du choix du développeur.

Vue d'ensemble

QGesture est la classe centrale du cadre gestuel de Qt, fournissant un conteneur pour les informations sur les gestes effectués par l'utilisateur. QGesture expose des propriétés qui donnent des informations générales communes à tous les gestes, et celles-ci peuvent être étendues pour fournir des informations supplémentaires spécifiques à un geste. Les gestes courants de panoramique, de pincement et de glissement sont représentés par des classes spécialisées : QPanGesture, QPinchGesture et QSwipeGesture.

Les développeurs peuvent également mettre en œuvre de nouveaux gestes en sous-classant et en étendant la classe QGestureRecognizer. La prise en charge d'un nouveau geste implique la mise en œuvre d'un code permettant de reconnaître le geste à partir des événements d'entrée. Cette procédure est décrite dans la section Création de votre propre outil de reconnaissance de gestes.

Utilisation des gestes standard avec les widgets

Les gestes peuvent être activés pour les instances des sous-classes QWidget et QGraphicsObject. Tout au long de la documentation, un objet qui accepte une saisie gestuelle est appelé objet cible.

Pour activer un geste pour un objet cible, appelez sa fonction QWidget::grabGesture() ou QGraphicsObject::grabGesture() avec un argument décrivant le type de geste requis. Les types standard sont définis par l'enum Qt::GestureType et comprennent de nombreux gestes couramment utilisés.

for (Qt::GestureType gesture : gestures)
    grabGesture(gesture);

Dans le code ci-dessus, les gestes sont définis dans le constructeur de l'objet cible lui-même.

Gestion des événements

Lorsque l'utilisateur effectue un geste, les événements QGestureEvent sont transmis à l'objet cible et peuvent être gérés en réimplémentant la fonction de gestion QWidget::event() pour les widgets ou QGraphicsItem::sceneEvent() pour les objets graphiques.

Comme un objet cible peut souscrire à plus d'un type de geste, le message QGestureEvent peut contenir plus d'un message QGesture, indiquant que plusieurs gestes possibles sont actifs en même temps. Il appartient alors au widget de déterminer comment gérer ces gestes multiples et de choisir si certains doivent être annulés au profit d'autres.

Chaque QGesture contenu dans un objet QGestureEvent peut être accepté() ou ignoré() individuellement, ou tous ensemble. En outre, vous pouvez interroger les objets de données QGesture individuels (l'état) à l'aide de plusieurs getters.

Procédure standard pour la gestion des événements

Une page QGesture est acceptée par défaut lorsqu'elle arrive sur votre widget. Toutefois, une bonne pratique consiste à toujours accepter ou rejeter explicitement un geste. La règle générale est que, si vous acceptez un geste, vous l'utilisez. Si vous l'ignorez, c'est qu'il ne vous intéresse pas. Ignorer un geste peut signifier qu'il sera proposé à un autre objet cible ou qu'il sera annulé.

Chaque site QGesture passe par plusieurs états ; il existe une manière bien définie de changer d'état. En général, c'est l'intervention de l'utilisateur qui est à l'origine des changements d'état (en démarrant et en arrêtant l'interaction, par exemple), mais le widget peut également être à l'origine de ces changements d'état.

La première fois qu'un QGesture particulier est transmis à un widget ou à un élément graphique, il se trouve dans l'état Qt::GestureStarted. La manière dont vous traitez le geste à ce stade détermine si vous pouvez interagir avec lui par la suite.

• Accepter le geste signifie que le widget agit sur le geste et qu'il y aura des gestes suivants avec l'état Qt::GestureUpdated.
• Ignorer le geste signifie que le geste ne vous sera plus jamais proposé. Il sera également proposé à un widget parent ou à un élément.
• L'appel à setGestureCancelPolicy() sur le geste lorsqu'il est dans son état de départ et qu'il est également accepté peut entraîner l'annulation d'autres gestes.

L'utilisation de QGesture::CancelAllInContext pour annuler un geste entraînera l'annulation de tous les gestes, quel que soit leur état, à moins qu'ils ne soient explicitement acceptés. Cela signifie que les gestes actifs sur les enfants seront annulés. Cela signifie également que les gestes fournis dans le même QGestureEvent seront annulés si le widget les ignore. Cela peut être un moyen utile de filtrer tous les gestes à l'exception de celui qui vous intéresse.

Exemple de gestion d'événements

Pour des raisons pratiques, l'exemple de gestes d'image réimplémente la fonction générale de traitement event() et délègue les événements de gestes à une fonction spécialisée gestureEvent() :

bool ImageWidget::event(QEvent *event)
{
    if (event->type() == QEvent::Gesture)
        return gestureEvent(static_cast<QGestureEvent*>(event));
    return QWidget::event(event);
}

Les événements gestuels transmis à l'objet cible peuvent être examinés individuellement et traités de manière appropriée :

bool ImageWidget::gestureEvent(QGestureEvent *event)
{
    qCDebug(lcExample) << "gestureEvent():" << event;
    if (QGesture *swipe = event->gesture(Qt::SwipeGesture))
        swipeTriggered(static_cast<QSwipeGesture *>(swipe));
    else if (QGesture *pan = event->gesture(Qt::PanGesture))
        panTriggered(static_cast<QPanGesture *>(pan));
    if (QGesture *pinch = event->gesture(Qt::PinchGesture))
        pinchTriggered(static_cast<QPinchGesture *>(pinch));
    return true;
}

Pour répondre à un geste, il suffit d'obtenir l'objet QGesture livré dans le QGestureEvent envoyé à l'objet cible et d'examiner les informations qu'il contient.

void ImageWidget::swipeTriggered(QSwipeGesture *gesture)
{
    if (gesture->state() == Qt::GestureFinished) {
        if (gesture->swipeAngle() < 45 || gesture->swipeAngle() > 225) {
            // swipe direction right or down
            qCDebug(lcExample) << "swipeTriggered(): angle"
                               << gesture->swipeAngle() << "; swipe to next";
            goNextImage();
        } else {
            // swipe direction left or up
            qCDebug(lcExample) << "swipeTriggered(): angle"
                               << gesture->swipeAngle() << "; swipe to previous";
            goPrevImage();
        }
        update();
    }
}

Ici, nous examinons la direction dans laquelle l'utilisateur a fait glisser le widget et modifions son contenu en conséquence.

Création de votre propre outil de reconnaissance de gestes

La prise en charge d'un nouveau geste implique la création et l'enregistrement d'un nouvel outil de reconnaissance de geste. En fonction du processus de reconnaissance du geste, cela peut également impliquer la création d'un nouvel objet de geste.

Pour créer un nouvel outil de reconnaissance, vous devez sous-classer QGestureRecognizer afin de créer une classe de reconnaissance personnalisée. Il existe une fonction virtuelle que vous devez réimplémenter et deux autres qui peuvent être réimplémentées si nécessaire.

Filtrage des événements d'entrée

La fonction recognize() doit être réimplémentée. Cette fonction traite et filtre les événements d'entrée pour les objets cibles et détermine s'ils correspondent ou non au geste recherché par l'outil de reconnaissance.

Bien que la logique de reconnaissance des gestes soit implémentée dans cette fonction, éventuellement à l'aide d'une machine à états basée sur les enums Qt::GestureState, vous pouvez stocker des informations persistantes sur l'état du processus de reconnaissance dans l'objet QGesture fourni.

Votre fonction recognize() doit renvoyer une valeur de QGestureRecognizer::Result qui indique l'état de la reconnaissance pour un geste et un objet cible donnés. Cela permet de déterminer si un événement de geste sera transmis ou non à un objet cible.

Gestes personnalisés

Si vous choisissez de représenter un geste par une sous-classe QGesture personnalisée, vous devrez réimplémenter la fonction create() pour construire des instances de votre classe de geste au lieu des instances QGesture standard. Vous pouvez également utiliser les instances standard QGesture, mais leur ajouter des propriétés dynamiques supplémentaires pour exprimer les détails spécifiques du geste que vous souhaitez gérer.

Réinitialisation des gestes

Si vous utilisez des objets gestuels personnalisés qui doivent être réinitialisés ou traités de manière particulière lorsqu'un geste est annulé, vous devez réimplémenter la fonction reset() pour effectuer ces tâches spéciales.

Notez que les objets QGesture ne sont créés qu'une seule fois pour chaque combinaison d'objet cible et de type de geste, et qu'ils peuvent être réutilisés chaque fois que l'utilisateur tente d'effectuer le même type de geste sur l'objet cible. Par conséquent, il peut être utile de réimplémenter la fonction reset() pour faire le ménage après chaque tentative précédente de reconnaissance d'un geste.

Utilisation d'un nouvel outil de reconnaissance de gestes

Pour utiliser un reconnaissant de gestes, construisez une instance de votre sous-classe QGestureRecognizer et enregistrez-la avec l'application à l'aide de la fonction QGestureRecognizer::registerRecognizer(). Un reconnaisseur pour un type de geste donné peut être supprimé à l'aide de QGestureRecognizer::unregisterRecognizer().

Pour en savoir plus

L'exemple des gestes de l'image montre comment activer les gestes pour un widget dans une application simple de visualisation d'images.

Les gestes dans Qt Quick

Qt Quick ne dispose pas d'un système générique global de reconnaissance des gestes ; les composants individuels peuvent répondre aux événements tactiles de leur propre manière. Par exemple, PinchArea gère les gestes à deux doigts, Flickable permet de feuilleter le contenu avec un seul doigt et MultiPointTouchArea peut gérer un nombre arbitraire de points de contact et permettre au développeur de l'application d'écrire un code de reconnaissance de gestes personnalisé.