HoverHandler QML Type

Gestionnaire pour le survol de la souris et de la tablette. Plus d'informations...

• 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 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 :

Voir aussi QInputDevice::DeviceType.

acceptedModifiers : flags

Si cette propriété est définie, un événement de survol n'est traité que si l'on appuie sur les modificateurs de clavier indiqués. L'événement est ignoré en l'absence de modificateurs.

Cette propriété est définie par défaut sur Qt.KeyboardModifierMask, ce qui permet de traiter les événements de survol indépendamment 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 :

Voir aussi Qt::KeyboardModifier.

acceptedPointerTypes : flags

Types d'instruments de pointage (générique, stylet, gomme, etc.) pouvant activer 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 d'appareils, 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 :

Voir également QPointingDevice::PointerType.

active : bool [read-only]

Il s'agit de true chaque fois que ce gestionnaire d'entrée a pris l'entière responsabilité de la transmission d'un ou de plusieurs eventPoints, en s'emparant avec succès de ces points de manière exclusive. Cela signifie qu'il tient ses propriétés à jour en fonction des mouvements de ces eventPoints et qu'il manipule activement son site target (le cas échéant).

blocking : bool [since 6.3]

Indique 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 à la condition 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.

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

enabled : bool

Si un site HoverHandler est désactivé, il rejettera tous les événements et aucun signal ne sera émis.

Si l'adresse parent d'un HoverHandler est disabled, le HoverHandler continue de réagir aux événements de survol par défaut. En effet, les effets de rétroaction au survol et les infobulles peuvent être utiles même lorsqu'un contrôle est désactivé. Si vous souhaitez désactiver le site HoverHandler lorsque son parent est désactivé, vous pouvez ajouter une liaison :

Item {
    HoverHandler {
        enabled: parent.enabled
    }
}

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.

La valeur par défaut est PointerHandler.CanTakeOverFromItems | PointerHandler.CanTakeOverFromHandlersOfDifferentType | PointerHandler.ApprovesTakeOverByAnything, ce qui permet la plupart des scénarios de prise en charge mais évite, par exemple, que deux PinchHandler ne se disputent les mêmes points de contact.

hovered : bool [read-only]

Demeure vrai lorsque 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 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 [read-only]

Le site 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 manipulera.

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.

grabChanged(PointerDevice::GrabTransition transition, eventPoint point)

Ce signal est émis lorsque le grab 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