HoverHandler QML Type

Gestionnaire de survol pour souris et tablette. En savoir plus...

• Liste de tous les membres, y compris les membres hérités

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 survol du curseur de la souris ou du stylet d'une tablette.

Un lien vers la propriété ` hovered ` constitue le moyen le plus simple de réagir lorsque le curseur entre dans l’élément ` parent ` ou en sort. La propriété ` point ` fournit davantage de détails, notamment la position du curseur. Les propriétés ` acceptedDevices`, ` acceptedPointerTypes` et ` acceptedModifiers ` peuvent être utilisées pour affiner le comportement afin de détecter le survol de types spécifiques de périphériques ou lorsque une touche de modification est enfoncée.

La propriété ` cursorShape ` permet de modifier l’apparence du curseur dès que la propriété ` hovered ` passe à la valeur ` true`.

Voir également les exemples relatifs aux propriétésMouseArea, PointHandler et Qt Quick – Gestionnaires de pointeur.

Documentation sur les propriétés

acceptedDevices : flags

Les types de périphériques de pointage susceptibles d'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 qui ne correspondent pas.

Par exemple, un élément peut être configuré pour réagir différemment au survol de la souris et au survol du stylet, grâce à 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 :

Voir également QInputDevice::DeviceType.

acceptedModifiers : flags

Si cette propriété est définie, un événement de survol n'est géré que si les touches de modification spécifiées sont enfoncées. L'événement est ignoré en l'absence de ces touches de modification.

Par défaut, cette propriété est définie sur « Qt.KeyboardModifierMask », ce qui entraîne la gestion des événements de survol indépendamment de toute touche de modification.

Par exemple, un « Item » peut comporter deux gestionnaires du même type, dont l’un n’est activé que si les touches de modification requises sont enfoncées :

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 :

Voir également Qt::KeyboardModifier.

acceptedPointerTypes : flags

Les types de périphériques de pointage (générique, stylet, gomme, etc.) pouvant déclencher le gestionnaire de pointeur.

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, elle ignorera les événements provenant de périphériques ne correspondant pas à cette combinaison.

Par exemple, vous pouvez fournir un retour d'information en modifiant le curseur selon qu'un stylet ou une gomme survole 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 :

Voir aussi QPointingDevice::PointerType.

active : bool [read-only]

Cette propriété prend la valeur « true » dès lors que ce gestionnaire d’entrée a pris la responsabilité exclusive de la gestion d’un ou plusieurs « eventPoints », en ayant réussi à les «saisir» de manière exclusive. Cela signifie qu’il maintient ses propriétés à jour en fonction des mouvements de ces «eventPoints» et qu’il manipule activement ses « target » (le cas échéant).

blocking : bool [since 6.3]

Indique si ce gestionnaire empêche le survol simultané d'autres éléments ou gestionnaires situés derrière lui. Cette propriété est définie par défaut sur « false ».

Cette propriété a été introduite dans Qt 6.3.

cursorShape : Qt::CursorShape

Cette propriété définit la forme du curseur qui s'affichera dès que l'attribut « hovered » est défini sur « true » et qu'aucun autre gestionnaire ne la remplace.

Les formes de curseur disponibles sont les suivantes :

• Qt.ArrowCursor
• Qt.UpArrowCursor
• Qt.CrossCursor
• Qt.WaitCursor
• Qt.IBeamCursor
• Qt.CursorDeTailleVerticale
• Qt.CursorTailleHoriz
• Qt.SizeBDiagCursor
• Qt.SizeFDiagCursor
• Qt.SizeAllCursor
• Qt.CurseurVide
• Qt.CursorDiviséVertical
• Qt.Cursor à division horizontale
• Qt.CurseurMainPointante
• Qt.CursorInterdit
• Qt.Cursor« Qu'est-ce que c'est ? »
• Qt.CursorOccupé
• Qt.CursorMainOuverte
• Qt.CurseurMainFermée
• Qt.CurseurDeCopieParGlissement
• Qt.CurseurGlisserDéplacer
• 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 réinitialisée à son état initial en lui attribuant la valeur « undefined ».

Si un gestionnaire dont la propriété « cursorShape » est définie est de type « active », ce curseur s'affichera. Sinon, si la propriété « HoverHandler » du gestionnaire est définie et que la valeur est « cursorShape », ce curseur s'affichera. Dans le cas contraire, le curseur « cursor » de l'élément parent s'affichera.

Voir également Qt::CursorShape et QQuickItem::cursor().

enabled : bool

Si une HoverHandler est désactivée, elle rejettera tous les événements et aucun signal ne sera émis.

Si l’ parent d’un HoverHandler est définie sur ` disabled`, l’ HoverHandler continue par défaut à réagir aux événements de survol. En effet, les effets de retour d’information au survol et les infobulles peuvent s’avérer utiles même lorsqu’un contrôle est désactivé. Si vous souhaitez désactiver l’ HoverHandler lorsque son parent est désactivé, vous pouvez ajouter une liaison :

Item {
    HoverHandler {
        enabled: parent.enabled
    }
}

grabPermissions : flags

Cette propriété définit les autorisations lorsque la logique de ce gestionnaire décide de prendre le contrôle exclusif, ou lorsqu'il est invité à approuver la prise de contrôle ou l'annulation de celle-ci par un autre gestionnaire.

La valeur par défaut est « PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything », ce qui autorise la plupart des scénarios de prise de contrôle tout en évitant, par exemple, que deux PinchHandlers ne se disputent les mêmes points de contact.

hovered : bool [read-only]

Cette règle s'applique dès lors que le curseur d'un périphérique de pointage (souris ou tablette) se trouve à l'intérieur des limites de l'élément « parent », étendues par l'élément « margin » le cas échéant.

margin : real

La marge située au-delà des limites de l'élément « parent », à l'intérieur de laquelle un « eventPoint » peut activer ce gestionnaire. Par exemple, sur une « PinchHandler » où le « target » est également le « parent », il est utile de définir cette valeur à une distance correspondant au moins à la moitié de la largeur du doigt d'un utilisateur moyen, afin que, si la « parent » a été réduite à une très petite taille, le geste de pincement reste possible. De même, si un bouton basé sur l’ TapHandler est placé près du bord de l’écran, cela permet de respecter la loi de Fitts : réagir aux clics de souris au bord de l’écran même si le bouton est visuellement espacé de quelques pixels par rapport à ce bord.

La valeur par défaut est 0.

parent : Item

L'objet « Item », qui correspond au champ d'application du gestionnaire ; l'« Item » dans lequel il a été déclaré. Le gestionnaire traitera les événements pour le compte de cet « Item », 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'« Item ». Au départ, « target() » est identique, mais il peut être réattribué.

Voir également target et QObject::parent().

point : handlerPoint [read-only]

L'eventPoint e actuellement sélectionné. Lorsqu'aucun point n'est sélectionné, cet objet est réinitialisé à ses valeurs par défaut (toutes les coordonnées sont égales à 0).

target : Item

L'élément que ce gestionnaire va manipuler.

Par défaut, il s’agit de l’ parent, c’est-à-dire l’élément dans lequel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir la cible sur un autre élément, afin de gérer les événements au sein d’un élément tout en manipulant un autre ; ou d’ null, pour désactiver le comportement par défaut et effectuer une autre action à la place.

Documentation sur les signaux

canceled(eventPoint point)

Si ce gestionnaire a déjà saisi l'point donné, ce signal est émis lorsqu'un autre gestionnaire de pointeur ou un autre élément lui vole la saisie.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le « grab » a subi une modification pertinente pour ce gestionnaire.

Le verbe « transition » indique ce qui s'est passé. L'objet « point » correspond au point qui a été sélectionné ou désélectionné.

Les valeurs valides pour « transition » sont :