QWheelEvent Class
La clase QWheelEvent contiene parámetros que describen un evento de rueda. Más información...
| Cabecera: | #include <QWheelEvent> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredado de: | QSinglePointEvent |
- Lista de todos los miembros, incluidos los heredados
- Miembros obsoletos
- QWheelEvent forma parte de las clases de eventos.
Propiedades
|
|
Funciones públicas
| QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, bool inverted, Qt::MouseEventSource source = Qt::MouseEventNotSynthesized, const QPointingDevice *device = QPointingDevice::primaryPointingDevice()) | |
| QPoint | angleDelta() const |
| bool | inverted() const |
| Qt::ScrollPhase | phase() const |
| QPoint | pixelDelta() const |
Funciones públicas reimplementadas
| virtual bool | isBeginEvent() const override |
| virtual bool | isEndEvent() const override |
| virtual bool | isUpdateEvent() const override |
Funciones protegidas
| QWheelEvent(QWheelEvent &&) | |
| QWheelEvent & | operator=(QWheelEvent &&) |
| QWheelEvent & | operator=(const QWheelEvent &other) |
Descripción detallada
Los eventos de rueda se envían al widget situado bajo el cursor del ratón, pero si dicho widget no gestiona el evento, se envían al widget con foco. Los eventos de rueda se generan tanto para las ruedas del ratón como para los gestos de desplazamiento del trackpad. Hay dos formas de leer el delta del evento de rueda: ` angleDelta()` devuelve los deltas en grados de rueda. Estos valores siempre se proporcionan. ` pixelDelta` () devuelve los deltas en píxeles de pantalla y está disponible en plataformas que cuentan con trackpads de alta resolución, como macOS. Si ese es el caso, device()->type() devolverá QInputDevice::DeviceType::Touchpad.
Las funciones position() y globalPosition() devuelven la posición del cursor del ratón en el momento del evento.
Un evento de rueda contiene un indicador de aceptación especial que indica si el receptor desea el evento. Debes llamar a ignore() si no gestionas el evento de rueda; esto garantiza que se envíe al widget padre.
La función QWidget::setEnabled() se puede utilizar para habilitar o deshabilitar los eventos de ratón y teclado de un widget.
El controlador de eventos QWidget::wheelEvent() recibe eventos de rueda.
Véase también QMouseEvent y QWidget::grabMouse().
Documentación de propiedades
[read-only] angleDelta : QPoint
Esta propiedad almacena el ángulo relativo de giro de la rueda, expresado en octavos de grado
Un valor positivo indica que la rueda se ha girado hacia delante, alejándose del usuario; un valor negativo indica que la rueda se ha girado hacia atrás, acercándose al usuario. angleDelta().y() proporciona el ángulo en el que se ha girado la rueda vertical habitual del ratón desde el evento anterior. angleDelta().x() proporciona el ángulo en el que se ha girado la rueda horizontal del ratón, si este dispone de una rueda horizontal; en caso contrario, se mantiene en cero.
La mayoría de los tipos de ratón funcionan en pasos de 15 grados, en cuyo caso el valor delta es un múltiplo de 120; es decir, 120 unidades * 1/8 = 15 grados.
Nota: En plataformas que admiten el desplazamiento phases, el valor delta puede ser nulo cuando el desplazamiento está a punto de comenzar (Qt::ScrollBegin) o ha finalizado (Qt::ScrollEnd).
Funciones de acceso:
| QPoint | angleDelta() const |
Véase también pixelDelta().
[read-only] device : const QPointingDevice*
Esta propiedad contiene el dispositivo desde el que se originó el evento de la rueda
Véase también pointingDevice().
[read-only] inverted : bool
Esta propiedad se cumple independientemente de si los valores delta proporcionados con el evento están invertidos
Normalmente, una rueda vertical generará un QWheelEvent con valores delta positivos si la parte superior de la rueda gira alejándose de la mano que la maneja. Del mismo modo, un movimiento horizontal de la rueda generará un QWheelEvent con valores delta positivos si la parte superior de la rueda se desplaza hacia la izquierda.
Sin embargo, en algunas plataformas esto es configurable, de modo que las mismas operaciones descritas anteriormente producirán valores delta negativos (pero con la misma magnitud). Con la propiedad «inverted», un consumidor de eventos de rueda puede optar por seguir siempre la dirección de la rueda, independientemente de la configuración del sistema, pero solo para determinados widgets.
Nota: Muchas plataformas no proporcionan este tipo de información. En dichas plataformas, la función « inverted » siempre devuelve «false».
Funciones de acceso:
| bool | inverted() const |
[read-only] phase : Qt::ScrollPhase
Esta propiedad contiene la fase de desplazamiento de este evento de rueda
Nota: Las fases « Qt::ScrollBegin » y « Qt::ScrollEnd » solo son compatibles actualmente con macOS.
Funciones de acceso:
| Qt::ScrollPhase | phase() const |
[read-only] pixelDelta : QPoint
Esta propiedad contiene la distancia de desplazamiento en píxeles en la pantalla
Este valor se proporciona en plataformas que admiten valores delta basados en píxeles de alta resolución, como macOS. El valor debe utilizarse directamente para desplazar el contenido en pantalla.
Nota: En plataformas que admiten el desplazamiento phases, el valor delta puede ser nulo cuando el desplazamiento está a punto de comenzar (Qt::ScrollBegin) o ha finalizado (Qt::ScrollEnd).
Nota: En X11, este valor depende del controlador y no es fiable; utilice en su lugar angleDelta().
Funciones de acceso:
| QPoint | pixelDelta() const |
Véase también ` angleDelta()` ().
Documentación de las funciones miembro
QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, bool inverted, Qt::MouseEventSource source = Qt::MouseEventNotSynthesized, const QPointingDevice *device = QPointingDevice::primaryPointingDevice())
Crea un objeto de evento de rueda.
La propiedad ` pos ` proporciona la ubicación del cursor del ratón dentro de la ventana. La posición en coordenadas globales se especifica mediante ` globalPos`.
pixelDelta contiene la distancia de desplazamiento en píxeles en pantalla, mientras que ` angleDelta ` contiene el ángulo de rotación de la rueda. ` pixelDelta ` es opcional y puede ser nulo.
Los estados del ratón y del teclado en el momento del evento se especifican mediante buttons y modifiers.
La fase de desplazamiento del evento viene especificada por ` phase`, y ` source ` indica si se trata de un evento genuino o artificial (sintetizado).
Si el sistema está configurado para invertir los valores delta proporcionados con el evento (como el desplazamiento natural del panel táctil en macOS), inverted debe ser true. De lo contrario, inverted es false
El dispositivo del que se originó el evento de rueda se especifica mediante device.
Véase también position(), globalPosition(), angleDelta(), pixelDelta(), phase(), inverted() y device().
[protected delete] QWheelEvent::QWheelEvent(QWheelEvent &&)
Crea una instancia de ` QWheelEvent`. Esta función se ha eliminado.
QPoint QWheelEvent::angleDelta() const
Devuelve el ángulo relativo de giro de la rueda, expresado en octavos de grado. Un valor positivo indica que la rueda se ha girado hacia delante, alejándose del usuario; un valor negativo indica que la rueda se ha girado hacia atrás, acercándose al usuario. ` angleDelta().y() ` proporciona el ángulo en el que se ha girado la rueda vertical habitual del ratón desde el evento anterior. ` angleDelta().x() ` proporciona el ángulo en el que se ha girado la rueda horizontal del ratón, si este dispone de una rueda horizontal; en caso contrario, se mantiene en cero. Algunos ratones permiten al usuario inclinar la rueda para realizar un desplazamiento horizontal, y algunos paneles táctiles admiten un gesto de desplazamiento horizontal; esto también aparecerá en angleDelta().x().
La mayoría de los tipos de ratón funcionan en pasos de 15 grados, en cuyo caso el valor delta es un múltiplo de 120; es decir, 120 unidades * 1/8 = 15 grados.
Sin embargo, algunos ratones tienen ruedas de mayor resolución y envían valores delta inferiores a 120 unidades (menos de 15 grados). Para dar respuesta a esta posibilidad, puedes sumar de forma acumulativa los valores delta de los eventos hasta alcanzar el valor de 120 y, a continuación, desplazar el widget, o bien puedes desplazar parcialmente el widget en respuesta a cada evento de la rueda. No obstante, para ofrecer una sensación más natural, es recomendable utilizar ` pixelDelta()` en las plataformas en las que esté disponible.
Ejemplo:
void MyWidget::wheelEvent(QWheelEvent *event)
{
QPoint numPixels = event->pixelDelta();
QPoint numDegrees = event->angleDelta() / 8;
if (!numPixels.isNull()) {
scrollWithPixels(numPixels);
} else if (!numDegrees.isNull()) {
QPoint numSteps = numDegrees / 15;
scrollWithDegrees(numSteps);
}
event->accept();
}Nota: En las plataformas que admiten el desplazamiento mediante ` phases`, el valor delta puede ser nulo cuando:
- el desplazamiento esté a punto de comenzar, pero la distancia aún no haya cambiado (Qt::ScrollBegin),
- o cuando el desplazamiento ha finalizado y la distancia ya no ha variado (Qt::ScrollEnd).
Nota: Funcióngetter para la propiedad angleDelta.
Véase también pixelDelta().
bool QWheelEvent::inverted() const
Devuelve si los valores delta proporcionados con el evento están invertidos.
Normalmente, una rueda vertical generará un QWheelEvent con valores delta positivos si la parte superior de la rueda gira alejándose de la mano que la maneja. Del mismo modo, un movimiento horizontal de la rueda generará un QWheelEvent con valores delta positivos si la parte superior de la rueda se desplaza hacia la izquierda.
Sin embargo, en algunas plataformas esto es configurable, por lo que las mismas operaciones descritas anteriormente producirán valores delta negativos (pero con la misma magnitud). Con la propiedad «inverted», un consumidor de eventos de rueda puede optar por seguir siempre la dirección de la rueda, independientemente de la configuración del sistema, pero solo para widgets específicos. (Un caso de uso podría ser que el usuario gire la rueda en la misma dirección en que gira un «Tumbler» visual. Otro caso de uso es hacer que el control deslizante siga la dirección del movimiento de los dedos en un panel táctil, independientemente de la configuración del sistema.)
Nota: Muchas plataformas no proporcionan este tipo de información. En dichas plataformas, inverted siempre devuelve «false».
Nota: Funcióngetter para la propiedad «inverted».
[override virtual] bool QWheelEvent::isBeginEvent() const
Reimplementa: QSinglePointEvent::isBeginEvent() const.
Devuelve ` true ` si ` phase()` de este evento es ` Qt::ScrollBegin`.
[override virtual] bool QWheelEvent::isEndEvent() const
Reimplementa: QSinglePointEvent::isEndEvent() const.
Devuelve ` true ` si ` phase()` de este evento es ` Qt::ScrollEnd`.
[override virtual] bool QWheelEvent::isUpdateEvent() const
Reimplementa: QSinglePointEvent::isUpdateEvent() const.
Devuelve true si phase() de este evento es Qt::ScrollUpdate o Qt::ScrollMomentum.
Qt::ScrollPhase QWheelEvent::phase() const
Devuelve la fase de desplazamiento de este evento de rueda.
Nota: Las fases « Qt::ScrollBegin » y « Qt::ScrollEnd » solo son compatibles actualmente con macOS.
Nota: Funcióngetter para la propiedad «phase».
QPoint QWheelEvent::pixelDelta() const
Devuelve la distancia de desplazamiento en píxeles en pantalla. Este valor está disponible en plataformas que admiten valores delta basados en píxeles de alta resolución, como macOS. El valor debe utilizarse directamente para desplazar el contenido en pantalla.
Ejemplo:
void MyWidget::wheelEvent(QWheelEvent *event)
{
QPoint numPixels = event->pixelDelta();
QPoint numDegrees = event->angleDelta() / 8;
if (!numPixels.isNull()) {
scrollWithPixels(numPixels);
} else if (!numDegrees.isNull()) {
QPoint numSteps = numDegrees / 15;
scrollWithDegrees(numSteps);
}
event->accept();
}Nota: En plataformas que admiten el desplazamiento phases, el delta puede ser nulo cuando:
- el desplazamiento está a punto de comenzar, pero la distancia aún no ha cambiado (Qt::ScrollBegin),
- o el desplazamiento ha finalizado y la distancia ya no ha cambiado más (Qt::ScrollEnd).
Nota: En X11, este valor depende del controlador y no es fiable; utiliza angleDelta() en su lugar.
Nota: Funcióngetter para la propiedad pixelDelta.
[protected delete] QWheelEvent &QWheelEvent::operator=(QWheelEvent &&)
Asigna mediante «move» other a esta instancia de QWheelEvent. Esta función se elimina.
[noexcept protected default] QWheelEvent &QWheelEvent::operator=(const QWheelEvent &other)
Asigna por copia other a esta instancia de QWheelEvent.
© 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.