QWheelEvent Class

Member Function Documentation

QWheelEvent::QWheelEvent(QPointF pos, QPointF globalPos, QPoint pixelDelta, QPoint angleDelta, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, bool inverted, Qt::MouseEventSource source = Qt::MouseEventNotSynthesized)

Constructs a wheel event object.

The pos provides the location of the mouse cursor within the window. The position in global coordinates is specified by globalPos.

pixelDelta contains the scrolling distance in pixels on screen, while angleDelta contains the wheel rotation angle. pixelDelta is optional and can be null.

The mouse and keyboard states at the time of the event are specified by buttons and modifiers.

The scrolling phase of the event is specified by phase.

If the wheel event comes from a physical mouse wheel, source is set to Qt::MouseEventNotSynthesized. If it comes from a gesture detected by the operating system, or from a non-mouse hardware device, such that pixelDelta is directly related to finger movement, source is set to Qt::MouseEventSynthesizedBySystem. If it comes from Qt, source would be set to Qt::MouseEventSynthesizedByQt.

If the system is configured to invert the delta values delivered with the event (such as natural scrolling of the touchpad on macOS), inverted should be true. Otherwise, inverted is false

This function was introduced in Qt 5.12.

See also position(), globalPosition(), angleDelta(), pixelDelta(), phase(), inverted(), and source().

QPoint QWheelEvent::angleDelta() const

Returns the relative amount that the wheel was rotated, in eighths of a degree. A positive value indicates that the wheel was rotated forwards away from the user; a negative value indicates that the wheel was rotated backwards toward the user. angleDelta().y() provides the angle through which the common vertical mouse wheel was rotated since the previous event. angleDelta().x() provides the angle through which the horizontal mouse wheel was rotated, if the mouse has a horizontal wheel; otherwise it stays at zero. Some mice allow the user to tilt the wheel to perform horizontal scrolling, and some touchpads support a horizontal scrolling gesture; that will also appear in angleDelta().x().

Most mouse types work in steps of 15 degrees, in which case the delta value is a multiple of 120; i.e., 120 units * 1/8 = 15 degrees.

However, some mice have finer-resolution wheels and send delta values that are less than 120 units (less than 15 degrees). To support this possibility, you can either cumulatively add the delta values from events until the value of 120 is reached, then scroll the widget, or you can partially scroll the widget in response to each wheel event. But to provide a more native feel, you should prefer pixelDelta() on platforms where it's available.

Example:

 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();
 }

Note: On platforms that support scrolling phases, the delta may be null when:

• scrolling is about to begin, but the distance did not yet change (Qt::ScrollBegin),
• or scrolling has ended and the distance did not change anymore (Qt::ScrollEnd).

See also pixelDelta().

QPoint QWheelEvent::pixelDelta() const

Returns the scrolling distance in pixels on screen. This value is provided on platforms that support high-resolution pixel-based delta values, such as macOS. The value should be used directly to scroll content on screen.

Example:

 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();
 }

Note: On platforms that support scrolling phases, the delta may be null when:

• scrolling is about to begin, but the distance did not yet change (Qt::ScrollBegin),
• or scrolling has ended and the distance did not change anymore (Qt::ScrollEnd).

Note: On X11 this value is driver specific and unreliable, use angleDelta() instead