WheelHandler QML Type

Gestionnaire de la molette de la souris. En savoir plus...

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

Propriétés

• acceptedDevices : flags
• acceptedModifiers : flags
• active : bool
• activeTimeout : real
• blocking : bool (since 6.3)
• enabled : bool
• invertible : bool
• margin : real
• orientation : enumeration
• parent : Item
• point : handlerPoint
• property : string
• rotation : real
• rotationScale : real
• target : Item
• targetScaleMultiplier : real
• targetTransformAroundCursor : bool

Signaux

• wheel(WheelEvent event)

Description détaillée

WheelHandler est un gestionnaire utilisé pour modifier de manière interactive une propriété numérique d’un élément lorsque l’utilisateur fait tourner la molette de la souris. À l’instar des autres gestionnaires d’entrée, il modifie par défaut sa propriété « target ». Déclarez « property » pour contrôler la propriété cible à modifier :

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        onWheel: (event)=> console.log("rotation", event.angleDelta.y,
                                       "scaled", rotation, "@", point.position,
                                       "=>", parent.rotation)
    }
}

BoundaryRule est très utile en combinaison avec WheelHandler (ainsi qu’avec d’autres gestionnaires d’entrée) pour définir la plage de valeurs autorisées que la propriété cible peut prendre. Par exemple, il est possible d’implémenter un défilement en combinant WheelHandler et DragHandler pour modifier la propriété y de l’élément défilable lorsque l’utilisateur fait tourner la molette ou fait glisser l’élément sur un écran tactile, et BoundaryRule pour limiter la plage de déplacement du haut vers le bas :

import QtQuick
import Qt.labs.animation

Item {
    width: 320; height: 480
    Flow {
        id: content
        width: parent.width
        spacing: 2; padding: 2

        WheelHandler {
            orientation: Qt.Vertical
            property: "y"
            rotationScale: 15
            acceptedDevices: PointerDevice.Mouse | PointerDevice.TouchPad
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        DragHandler {
            xAxis.enabled: false
            onActiveChanged: if (!active) ybr.returnToBounds()
        }

        BoundaryRule on y {
            id: ybr
            minimum: content.parent.height - content.height
            maximum: 0
            minimumOvershoot: 400; maximumOvershoot: 400
            overshootFilter: BoundaryRule.Peak
        }

        Repeater {
            model: 1000
            Rectangle { color: "gray"; width: 10 + Math.random() * 100; height: 15 }
        }
    }
}

Sinon, si ` property ` n’est pas défini ou si ` target ` est nul, `WheelHandler` ne manipulera automatiquement aucun élément ; mais la propriété ` rotation ` peut être utilisée dans une liaison pour manipuler une autre propriété, ou vous pouvez implémenter ` onWheel ` et gérer directement l’événement de molette.

Par défaut, WheelHandler ne gère que la molette de souris rotative ; cela peut être modifié en définissant acceptedDevices.

Voir également MouseArea, Flickable et Exemples deQt Quick - Gestionnaires de pointeur.

Documentation sur les propriétés

acceptedDevices : flags

Les types de périphériques de pointage pouvant activer ce gestionnaire.

Par défaut, cette propriété est définie sur « PointerDevice.Mouse », afin de ne réagir qu'aux événements provenant d'une véritable molette de souris.

WheelHandler Il est possible de la configurer pour qu’elle réponde à la fois au défilement de la molette de souris et à celui du pavé tactile en définissant acceptedDevices sur PointerDevice.Mouse | PointerDevice.TouchPad.

acceptedModifiers : flags

Si cette propriété est définie, les touches de modification spécifiées devront être enfoncées pour que le système réagisse aux événements de la molette ; dans le cas contraire, il les ignorera.

Si cette propriété est définie sur « Qt.KeyboardModifierMask » (valeur par défaut), l’ WheelHandler ignore les touches de modification.

Par exemple, un « Item » peut comporter deux gestionnaires : l’un n’est activé que si la touche de modification requise est enfoncée, tandis que l’autre ignore les événements si une touche de modification quelconque est enfoncée :

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        acceptedModifiers: Qt.ControlModifier
    }

    WheelHandler {
        property: "scale"
        acceptedModifiers: Qt.NoModifier
    }
}

Les modificateurs disponibles sont les suivants :

Voir aussi Qt::KeyboardModifier.

active : bool [read-only]

Cela s'applique à true dès lors que le site WheelHandler a récemment reçu une mise à jour QWheelEvent, qu'il maintient ses propriétés à jour et qu'il manipule activement ses target (le cas échéant).

Voir également activeTimeout.

activeTimeout : real

Durée en secondes au terme de laquelle la propriété « active » reprendra la valeur « false » si aucun autre événement de molette n’est reçu. La valeur par défaut est « 0.1 » (100 ms).

Lorsque WheelHandler gère des événements contenant des informations de type « scroll phase », comme ceux provenant de certains pavés tactiles, la propriété active prend la valeur « false » dès la réception d’un événement comportant la phase « Qt::ScrollEnd » ; dans ce cas, le délai d’expiration n’est pas nécessaire. En revanche, une souris classique dotée d’une molette ne fournit pas de phase de défilement : la souris ne peut pas détecter à quel moment l’utilisateur a décidé d’arrêter le défilement ; la propriété ` active ` passe donc à ` false ` une fois ce délai écoulé.

Voir également QWheelEvent::phase().

blocking : bool [since 6.3]

Indique si ce gestionnaire empêche d'autres éléments ou gestionnaires situés en aval de traiter le même événement de molette. Cette propriété est définie par défaut sur « true ».

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

enabled : bool

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

Si la propriété « parent » d'une PointerHandler est définie sur « disabled », le gestionnaire sera également désactivé de fait, même si la propriété « enabled » reste définie sur « true ».

invertible : bool

Indique s'il faut ou non inverser le sens de la modification de la propriété lorsque QWheelEvent::inverted prend la valeur true. La valeur par défaut est true.

Si le système d’exploitation dispose d’un paramètre de « défilement naturel » qui fait en sorte que le défilement s’effectue dans la même direction que le mouvement du doigt, alors si cette propriété est définie sur true et que WheelHandler définit directement une propriété sur target, le sens du mouvement correspondra au paramètre système. Si cette propriété est définie sur false, elle inversera l’ rotation, de sorte que la direction du déplacement soit toujours identique à celle du mouvement du doigt.

margin : real

La marge au-delà des limites de l'élément parent, à l'intérieur de laquelle l'WheelHandler peut réagir. Par exemple, si margin est défini sur 10, vous pouvez placer le curseur jusqu'à 10 pixels en dehors du bord visible de l'élément, et celui-ci réagira tout de même au défilement de la molette :

import QtQuick

Rectangle {
    width: 170; height: 120
    color: "green"; antialiasing: true

    WheelHandler {
        property: "rotation"
        margin: 10
    }
}

La valeur par défaut est 0.

orientation : enumeration

À quelle molette réagir. La valeur par défaut est « Qt.Vertical ».

Toutes les souris ne disposent pas d'une molette « Horizontal » ; celle-ci est parfois simulée en inclinant la molette sur le côté. Un pavé tactile peut généralement générer des événements de molette à la fois verticaux et horizontaux.

parent : Item

L'objet « Item », qui correspond au périmètre 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ée. Lorsqu'aucun point n'est sélectionné, cet objet est réinitialisé à ses valeurs par défaut (toutes les coordonnées sont égales à 0).

property : string

Propriété à modifier sur l'target lorsque la molette de la souris est actionnée.

Par défaut, aucune propriété n'est spécifiée (chaîne vide). Lorsqu'aucune propriété cible n'est automatiquement modifiée, vous pouvez utiliser des liaisons pour réagir à la rotation de la molette de la souris de manière arbitraire.

Vous pouvez utiliser la molette de la souris pour ajuster n'importe quelle propriété numérique. Par exemple, si property est défini sur x, l'target se déplacera horizontalement à mesure que la molette est tournée. Les propriétés suivantes ont un comportement particulier :

L'ajustement de la propriété cible donnée est toujours mis à l'échelle par rotationScale.

rotation : real

Angle de rotation de la molette de la souris depuis la dernière définition de cette propriété, exprimé en degrés de molette.

Une valeur positive indique que la molette a été tournée vers le haut/la droite ; une valeur négative indique qu'elle a été tournée vers le bas/la gauche.

Une molette de souris standard fonctionne par paliers de 15 degrés.

La valeur par défaut est « 0 » au démarrage. Elle peut être définie par programmation sur n'importe quelle valeur à tout moment. La valeur sera ajustée à partir de là à mesure que l'utilisateur fait tourner la molette de la souris.

Voir également orientation.

rotationScale : real

Échelle à appliquer à la propriété « rotation », ainsi qu’à la propriété « property » de l’élément « target », le cas échéant. La valeur par défaut est 1, ce qui signifie que « rotation » sera exprimé en degrés de rotation. Il est possible de définir une valeur négative pour inverser l’effet du sens de rotation de la molette de la souris.

target : Item

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

Par défaut, il s'agit de l'élément « parent », c'est-à-dire l'élément au sein duquel le gestionnaire est déclaré. Cependant, il peut parfois être utile de définir une autre cible, 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.

targetScaleMultiplier : real

Valeur par laquelle l'target scale doit être multipliée chaque fois que l'rotation varie de 15 degrés. Ceci ne s'applique que lorsque property est égal à "scale".

La valeur de scale sera multipliée par targetScaleMultiplier ^{angleDelta * rotationScale / 15}. La valeur par défaut est 2 ^1/3, ce qui signifie que si rotationScale est laissé à sa valeur par défaut et que la molette de la souris est tournée d’un « clic » (15 degrés), la valeur de target sera multipliée par environ 1,25 ; après trois « clics », sa taille sera doublée ou divisée par deux, selon le sens de rotation de la molette. Si vous souhaitez que la taille double ou soit divisée par deux tous les deux clics de la molette, définissez cette valeur sur 2 ^1/2 (1,4142). Si vous souhaitez que la taille soit modifiée dans le sens inverse de la rotation de la molette, définissez « rotationScale » sur une valeur négative.

targetTransformAroundCursor : bool

Détermine si l'target doit être automatiquement repositionné de manière à être transformé autour de la position du curseur de la souris pendant le réglage de l'property. La valeur par défaut est « true ».

Si « property » est défini sur « "rotation" » et que « targetTransformAroundCursor » est défini sur « true », alors lorsque la molette est tournée, l’élément « target » pivotera sur place autour de la position du curseur de la souris. Si « targetTransformAroundCursor » est défini sur « false », il pivotera plutôt autour de son « transformOrigin ».

Documentation sur les signaux

wheel(WheelEvent event)

Ce signal est émis chaque fois que ce gestionnaire reçoit une event de type QWheelEvent: c'est-à-dire chaque fois que la molette est déplacée ou que le geste de défilement est mis à jour.