WheelHandler QML Type
Controlador de la rueda del ratón. Más...
| Import Statement: | import QtQuick |
| Inherits: |
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 controlador que se utiliza para manipular de forma interactiva alguna propiedad numérica de un elemento (Item) a medida que el usuario gira la rueda del ratón. Al igual que otros controladores de entrada (Input Handlers), por defecto manipula su propiedad de destino ( target). Declara property para controlar qué propiedad de destino se manipulará:
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 resulta muy útil en combinación con WheelHandler (así como con otros controladores de entrada) para declarar el rango de valores permitido que puede tener la propiedad de destino. 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 desde la parte superior hasta la inferior:
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 }
}
}
}Por otra parte, si no se ha establecido ` property ` o si ` target ` es nulo, `WheelHandler` no manipulará nada automáticamente; sin embargo, la propiedad ` rotation ` puede utilizarse en un enlace para manipular otra propiedad, o bien se puede implementar ` onWheel ` y gestionar el evento de la rueda directamente.
WheelHandler solo gestiona la rueda giratoria del ratón de forma predeterminada; esto se puede cambiar configurando acceptedDevices.
Véase también MouseArea, Flickable y Qt Quick Ejemplos: controladores de puntero.
Documentación de propiedades
acceptedDevices : flags
Los tipos de dispositivos de puntero que pueden activar este controlador.
Por defecto, esta propiedad está establecida en « PointerDevice.Mouse », de modo que solo reacciona a los eventos procedentes de la rueda de un ratón físico.
WheelHandler Se puede hacer que responda tanto al desplazamiento de la rueda del ratón como al del panel táctil configurando `acceptedDevices` en ` PointerDevice.Mouse | PointerDevice.TouchPad`.
Nota: Algunos dispositivos que no son ratones (como una tableta Wacom táctil o el panel táctil de un portátil con Linux) generan eventos de rueda reales a partir de gestos. WheelHandler responderá a esos eventos como eventos de rueda, incluso si acceptedDevices permanece establecido en su valor por defecto.
acceptedModifiers : flags
Si se activa esta propiedad, será necesario pulsar los modificadores de teclado indicados para que el sistema reaccione a los eventos de la rueda; de lo contrario, los ignorará.
Si esta propiedad se establece en « Qt.KeyboardModifierMask » (el valor por defecto), el « WheelHandler » ignora las teclas modificadoras.
Por ejemplo, un « Item » podría tener dos controladores, uno de los cuales solo se activa 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:
| Constante | Descripción |
|---|---|
NoModifier | No se permite ninguna tecla modificadora. |
ShiftModifier | Debe pulsarse la tecla Mayús del teclado. |
ControlModifier | Se debe pulsar la tecla Ctrl del teclado. |
AltModifier | Se debe pulsar la tecla Alt del teclado. |
MetaModifier | Se debe pulsar la tecla Meta del teclado. |
KeypadModifier | Se debe pulsar un botón del teclado numérico. |
GroupSwitchModifier | Solo en X11 (a menos que se active en Windows mediante un argumento de línea de comandos). Se debe pulsar una tecla Mode_switch del teclado. |
KeyboardModifierMask | Al controlador no le importa qué modificadores se pulsen. |
Véase también Qt::KeyboardModifier.
active : bool [read-only]
Esto se cumple true siempre que el WheelHandler haya visto recientemente un QWheelEvent, mantenga sus propiedades actualizadas y manipule activamente su target (si lo hay).
Véase también activeTimeout.
activeTimeout : real
El tiempo, en segundos, tras el cual la propiedad « active » volverá a « false » si no se reciben más eventos de la rueda. El valor por defecto es « 0.1 » (100 ms).
Cuando WheelHandler gestiona eventos que contienen información de scroll phase, como los eventos procedentes de algunos paneles táctiles, la propiedad active pasará a ser false tan pronto como se reciba un evento con la fase Qt::ScrollEnd; en ese caso, el tiempo de espera no es necesario. Sin embargo, un ratón convencional con rueda no ofrece 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]
Indica si este controlador impide que otros elementos o controladores situados a continuación de él gestionen el mismo evento de rueda. Esta propiedad tiene el valor predeterminad true.
Esta propiedad se introdujo en Qt 6.3.
enabled : bool
Si se desactiva un « PointerHandler », rechazará todos los eventos y no se emitirá ninguna señal.
Si la propiedad « parent » de un « PointerHandler » tiene el valor « disabled », el controlador también quedará desactivado de forma efectiva, incluso cuando la propiedad « enabled » siga teniendo el valor « true ».
Nota: HoverHandler se comporta de forma diferente: consulta la documentación de su propiedad enabled para obtener más información.
invertible : bool
Indica si se debe invertir o no la dirección del cambio de la propiedad cuando QWheelEvent::inverted es true. El valor predeterminado es true.
Si el sistema operativo dispone de 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 se establece en true y WheelHandler establece directamente una propiedad en target, la dirección del movimiento se corresponderá con la configuración del sistema. Si esta propiedad se establece en false, se invertirá el rotation de modo que la dirección del movimiento sea siempre la misma que la 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, podrías situar el cursor hasta 10 píxeles fuera del borde visible del elemento y este seguirá reaccionando al movimiento de 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. El valor predeterminado es Qt.Vertical.
No todos los ratones tienen una rued Horizontal; a veces se emula inclinando la rueda hacia un lado. Un panel táctil suele generar eventos de rueda tanto verticales como horizontales.
parent : Item
El ` Item `, que es el ámbito del controlador; el `Item` en el que se declaró. El controlador gestionará los eventos en nombre de este `Item`, lo que significa que un evento de puntero es relevante si al menos uno de sus ` eventPoints ` tiene lugar dentro del interior del `Item`. Inicialmente, ` target() ` es el mismo, pero se puede reasignar.
Véase también target y QObject::parent().
point : handlerPoint [read-only]
El objeto « eventPoint » que se está gestionando actualmente. Cuando no hay ningún punto en proceso, este objeto se restablece a los valores por defecto (todas las coordenadas son 0).
property : string
La propiedad que se modificará en el objeto ` target ` al girar la rueda del ratón.
El valor por defecto es ninguna propiedad (cadena vacía). Cuando no se modifica automáticamente ninguna propiedad de destino, puedes utilizar enlaces para reaccionar a la rotación de la rueda del ratón de formas arbitrarias.
Se puede utilizar la rueda del ratón para ajustar cualquier propiedad numérica. Por ejemplo, si property se establece en x, el target se desplazará horizontalmente al girar la rueda. Las siguientes propiedades tienen un comportamiento especial:
| Constante | Descripción |
|---|---|
scale | scale se modificará de forma no lineal, tal y como se describe en targetScaleMultiplier. Si targetTransformAroundCursor es true, las propiedades x y y se ajustarán simultáneamente para que el usuario pueda ampliar o reducir el punto situado bajo el cursor del ratón. |
rotation | rotation se establecerá en rotation. Si targetTransformAroundCursor es true, las propiedades l{QQuickItem::x}{x} y y se ajustarán simultáneamente de modo que el usuario pueda girar el elemento en torno al punto situado bajo el cursor del ratón. |
El ajuste de la propiedad de destino dada siempre se escala por rotationScale.
rotation : real
El ángulo en el que se ha girado la rueda del ratón desde la última vez que se estableció esta propiedad, expresado en grados de rueda.
Un valor positivo indica que la rueda se ha girado hacia arriba o hacia la derecha; un valor negativo indica que la rueda se ha girado hacia abajo o hacia la izquierda.
Una rueda de clic básica del ratón funciona en pasos de 15 grados.
El valor por defecto al iniciar el sistema es « 0 ». Se puede establecer mediante programación en 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 la propiedad « property » del elemento « target », si existe. El valor por defecto es 1, por lo que « rotation » se expresará en grados de rotación. Se puede establecer en un número negativo para invertir el efecto de la dirección de rotación de la rueda del ratón.
target : Item
El elemento que este controlador va a manipular.
Por defecto, es el mismo que el « parent », es decir, el «Item» en el que se declara el controlador. Sin embargo, a veces puede resultar útil establecer el «target» en un «Item» diferente, con el fin de gestionar eventos dentro de un «Item» pero manipular otro; o bien en « null », para desactivar el comportamiento predeterminado y realizar otra acción en su lugar.
targetScaleMultiplier : real
El valor por el que se debe multiplicar el target scale cada vez que el rotation varíe en 15 grados. Esto solo es relevante cuando property es "scale".
El valor de 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 se gira la rueda del ratón un «clic» (15 grados), el valor de target se escalará aproximadamente a 1,25; tras tres «clics», su tamaño se duplicará o se reducirá a la mitad, dependiendo de la dirección en la que se gire la rueda. Si quieres que se duplique o se reduzca a la mitad cada dos clics de la rueda, configura este valor en 2 1/2 (1,4142). Si quieres que el tamaño se ajuste de forma opuesta a la rotación de la rueda, establece « rotationScale » en un valor negativo.
targetTransformAroundCursor : bool
Si el « target » debe reposicionarse automáticamente de tal forma que se transforme en torno a la posición del cursor del ratón mientras se ajusta el « property ». El valor por defecto es « true ».
Si property se establece en "rotation" y targetTransformAroundCursor es true, al girar la rueda, el elemento target girará in situ alrededor de la posición del cursor del ratón. Si targetTransformAroundCursor es false, girará en su lugar alrededor de su transformOrigin.
Documentación de Signal
wheel(WheelEvent event)
Esta señal se emite cada vez que este controlador recibe un « event » de tipo « QWheelEvent »: es decir, cada vez que se mueve la rueda o se actualiza el gesto de desplazamiento.
Nota: El controlador correspondiente es onWheel.
© 2026 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.