WheelHandler QML Type

Manejador para la rueda del ratón. Más...

• Lista de todos los miembros, incluidos los heredados

Propiedades

• 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

Señales

• wheel(WheelEvent event)

Descripción detallada

WheelHandler es un manejador que se utiliza para manipular interactivamente alguna propiedad numérica de un Item cuando el usuario gira la rueda del ratón. Como otros Manejadores de Entrada, por defecto manipula su target. Declare property para controlar qué propiedad objetivo será manipulada:

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 es bastante útil en combinación con WheelHandler (así como con otros Input Handlers) para declarar el rango permitido de valores que puede tener la propiedad objetivo. Por ejemplo, es posible implementar el desplazamiento utilizando una combinación de WheelHandler y DragHandler para manipular la propiedad y del elemento desplazable cuando el usuario gira la rueda o arrastra el elemento en una pantalla táctil, y BoundaryRule para limitar el rango de movimiento de arriba a abajo:

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

Alternativamente, si property no está establecido o target es nulo, WheelHandler no manipulará nada automáticamente; pero la propiedad rotation puede ser utilizada en un binding para manipular otra propiedad, o puedes implementar onWheel y manejar el evento de la rueda directamente.

WheelHandler sólo maneja una rueda de ratón giratoria por defecto; esto puede cambiarse configurando acceptedDevices.

Vea también MouseArea, Flickable, y Qt Quick Ejemplos - Manejadores de Puntero.

Documentación de Propiedades

acceptedDevices : flags

Los tipos de dispositivos señaladores que pueden activar este manejador.

Por defecto, esta propiedad está establecida a PointerDevice.Mouse, para reaccionar sólo a eventos de una rueda de ratón real.

WheelHandler se puede hacer que responda tanto a la rueda del ratón como al desplazamiento del touchpad estableciendo acceptedDevices a PointerDevice.Mouse | PointerDevice.TouchPad.

acceptedModifiers : flags

Si esta propiedad está establecida, requerirá que los modificadores de teclado dados sean presionados para reaccionar a los eventos de rueda, y en caso contrario los ignorará.

Si esta propiedad está establecida a Qt.KeyboardModifierMask (el valor por defecto), el WheelHandler ignora las teclas modificadoras.

Por ejemplo, un Item podría tener dos manejadores, uno de los cuales se activa sólo si se pulsa el modificador de teclado requerido, mientras que el otro ignora los eventos si se pulsa cualquier modificador:

import QtQuick

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

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

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

Los modificadores disponibles son los siguientes

Véase también Qt::KeyboardModifier.

active : bool [read-only]

Se mantiene true siempre que WheelHandler haya visto recientemente un QWheelEvent, mantenga sus propiedades actualizadas y manipule activamente su target (si existe).

Véase también activeTimeout.

activeTimeout : real

La cantidad de tiempo en segundos tras la cual la propiedad active volverá a false si no se reciben más eventos de rueda. El valor por defecto es 0.1 (100 ms).

Cuando WheelHandler maneja eventos que contienen información scroll phase, como los eventos de algunos touchpads, la propiedad active se convertirá en false tan pronto como se reciba un evento con fase Qt::ScrollEnd; en ese caso el tiempo de espera no es necesario. Pero un ratón convencional con rueda no proporciona una fase de desplazamiento: el ratón no puede detectar cuándo el usuario ha decidido dejar de desplazarse, por lo que la propiedad active pasa a false una vez transcurrido ese tiempo.

Véase también QWheelEvent::phase().

blocking : bool [since 6.3]

Si este manejador impide que otros elementos o manejadores detrás de él manejen el mismo evento de rueda. Esta propiedad es true por defecto.

Esta propiedad se introdujo en Qt 6.3.

enabled : bool

Si un PointerHandler está desactivado, rechazará todos los eventos y no se emitirá ninguna señal.

Si un PointerHandler's parent es disabled, el manejador también será efectivamente desactivado, incluso cuando la propiedad enabled permanezca true.

invertible : bool

Si se invierte o no la dirección del cambio de propiedad si QWheelEvent::inverted es true. El valor predeterminado es true.

Si el sistema operativo tiene una configuración de "desplazamiento natural" que hace que el desplazamiento se realice en la misma dirección que el movimiento del dedo, entonces si esta propiedad está establecida a true, y WheelHandler está estableciendo directamente una propiedad en target, la dirección de movimiento corresponderá a la configuración del sistema. Si esta propiedad se establece en false, se invertirá rotation para que la dirección del movimiento sea siempre la misma que la dirección del movimiento del dedo.

margin : real

El margen más allá de los límites del elemento parent dentro del cual el WheelHandler puede reaccionar. Por ejemplo, si margin se establece en 10, puede colocar el cursor hasta 10 píxeles fuera del borde visible del elemento, y aún así reaccionará a la rueda:

import QtQuick

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

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

El valor por defecto es 0.

orientation : enumeration

A qué rueda reaccionar. Por defecto es Qt.Vertical.

No todos los ratones tienen una rueda Horizontal; a veces se emula inclinando la rueda lateralmente. Un touchpad normalmente puede generar eventos de rueda vertical y horizontal.

parent : Item

El Item que es el ámbito del manejador; el Item en el que fue declarado. El manejador manejará eventos en nombre de este Item, lo que significa que un evento de puntero es relevante si al menos uno de sus eventPoints ocurre dentro del interior del Item. Inicialmente target() es el mismo, pero puede ser reasignado.

Véase también target y QObject::parent().

point : handlerPoint [read-only]

El eventPoint que se está manejando actualmente. Cuando no se está gestionando ningún punto, este objeto se restablece a los valores por defecto (todas las coordenadas son 0).

property : string

La propiedad que se modificará en target cuando se gire la rueda del ratón.

Por defecto no hay propiedad (cadena vacía). Cuando no se modifica automáticamente ninguna propiedad de destino, puede utilizar los enlaces para reaccionar a la rotación de la rueda del ratón de forma arbitraria.

Puede utilizar la rueda del ratón para ajustar cualquier propiedad numérica. Por ejemplo, si property se establece en x, target se moverá horizontalmente al girar la rueda. Las siguientes propiedades tienen un comportamiento especial:

El ajuste de la propiedad objetivo dada siempre se escala en rotationScale.

rotation : real

El ángulo con el que se ha girado la rueda del ratón desde la última vez que se estableció esta propiedad, en grados de rueda.

Un valor positivo indica que la rueda fue rotada hacia arriba/derecha; un valor negativo indica que la rueda fue rotada hacia abajo/izquierda.

Una rueda de clic de ratón básica funciona en pasos de 15 grados.

El valor por defecto es 0 al inicio. Puede ser programado a cualquier valor en cualquier momento. El valor se ajustará a partir de ahí a medida que el usuario gire la rueda del ratón.

Véase también orientation.

rotationScale : real

La escala que se aplicará a la propiedad rotation, y a property en el elemento target, si existe. El valor por defecto es 1, de forma que rotation estará en unidades de grados de rotación. Puede establecerse a un número negativo para invertir el efecto de la dirección de rotación de la rueda del ratón.

target : Item

Elemento que manipulará este controlador.

Por defecto, es el mismo que parent, el Item dentro del cual se declara el manejador. Sin embargo, a veces puede ser útil establecer el objetivo a un elemento diferente, con el fin de manejar eventos dentro de un elemento pero manipular otro; o a null, para desactivar el comportamiento por defecto y hacer otra cosa en su lugar.

targetScaleMultiplier : real

La cantidad por la que se multiplicará target scale cada vez que rotation cambie 15 grados. Esto es relevante sólo cuando property es "scale".

El scale se multiplicará por targetScaleMultiplier ^{angleDelta * rotationScale / 15}. El valor por defecto es 2 ^1/3, lo que significa que si rotationScale se deja en su valor por defecto, y la rueda del ratón se gira un "clic" (15 grados), el target se escalará aproximadamente 1.25; después de tres "clics" su tamaño se duplicará o se reducirá a la mitad, dependiendo de la dirección en que se gire la rueda. Si desea que se duplique o reduzca a la mitad cada 2 clics de la rueda, ajústelo a 2 ^1/2 (1,4142). Si quieres que se escale en sentido contrario a como se gira la rueda, establece rotationScale a un valor negativo.

targetTransformAroundCursor : bool

Si el target debe reposicionarse automáticamente de forma que se transforme alrededor de la posición del cursor del ratón mientras se ajusta el property. El valor predeterminado es true.

Si property se ajusta a "rotation" y targetTransformAroundCursor es true, entonces al girar la rueda, el elemento target girará en su lugar alrededor de la posición del cursor del ratón. Si targetTransformAroundCursor es false, rotará alrededor de su transformOrigin en su lugar.

Documentación de señales

wheel(WheelEvent event)

Esta señal se emite cada vez que este manejador recibe un event de tipo QWheelEvent: es decir, cada vez que se mueve la rueda o se actualiza el gesto de desplazamiento.