QTouchEvent Class

Description détaillée

Activation des événements tactiles

Les événements tactiles se produisent lorsque l'on appuie, relâche ou déplace un ou plusieurs points tactiles sur un dispositif tactile (tel qu'un écran tactile ou un track-pad). Pour recevoir des événements tactiles, les widgets doivent avoir l'attribut Qt::WA_AcceptTouchEvents défini et les éléments graphiques doivent avoir l'attribut acceptTouchEvents défini à true.

Lorsque vous utilisez des widgets basés sur QAbstractScrollArea, vous devez activer l'attribut Qt::WA_AcceptTouchEvents sur la zone de défilement viewport.

De la même manière que pour QMouseEvent, Qt Widgets saisit automatiquement chaque point de contact lors de la première pression à l'intérieur d'un widget, et le widget recevra toutes les mises à jour pour le point de contact jusqu'à ce qu'il soit relâché. Notez qu'il est possible qu'un widget reçoive des événements pour de nombreux points de contact et que plusieurs widgets puissent recevoir des événements de contact en même temps.

Gestion des événements

Tous les événements tactiles sont de type QEvent::TouchBegin, QEvent::TouchUpdate, QEvent::TouchEnd ou QEvent::TouchCancel. Réimplémentez QWidget::event() ou QAbstractScrollArea::viewportEvent() pour les widgets et QGraphicsItem::sceneEvent() pour les éléments d'une vue graphique afin de recevoir des événements tactiles.

Contrairement aux widgets, les QWindows reçoivent toujours les événements tactiles, il n'est pas nécessaire d'opter pour cette option. Lorsque l'on travaille directement avec QWindow, il suffit de réimplémenter QWindow::touchEvent().

Les événements QEvent::TouchUpdate et QEvent::TouchEnd sont envoyés au widget ou à l'élément qui a accepté l'événement QEvent::TouchBegin. Si l'événement QEvent::TouchBegin n'est pas accepté et n'est pas filtré par un filtre d'événement, aucun autre événement tactile n'est envoyé jusqu'au prochain QEvent::TouchBegin.

Certains systèmes peuvent envoyer un événement du type QEvent::TouchCancel. Lors de la réception de cet événement, les applications sont invitées à ignorer l'ensemble de la séquence tactile active. Par exemple, dans un système composé, le compositeur peut décider de traiter certains gestes comme des gestes à l'échelle du système. Lorsqu'une telle décision est prise (le geste est reconnu), les clients en sont informés par un événement QEvent::TouchCancel afin qu'ils puissent mettre à jour leur état en conséquence.

Les fonctions pointCount() et point() peuvent être utilisées pour accéder à des points de contact individuels et les parcourir.

La fonction points() renvoie une liste de tous les points de contact contenus dans l'événement. Notez que cette liste peut être vide, par exemple dans le cas d'un événement QEvent::TouchCancel. Chaque point est une instance de la classe QEventPoint. L'énumération QEventPoint::State décrit les différents états que peut avoir un point de contact.

Transmission et propagation des événements

Par défaut, QGuiApplication traduit le premier point de contact d'un QTouchEvent en QMouseEvent. Cela permet d'activer les événements tactiles sur des widgets existants qui ne gèrent pas normalement les QTouchEvent. Voir ci-dessous pour plus d'informations sur certaines considérations particulières à prendre en compte lors de cette opération.

QEvent::TouchBegin est le premier événement tactile envoyé à un widget. L'événement QEvent::TouchBegin contient un drapeau d'acceptation spécial qui indique si le récepteur veut l'événement. Par défaut, l'événement est accepté. Vous devez appeler ignore() si l'événement tactile n'est pas géré par votre widget. L'événement QEvent::TouchBegin est propagé dans la chaîne des widgets parents jusqu'à ce qu'un widget l'accepte avec accept() ou qu'un filtre d'événement le consomme. Pour les QGraphicsItems, l'événement QEvent::TouchBegin est propagé aux éléments situés sous la souris (de manière similaire à la propagation des événements de la souris pour les QGraphicsItems).

Regroupement des points de contact

Comme mentionné ci-dessus, il est possible que plusieurs widgets reçoivent des QTouchEvents en même temps. Cependant, Qt Widgets s'assure de ne jamais envoyer des événements QEvent::TouchBegin en double au même widget, ce qui pourrait théoriquement se produire lors de la propagation si, par exemple, l'utilisateur touchait 2 widgets distincts dans un QGroupBox et que les deux widgets ignoraient l'événement QEvent::TouchBegin.

Pour éviter cela, Qt regroupera les nouveaux points de contact en utilisant les règles suivantes :

• Lorsque le premier point de contact est détecté, le widget de destination est déterminé d'abord par l'emplacement sur l'écran et ensuite par les règles de propagation.
• Lorsque des points de contact supplémentaires sont détectés, Qt Widgets vérifie d'abord s'il existe des points de contact actifs sur un ancêtre ou un descendant du widget sous le nouveau point de contact. Si c'est le cas, le nouveau point de contact est groupé avec le premier, et le nouveau point de contact sera envoyé dans un seul QTouchEvent au widget qui a géré le premier point de contact. (Le widget situé sous le nouveau point de contact ne recevra pas d'événement).

Cela permet aux widgets frères de gérer les événements tactiles de manière indépendante tout en s'assurant que la séquence des QTouchEvents est toujours correcte.

Synthèse des événements souris et des événements tactiles

La livraison de QTouchEvent est indépendante de celle de QMouseEvent. Les drapeaux d'application Qt::AA_SynthesizeTouchForUnhandledMouseEvents et Qt::AA_SynthesizeMouseForUnhandledTouchEvents peuvent être utilisés pour activer ou désactiver la synthèse automatique des événements tactiles en événements de souris et des événements de souris en événements tactiles.

Mise en garde

• Comme mentionné ci-dessus, l'activation des événements tactiles signifie que plusieurs widgets peuvent recevoir des événements tactiles simultanément. Combiné à la gestion par défaut de QWidget::event() pour QTouchEvents, cela vous donne une grande flexibilité dans la conception d'interfaces utilisateur tactiles. Soyez conscient des implications. Par exemple, il est possible que l'utilisateur déplace une page QSlider avec un doigt et appuie sur une page QPushButton avec un autre. Les signaux émis par ces widgets seront entrelacés.
• La récursivité dans la boucle d'événements à l'aide de l'une des méthodes exec() (par exemple, QDialog::exec() ou QMenu::exec()) dans un gestionnaire d'événements QTouchEvent n'est pas prise en charge. Étant donné qu'il y a plusieurs destinataires d'événements, la récursion peut causer des problèmes, y compris, mais sans s'y limiter, des événements perdus et une récursion infinie inattendue.
• Les QTouchEvents ne sont pas affectés par une mouse grab ou une active pop-up widget. Le comportement des QTouchEvents est indéfini lors de l'ouverture d'une fenêtre contextuelle ou de la saisie de la souris alors qu'il y a plus d'un point de contact actif.