WheelHandler QML Type

Gestionnaire de la roulette de la souris. Plus d'informations...

Import Statement: import QtQuick
Inherits:

SinglePointHandler

Propriétés

Signaux

  • wheel(WheelEvent event)

Description détaillée

WheelHandler est un gestionnaire utilisé pour manipuler de manière interactive une propriété numérique d'un élément lorsque l'utilisateur tourne la molette de la souris. Comme les autres gestionnaires d'entrée, il manipule par défaut son target. Déclarez property pour contrôler quelle propriété cible sera manipulée :

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 Il est très utile, en combinaison avec WheelHandler (ainsi qu'avec d'autres Input Handlers), de déclarer la plage de valeurs autorisée pour la propriété cible. Par exemple, il est possible de mettre en œuvre le défilement en utilisant une combinaison de WheelHandler et de DragHandler pour manipuler la propriété y de l'élément défilant lorsque l'utilisateur fait tourner la roue ou fait glisser l'élément sur un écran tactile, et BoundaryRule pour limiter l'amplitude du mouvement 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 la cible est nulle, WheelHandler ne manipulera rien automatiquement ; 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 l'événement de la roue directement.

Par défaut, WheelHandler ne gère qu'une roue de souris rotative, ce qui peut être modifié en définissant acceptedDevices.

Voir également MouseArea, Flickable, et Qt Quick Exemples - Pointer Handlers.

Documentation sur les propriétés

acceptedDevices : flags

Types de dispositifs de pointage pouvant activer ce gestionnaire.

Par défaut, cette propriété est définie sur PointerDevice.Mouse, de manière à ne réagir qu'aux événements provenant d'une roue de souris réelle.

WheelHandler Il est possible de faire en sorte que ce gestionnaire réagisse à la fois au défilement de la molette de la souris et au défilement du pavé tactile en définissant la valeur de acceptedDevices (périphériques acceptés) sur PointerDevice.Mouse | PointerDevice.TouchPad.

Remarque : certains matériels qui ne sont pas des souris (comme une tablette tactile Wacom ou un pavé tactile d'ordinateur portable Linux) génèrent de véritables événements de molette à partir de gestes. WheelHandler réagira à ces événements en tant qu'événements de molette même si acceptedDevices reste réglé sur sa valeur par défaut.


acceptedModifiers : flags

Si cette propriété est définie, il faudra appuyer sur les modificateurs de clavier donnés pour réagir aux événements de roue, et les ignorer dans le cas contraire.

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

Par exemple, un site Item peut avoir deux gestionnaires, dont l'un n'est activé que si le modificateur de clavier requis est enfoncé, tandis que l'autre ignore les événements si n'importe quel modificateur est enfoncé :

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 :

ConstanteDescription
NoModifierAucune touche de modification n'est autorisée.
ShiftModifierLa touche Shift du clavier doit être enfoncée.
ControlModifierUne touche Ctrl du clavier doit être enfoncée.
AltModifierUne touche Alt du clavier doit être enfoncée.
MetaModifierUne touche Meta du clavier doit être enfoncée.
KeypadModifierUne touche du clavier doit être enfoncée.
GroupSwitchModifierX11 uniquement (sauf s'il est activé sous Windows par un argument de ligne de commande). Une touche Mode_switch du clavier doit être enfoncée.
KeyboardModifierMaskLe gestionnaire ne se préoccupe pas des modificateurs enfoncés.

Voir également Qt::KeyboardModifier.


active : bool [read-only]

Cette fonction retient true chaque fois que WheelHandler a récemment vu QWheelEvent, qu'il maintient ses propriétés à jour et qu'il manipule activement sa cible (le cas échéant).

Voir aussi activeTimeout.


activeTimeout : real

Délai en secondes après lequel la propriété active redevient false si aucun autre événement de roue n'est reçu. La valeur par défaut est 0.1 (100 ms).

Lorsque WheelHandler gère des événements contenant des informations scroll phase, comme les événements provenant de certains pavés tactiles, la propriété active devient false dès qu'un événement de phase Qt::ScrollEnd est reçu ; dans ce cas, le délai d'attente n'est pas nécessaire. Mais une souris classique à molette ne prévoit pas de phase de défilement : la souris ne peut pas détecter le moment où l'utilisateur a décidé d'arrêter le défilement, de sorte que la propriété active passe à false après ce laps de temps.

Voir également QWheelEvent::phase().


blocking : bool [since 6.3]

Si ce gestionnaire empêche d'autres éléments ou gestionnaires situés derrière lui de gérer le même événement de roue. Cette propriété est true par défaut.

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.


invertible : bool

Inverser ou non le sens du changement de propriété si QWheelEvent::inverted est 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 que le défilement se fait 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 la cible, la direction du mouvement correspondra au paramètre du système. Si cette propriété est définie sur false, elle inversera rotation de sorte que la direction du mouvement soit toujours la même que la direction du mouvement du doigt.


margin : real

La marge au-delà des limites de l'élément parent dans laquelle 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 il réagira toujours à 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 est la roue à laquelle réagir. La valeur par défaut est Qt.Vertical.

Toutes les souris ne disposent pas d'une molette Horizontal; celle-ci est parfois émulée en inclinant la molette sur le côté. Un pavé tactile peut généralement générer des événements de roue verticale et horizontale.


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 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).


property : string

La propriété à modifier sur la cible lorsque la molette de la souris est tournée.

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

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, la cible se déplacera horizontalement lorsque la molette sera tournée. Les propriétés suivantes ont un comportement particulier :

ConstanteDescription
scalescale sera modifiée de manière non linéaire, comme décrit sous targetScaleMultiplier. Si targetTransformAroundCursor est true, les propriétés x et y seront ajustées simultanément afin que l'utilisateur puisse effectuer un zoom avant ou arrière sur le point situé sous le curseur de la souris.
rotationrotation rotation Si targetTransformAroundCursor est true, les propriétés l{QQuickItem::x}{x} et y seront ajustées simultanément afin que l'utilisateur puisse faire pivoter l'élément autour du point situé sous le curseur de la souris.

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


rotation : real

L'angle de rotation de la roue de la souris depuis la dernière fois que cette propriété a été définie, en degrés de roue.

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

Une molette de clic de souris de base fonctionne par pas de 15 degrés.

La valeur par défaut est 0 au démarrage. Elle peut être programmée à n'importe quelle valeur à n'importe quel moment. La valeur sera ajustée à partir de là au fur et à mesure que l'utilisateur tournera la molette de la souris.

Voir également orientation.


rotationScale : real

L'échelle à appliquer à la propriété rotation et à la propriété property de l'élément cible, le cas échéant. La valeur par défaut est 1, de sorte que rotation est exprimé en degrés de rotation. Il peut être défini comme un nombre négatif pour inverser l'effet du sens de rotation de la molette de la souris.


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 de null, pour désactiver le comportement par défaut et faire quelque chose d'autre à la place.


targetScaleMultiplier : real

La quantité par laquelle la cible scale doit être multipliée chaque fois que rotation change de 15 degrés. Ceci n'est pertinent que lorsque property est "scale".

L'adresse 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 roue de la souris est tournée d'un "clic" (15 degrés), la cible sera mise à l'échelle d'environ 1,25 ; après trois "clics", sa taille sera doublée ou divisée par deux, selon la direction dans laquelle la roue est tournée. Si vous souhaitez que la cible soit doublée ou divisée par deux tous les deux clics de la roue, réglez cette valeur sur 2 1/2 (1,4142). Si vous souhaitez que l'échelle soit inversée lorsque la roue est tournée, réglez rotationScale sur une valeur négative.


targetTransformAroundCursor : bool

Indique si la cible doit être automatiquement repositionnée de manière à être transformée autour de la position du curseur de la souris pendant l'ajustement de property. La valeur par défaut est true.

Si property vaut "rotation" et que targetTransformAroundCursor vaut true, l'élément cible tournera autour de la position du curseur de la souris lors de la rotation de la roue. Si targetTransformAroundCursor est false, l'élément tournera autour de transformOrigin.


Documentation du signal

wheel(WheelEvent event)

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

Remarque : le gestionnaire correspondant est onWheel.


© 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.