En esta página

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

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.