QWheelEvent Class

Member Function Documentation

QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, int qt4Delta, Qt::Orientation qt4Orientation, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers)

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 distance. pixelDelta is optional and can be null.

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

For backwards compatibility, the event can also hold monodirectional wheel event data: qt4Delta specifies the rotation, and qt4Orientation the direction.

The phase() is initialized to Qt::ScrollUpdate. Use the other constructor to specify the phase explicitly.

See also posF(), globalPosF(), angleDelta(), and pixelDelta().

QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, int qt4Delta, Qt::Orientation qt4Orientation, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase)

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 distance. pixelDelta is optional and can be null.

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

For backwards compatibility, the event can also hold monodirectional wheel event data: qt4Delta specifies the rotation, and qt4Orientation the direction.

The scrolling phase of the event is specified by phase.

See also posF(), globalPosF(), angleDelta(), pixelDelta(), and phase().

QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, int qt4Delta, Qt::Orientation qt4Orientation, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, Qt::MouseEventSource source)

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 distance. pixelDelta is optional and can be null.

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

For backwards compatibility, the event can also hold monodirectional wheel event data: qt4Delta specifies the rotation, and qt4Orientation the direction.

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.

See also posF(), globalPosF(), angleDelta(), pixelDelta(), and phase().

QWheelEvent::QWheelEvent(const QPointF &pos, const QPointF &globalPos, QPoint pixelDelta, QPoint angleDelta, int qt4Delta, Qt::Orientation qt4Orientation, Qt::MouseButtons buttons, Qt::KeyboardModifiers modifiers, Qt::ScrollPhase phase, Qt::MouseEventSource source, bool inverted)

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 distance. pixelDelta is optional and can be null.

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

For backwards compatibility, the event can also hold monodirectional wheel event data: qt4Delta specifies the rotation, and qt4Orientation the direction.

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 OS X), inverted should be true. Otherwise, inverted is false

See also posF(), globalPosF(), angleDelta(), pixelDelta(), and phase().

QPoint QWheelEvent::angleDelta() const

Returns the distance that the wheel is 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.

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.

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).

Qt::MouseButtons QWheelEvent::buttons() const

Returns the mouse state when the event occurred.

QPoint QWheelEvent::globalPos() const

Returns the global position of the mouse pointer at the time of the event. This is important on asynchronous window systems such as X11; whenever you move your widgets around in response to mouse events, globalPos() can differ a lot from the current cursor position returned by QCursor::pos().

See also globalX() and globalY().

const QPointF &QWheelEvent::globalPosF() const

Returns the global position of the mouse pointer at the time of the event. This is important on asynchronous window systems such as X11; whenever you move your widgets around in response to mouse events, globalPosF() can differ a lot from the current cursor position returned by QCursor::pos().

See also posF().

int QWheelEvent::globalX() const

Returns the global x position of the mouse cursor at the time of the event.

See also globalY() and globalPos().

int QWheelEvent::globalY() const

Returns the global y position of the mouse cursor at the time of the event.

See also globalX() and globalPos().

bool QWheelEvent::inverted() const

Returns whether the delta values delivered with the event are inverted.

Normally, a vertical wheel will produce a QWheelEvent with positive delta values if the top of the wheel is rotating away from the hand operating it. Similarly, a horizontal wheel movement will produce a QWheelEvent with positive delta values if the top of the wheel is moved to the left.

However, on some platforms this is configurable, so that the same operations described above will produce negative delta values (but with the same magnitude). With the inverted property a wheel event consumer can choose to always follow the direction of the wheel, regardless of the system settings, but only for specific widgets. (One such use case could be that the user is rotating the wheel in the same direction as a visual Tumbler rotates. Another usecase is to make a slider handle follow the direction of movement of fingers on a touchpad regardless of system configuration.)

Note: Many platforms provide no such information. On such platforms inverted always returns false.

This function was introduced in Qt 5.7.

Qt::ScrollPhase QWheelEvent::phase() const

Returns the scrolling phase of this wheel event.

Note: The Qt::ScrollBegin and Qt::ScrollEnd phases are currently supported only on macOS.

This function was introduced in Qt 5.2.

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

QPoint QWheelEvent::pos() const

Returns the position of the mouse cursor relative to the widget that received the event.

If you move your widgets around in response to mouse events, use globalPos() instead of this function.

See also x(), y(), and globalPos().

const QPointF &QWheelEvent::posF() const

Returns the position of the mouse cursor relative to the widget that received the event.

If you move your widgets around in response to mouse events, use globalPosF() instead of this function.

See also globalPosF().

Qt::MouseEventSource QWheelEvent::source() const

Returns information about the wheel event source.

The source can be used to distinguish between events that come from a mouse with a physical wheel and events that are generated by some other means, such as a flick gesture on a touchpad.

Note: Many platforms provide no such information. On such platforms Qt::MouseEventNotSynthesized is returned always.

This function was introduced in Qt 5.5.

See also Qt::MouseEventSource.

int QWheelEvent::x() const

Returns the x position of the mouse cursor, relative to the widget that received the event.

See also y() and pos().

int QWheelEvent::y() const

Returns the y position of the mouse cursor, relative to the widget that received the event.

See also x() and pos().