WheelHandler QML Type

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

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

Par ailleurs, si property n'est pas défini ou si target est nul, 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 directement l'événement de la roue.

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 fixée à 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 à celui du pavé tactile en attribuant la valeur PointerDevice.Mouse | PointerDevice.TouchPad à acceptedDevices (Périphériques acceptés).

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 la valeur de cette propriété est 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 :

Voir aussi Qt::KeyboardModifier.

active : bool [read-only]

Cela vaut pour true chaque fois que WheelHandler a récemment vu un QWheelEvent, qu'il tient ses propriétés à jour et qu'il manipule activement son target (s'il y en a un).

Voir également activeTimeout.

activeTimeout : real

Délai en secondes après lequel la propriété active passera à 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 qui contiennent des informations scroll phase, comme les événements provenant de certaines tablettes tactiles, la propriété active devient false dès qu'un événement avec la 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 aussi 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.

Si la propriété parent d'un PointerHandler est disabled, le gestionnaire sera également désactivé, même si la propriété enabled reste true.

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 target, 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 à l'intérieur de 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 roue :

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

La roue à laquelle il faut réagir. La valeur par défaut est Qt.Vertical.

Toutes les souris ne disposent pas d'une molette Horizontal; elle 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 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).

property : string

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

La valeur par défaut est "no property" (chaîne vide). Lorsqu'aucune propriété cible n'est modifiée automatiquement, vous pouvez utiliser des liens 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, target se déplacera horizontalement lors de la rotation de la molette. 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

L'angle de rotation de la molette 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 aussi orientation.

rotationScale : real

L'échelle à appliquer à la propriété rotation et à l'élément property sur target, le cas échéant. La valeur par défaut est 1, de sorte que rotation sera 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

Le montant par lequel target scale doit être multiplié 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), target sera mis à l'échelle d'environ 1,25 ; après trois "clics", sa taille sera doublée ou divisée par deux, en fonction de la direction dans laquelle la roue est tournée. Si vous souhaitez que la taille soit doublée ou divisée par deux tous les deux clics de la molette, 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 le site target doit être automatiquement repositionné de manière à être transformé autour de la position du curseur de la souris pendant que le site property est ajusté. La valeur par défaut est true.

Si property est défini sur "rotation" et que targetTransformAroundCursor est true, l'élément target tournera autour de la position du curseur de la souris lors de la rotation de la roue. Si targetTransformAroundCursor est false, il tournera autour de son transformOrigin.

Documentation sur les signaux

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.