HoverHandler QML Type
Gestionnaire pour le survol de la souris et de la tablette. Plus d'informations...
| Import Statement: | import QtQuick |
| Inherits: |
Propriétés
- acceptedDevices : flags
- acceptedModifiers : flags
- acceptedPointerTypes : flags
- active : bool
- blocking : bool
(since 6.3) - cursorShape : Qt::CursorShape
- enabled : bool
- grabPermissions : flags
- hovered : bool
- margin : real
- parent : Item
- point : handlerPoint
- target : Item
Signaux
- canceled(eventPoint point)
- grabChanged(PointerDevice::GrabTransition transition, eventPoint point)
Description détaillée
HoverHandler détecte le passage du curseur de la souris ou du stylet de la tablette.
Une liaison à la propriété hovered est le moyen le plus simple de réagir lorsque le curseur entre ou sort de l'élément parent. La propriété point fournit plus de détails, notamment la position du curseur. Les propriétés acceptedDevices, acceptedPointerTypes et acceptedModifiers peuvent être utilisées pour limiter le comportement à la détection du survol de certains types d'appareils ou du maintien d'une touche de modification.
La propriété cursorShape permet de changer le curseur lorsque hovered devient true.
Voir aussi MouseArea, PointHandler, et Qt Quick Exemples - Pointer Handlers.
Documentation sur les propriétés
acceptedDevices : flags |
Types de dispositifs de pointage pouvant activer le gestionnaire de pointeur.
Par défaut, cette propriété est définie sur PointerDevice.AllDevices. Si vous la définissez sur une combinaison OU de types de périphériques, elle ignorera les événements de pointeur provenant des périphériques non correspondants.
Par exemple, un élément peut répondre au survol de la souris d'une certaine manière et au survol du stylet d'une autre manière, avec deux gestionnaires :
import QtQuick Rectangle { width: 150; height: 50; radius: 3 color: mouse.hovered ? "goldenrod" : stylus.hovered ? "tomato" : "wheat" HoverHandler { id: stylus acceptedDevices: PointerDevice.Stylus cursorShape: Qt.CrossCursor } HoverHandler { id: mouse acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad cursorShape: Qt.PointingHandCursor } }
Les types de périphériques disponibles sont les suivants :
| Constante | Description |
|---|---|
PointerDevice.Mouse | Une souris. |
PointerDevice.TouchScreen | Un écran tactile. |
PointerDevice.TouchPad | Un pavé tactile ou trackpad. |
PointerDevice.Stylus | Un stylet sur une tablette graphique. |
PointerDevice.Airbrush | Un aérographe sur une tablette graphique. |
PointerDevice.Puck | Un numériseur avec un réticule, sur une tablette graphique. |
PointerDevice.AllDevices | Tout type de dispositif de pointage. |
Remarque : toutes les plateformes ne sont pas encore en mesure de faire la distinction entre la souris et le pavé tactile ; et sur celles qui le font, vous voudrez souvent faire en sorte que le comportement de la souris et du pavé tactile soit le même.
Voir également QInputDevice::DeviceType.
acceptedModifiers : flags |
Si cette propriété est définie, un événement de survol n'est traité que si les modificateurs de clavier indiqués sont activés. L'événement est ignoré sans les modificateurs.
Cette propriété est définie par défaut sur Qt.KeyboardModifierMask, ce qui permet de traiter les événements de survol sans tenir compte des touches de modification.
Par exemple, un site Item peut avoir deux gestionnaires du même type, dont l'un n'est activé que si l'on appuie sur les modificateurs de clavier requis :
import QtQuick Rectangle { width: 150; height: 50; radius: 3 color: control.hovered ? "goldenrod" : shift.hovered ? "wheat" : "beige" HoverHandler { id: control acceptedModifiers: Qt.ControlModifier cursorShape: Qt.PointingHandCursor } HoverHandler { id: shift acceptedModifiers: Qt.ShiftModifier cursorShape: Qt.CrossCursor } }
Les modificateurs disponibles sont les suivants :
| Constante | Description |
|---|---|
Qt.NoModifier | Aucune touche de modification n'est autorisée. |
Qt.ShiftModifier | La touche Shift du clavier doit être enfoncée. |
Qt.ControlModifier | Une touche Ctrl du clavier doit être enfoncée. |
Qt.AltModifier | Une touche Alt du clavier doit être enfoncée. |
Qt.MetaModifier | Une touche Meta du clavier doit être enfoncée. |
Qt.KeypadModifier | Une touche du clavier doit être enfoncée. |
Qt.GroupSwitchModifier | Une touche Mode_switch du clavier doit être enfoncée. X11 uniquement (sauf s'il est activé sous Windows par un argument de ligne de commande). |
Qt.KeyboardModifierMask | Le gestionnaire ignore les touches de modification. |
Voir également Qt::KeyboardModifier.
acceptedPointerTypes : flags |
Types d'instruments de pointage (générique, stylet, gomme, etc.) pouvant activer le gestionnaire de pointeurs.
Par défaut, cette propriété est définie sur PointerDevice.AllPointerTypes. Si vous la définissez sur une combinaison OU de types de périphériques, les événements non correspondants seront ignorés.
Par exemple, vous pouvez fournir un retour d'information en changeant le curseur selon qu'un stylet ou une gomme se trouve au-dessus d'une tablette graphique :
import QtQuick Rectangle { id: rect width: 150; height: 150 HoverHandler { id: stylus acceptedPointerTypes: PointerDevice.Pen cursorShape: Qt.CrossCursor } HoverHandler { id: eraser acceptedPointerTypes: PointerDevice.Eraser cursorShape: Qt.BlankCursor target: Image { parent: rect source: "images/cursor-eraser.png" visible: eraser.hovered x: eraser.point.position.x y: eraser.point.position.y - 32 } } }
Les types de pointeurs disponibles sont les suivants :
| Constante | Description |
|---|---|
PointerDevice.Generic | Une souris ou un périphérique émulant une souris. |
PointerDevice.Finger | Un doigt sur un écran tactile (la détection du survol est peu probable). |
PointerDevice.Pen | Un stylet sur une tablette graphique. |
PointerDevice.Eraser | Une gomme sur une tablette graphique. |
PointerDevice.Cursor | Un numériseur avec un réticule sur une tablette graphique. |
PointerDevice.AllPointerTypes | Tout type de dispositif de pointage. |
Voir également QPointingDevice::PointerType.
active : bool |
Ceci tient true chaque fois que ce gestionnaire d'entrée a pris l'entière responsabilité de transmettre un ou plusieurs eventPoints, en prenant avec succès un contrôle exclusif de ces points. Cela signifie qu'il tient ses propriétés à jour en fonction des mouvements de ces eventPoints et qu'il manipule activement son target (le cas échéant).
blocking : bool |
Si ce gestionnaire empêche d'autres éléments ou gestionnaires situés derrière lui d'être survolés en même temps. Cette propriété est false par défaut.
Cette propriété a été introduite dans Qt 6.3.
cursorShape : Qt::CursorShape |
Cette propriété contient la forme du curseur qui apparaîtra lorsque hovered est true et qu'aucun autre gestionnaire ne le remplace.
Les formes de curseur disponibles sont les suivantes
- Qt.ArrowCursor
- Qt.UpArrowCursor
- Qt.CrossCursor
- Qt.WaitCursor
- Qt.IBeamCursor
- Qt.SizeVerCursor
- Qt.SizeHorCursor
- Qt.SizeBDiagCursor
- Qt.SizeFDiagCursor
- Qt.SizeAllCursor
- Qt.BlankCursor
- Qt.SplitVCursor
- Qt.SplitHCursor
- Qt.PointingHandCursor
- Qt.ForbiddenCursor
- Qt.WhatsThisCursor
- Qt.BusyCursor
- Qt.OpenHandCursor
- Qt.ClosedHandCursor
- Qt.DragCopyCursor
- Qt.DragMoveCursor
- Qt.DragLinkCursor
La valeur par défaut de cette propriété n'est pas définie, ce qui permet à tout gestionnaire actif sur le même élément parent de déterminer la forme du curseur. Cette propriété peut être ramenée à sa valeur initiale en lui attribuant la valeur undefined.
Si un gestionnaire ayant défini cursorShape est active, ce curseur apparaîtra. Dans le cas contraire, si le HoverHandler a un cursorShape défini, ce curseur apparaîtra. Sinon, c'est le site cursor de l'élément parent qui s'affiche.
Remarque : lorsque cette propriété n'a pas été définie ou qu'elle a été définie à undefined, la lecture de la valeur renverra Qt.ArrowCursor.
Voir également Qt::CursorShape et QQuickItem::cursor().
enabled : bool |
Si un site PointerHandler est désactivé, il rejettera tous les événements et aucun signal ne sera émis.
grabPermissions : flags |
Cette propriété spécifie les autorisations lorsque la logique de ce gestionnaire décide de prendre en charge la saisie exclusive, ou lorsqu'il lui est demandé d'approuver la prise en charge ou l'annulation de la saisie par un autre gestionnaire.
| Constante | Description |
|---|---|
PointerHandler.TakeOverForbidden | Ce gestionnaire ne prend ni ne donne la permission de saisie à aucun type d'élément ou de gestionnaire. |
PointerHandler.CanTakeOverFromHandlersOfSameType | Ce gestionnaire peut prendre la prise exclusive d'un autre gestionnaire de la même classe. |
PointerHandler.CanTakeOverFromHandlersOfDifferentType | Ce handler peut prendre l'exclusivité de la prise de n'importe quel type de handler. |
PointerHandler.CanTakeOverFromItems | Ce gestionnaire peut s'approprier l'exclusivité de n'importe quel type d'objet. |
PointerHandler.CanTakeOverFromAnything | Ce handler peut s'approprier l'exclusivité de n'importe quel type d'objet ou de handler. |
PointerHandler.ApprovesTakeOverByHandlersOfSameType | Ce handler autorise un autre handler de la même classe à s'emparer de la prise. |
PointerHandler.ApprovesTakeOverByHandlersOfDifferentType | Ce handler autorise n'importe quel type de handler à s'emparer de la prise. |
PointerHandler.ApprovesTakeOverByItems | Ce handler autorise n'importe quel type d'item à prendre la prise. |
PointerHandler.ApprovesCancellation | Ce gestionnaire permet à sa prise d'être fixée à null. |
PointerHandler.ApprovesTakeOverByAnything | Ce gestionnaire autorise n'importe quel type d'élément ou de gestionnaire à s'emparer de la prise. |
La valeur par défaut est PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, ce qui permet la plupart des scénarios de prise de contrôle mais évite, par exemple, que deux PinchHandler ne se disputent les mêmes points de contact.
hovered : bool |
S'applique chaque fois que le curseur d'un dispositif de pointage (souris ou tablette) se trouve à l'intérieur des limites de l'élément parent, prolongées par l'élément margin, le cas échéant.
margin : real |
La marge au-delà des limites de l'élément parent dans laquelle un eventPoint peut activer ce gestionnaire. Par exemple, sur un site PinchHandler où le site target est également le site parent, il est utile de fixer cette distance à au moins la moitié de la largeur du doigt d'un utilisateur typique, de sorte que si le site parent a été réduit à une taille très petite, le geste de pincement reste possible. Par ailleurs, si un bouton basé sur TapHandler est placé près du bord de l'écran, il peut être utilisé pour respecter la loi de Fitts : réagir aux clics de souris sur le bord de l'écran même si le bouton est visuellement éloigné du bord de quelques pixels.
La valeur par défaut est 0.

parent : Item |
Le site Item qui est la portée du gestionnaire ; l'élément dans lequel il a été déclaré. Le gestionnaire traitera les événements au nom de cet élément, ce qui signifie qu'un événement de pointeur est pertinent si au moins l'un de ses eventPoints se produit à l'intérieur de l'élément. Initialement, target() est le même, mais il peut être réaffecté.
Voir également target et QObject::parent().
point : handlerPoint |
Le eventPoint en cours de traitement. Si aucun point n'est en cours de traitement, cet objet est réinitialisé aux valeurs par défaut (toutes les coordonnées sont à 0).
target : Item |
L'élément que ce gestionnaire va manipuler.
Par défaut, il est identique à parent, l'élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un élément différent, afin de gérer des événements dans un élément mais d'en manipuler un autre ; ou sur null, pour désactiver le comportement par défaut et faire quelque chose d'autre à la place.
Documentation sur les signaux
canceled(eventPoint point) |
Si ce gestionnaire a déjà saisi l'objet donné point, ce signal est émis lorsque la saisie est volée par un autre gestionnaire de pointeurs ou un autre objet.
Note : Le gestionnaire correspondant est onCanceled.
grabChanged(PointerDevice::GrabTransition transition, eventPoint point) |
Ce signal est émis lorsque la prise a changé d'une manière ou d'une autre, ce qui est pertinent pour ce gestionnaire.
Le transition (verbe) indique ce qui s'est passé. Le point (objet) est le point qui a été saisi ou désaisi.
Les valeurs valides pour transition sont les suivantes
| Constante | Description |
|---|---|
PointerDevice.GrabExclusive | Ce gestionnaire a pris la responsabilité principale du traitement de point. |
PointerDevice.UngrabExclusive | Ce gestionnaire a renoncé à sa prise exclusive précédente. |
PointerDevice.CancelGrabExclusive | La prise exclusive de ce gestionnaire a été reprise ou annulée. |
PointerDevice.GrabPassive | Ce gestionnaire a acquis une prise passive, pour surveiller le point. |
PointerDevice.UngrabPassive | Ce handler a renoncé à sa précédente prise passive. |
PointerDevice.CancelGrabPassive | La prise passive précédente de ce gestionnaire s'est terminée de manière anormale. |
Note : Le gestionnaire correspondant est onGrabChanged.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.