Gestes dans les widgets et la vue graphique

Qt intègre un framework de programmation des gestes capable de générer des gestes à partir d’une série d’événements, indépendamment des méthodes de saisie utilisées. Un geste peut correspondre à un mouvement particulier de la souris, à une action sur un é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 déclenchée sont laissées au choix du développeur.

Présentation

QGesture est la classe centrale du framework de gestes de Qt ; elle fournit un conteneur pour les informations relatives aux gestes effectués par l’utilisateur. La classe ` QGesture ` expose des propriétés fournissant des informations générales communes à tous les gestes ; celles-ci peuvent être étendues pour fournir des informations supplémentaires spécifiques à chaque geste. Les gestes courants de panoramique, de pincement et de balayage sont représentés par des classes spécialisées : ` QPanGesture`, ` QPinchGesture ` et ` QSwipeGesture`.

Les développeurs peuvent également implémenter de nouveaux gestes en créant des sous-classes et en étendant la classe ` QGestureRecognizer `. L'ajout de la prise en charge d'un nouveau geste implique l'implémentation d'un code permettant de reconnaître ce geste à partir des événements d'entrée. Cette procédure est décrite dans la section « Créer votre propre reconnaisseur de gestes ».

Utilisation des gestes standard avec les widgets

Les gestes peuvent être activés pour les instances des sous-classes de QWidget et QGraphicsObject. Un objet acceptant une entrée par geste est désigné tout au long de la documentation sous le nom d’« 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’énumération ` Qt::GestureType ` et incluent de nombreux gestes couramment utilisés.

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

Dans le code ci-dessus, les gestes sont configurés dans le constructeur de l’objet cible lui-même.

Gestion des événements

Lorsque l’utilisateur effectue un geste, des événements QGestureEvent sont transmis à l’objet cible ; ceux-ci 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 s’abonner à plusieurs types de gestes, l’ QGestureEvent peut contenir plusieurs QGesture, ce qui indique que plusieurs gestes possibles sont actifs simultanément. Il appartient alors au widget de déterminer comment gérer ces multiples gestes et de choisir si certains doivent être annulés au profit d’autres.

Chaque QGesture contenu dans un objet QGestureEvent peut être accepté (accepted()) ou ignoré (ignored()) individuellement, ou tous ensemble. De plus, vous pouvez interroger les objets de données individuels de l’ QGesture (l’état) à l’aide de plusieurs méthodes de lecture (getters).

Procédure standard de gestion des événements

Par défaut, un QGesture est accepté dès son arrivée dans votre widget. Cependant, il est recommandé de toujours accepter ou rejeter explicitement un geste. La règle générale est la suivante : si vous acceptez un geste, c’est que 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 « QGesture » passe par plusieurs états ; il existe une méthode bien définie pour changer d’état. Généralement, c’est l’entrée de l’utilisateur qui est à l’origine des changements d’état (en démarrant ou en arrêtant l’interaction, par exemple), mais le widget peut également provoquer des 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 gérez le geste à ce stade détermine si vous pourrez interagir avec lui ultérieurement.

• Accepter le geste signifie que le widget agit sur celui-ci et que d’autres gestes suivront avec l’état Qt::GestureUpdated.
• Ignorer le geste signifie que celui-ci ne vous sera plus jamais proposé. Il sera également proposé à un widget ou élément parent.
• L'appel de la fonction `setGestureCancelPolicy()` sur le geste alors qu'il se trouve dans son état initial 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 transmis dans la 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 des événements

Pour plus de commodité, l’exemple « Image Gestures » réimplémente la fonction de gestion générale ` event()` et délègue les événements de geste à 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 de geste 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 de récupérer l’objet ` QGesture ` transmis dans l’ 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éer son propre détecteur de gestes

Pour prendre en charge un nouveau geste, il faut créer et enregistrer un nouveau reconnaisseur de gestes. Selon le processus de reconnaissance du geste, cela peut également impliquer la création d’un nouvel objet de geste.

Pour créer un nouveau reconnaisseur, vous devez créer une sous-classe de ` QGestureRecognizer ` afin de définir une classe de reconnaisseur personnalisée. Il existe une fonction virtuelle que vous devez réimplémenter et deux autres qui peuvent être réimplémentées selon vos besoins.

Filtrage des événements d’entrée

La fonction recognize() doit être réimplémentée. Cette fonction gère et filtre les événements d'entrée entrants pour les objets cibles et détermine s'ils correspondent ou non au geste recherché par le reconnaisseur.

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 énumérations 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 type QGestureRecognizer::Result indiquant l’état de la reconnaissance pour un geste et un objet cible donnés. C’est ce qui détermine si un événement de geste sera transmis ou non à un objet cible.

Gestes personnalisés

Si vous choisissez de représenter un geste à l’aide d’une sous-classe personnalisée de ` QGesture `, vous devrez réimplémenter la fonction ` create()` afin de créer des instances de votre classe de geste à la place des instances standard de ` QGesture `. Vous pouvez également utiliser des instances standard de ` QGesture `, mais en leur ajoutant 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 de geste personnalisés qui doivent être réinitialisés ou géré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écifiques.

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 nettoyer après chaque tentative précédente de reconnaissance d’un geste.

Utilisation d’un nouveau reconnaisseur de gestes

Pour utiliser un reconnaisseur de gestes, créez une instance de votre sous-classe de ` QGestureRecognizer `, puis enregistrez-la auprès de l’application à l’aide de ` QGestureRecognizer::registerRecognizer()`. Un reconnaisseur pour un type de geste donné peut être supprimé à l’aide de ` QGestureRecognizer::unregisterRecognizer()`.

Pour en savoir plus

L’exemple « Image Gestures » 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 reconnaisseur de gestes global générique ; ce sont plutôt les composants individuels qui peuvent répondre aux événements tactiles à leur manière. Par exemple, la classe ` PinchArea ` gère les gestes à deux doigts, ` Flickable ` permet de faire défiler le contenu d’un seul doigt, et ` MultiPointTouchArea ` peut gérer un nombre arbitraire de points de contact et permet au développeur d’application d’écrire du code personnalisé de reconnaissance de gestes.