WheelHandler QML Type▲

  • Import Statement: import QtQuick

  • Inherits: SinglePointHandler

  • Group: WheelHandler is part of qtquick-input-handlers

Detailed Description▲

WheelHandler is a handler that is used to interactively manipulate some numeric property of an Item as the user rotates the mouse wheel. Like other Input Handlers, by default it manipulates its target. Declare property to control which target property will be manipulated:

 
Sélectionnez
import QtQuick 2.14

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 is quite useful in combination with WheelHandler (as well as with other Input Handlers) to declare the allowed range of values that the target property can have. For example it is possible to implement scrolling using a combination of WheelHandler and DragHandler to manipulate the scrollable Item's y property when the user rotates the wheel or drags the item on a touchscreen, and BoundaryRule to limit the range of motion from the top to the bottom:

 
Sélectionnez
import QtQuick 2.14
import Qt.labs.animation 1.0

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 }
        }
    }
}

Alternatively, if property is not set or target is null, WheelHandler will not automatically manipulate anything; but the rotation property can be used in a binding to manipulate another property, or you can implement onWheel and handle the wheel event directly.

WheelHandler handles only a rotating mouse wheel by default; this can be changed by setting acceptedDevices.

See Also▲

See also MouseArea, Flickable

Property Documentation▲

 

acceptedButtons : flags▲

The mouse buttons which can activate this Pointer Handler.

By default, this property is set to Qt.LeftButton. It can be set to an OR combination of mouse buttons, and will ignore events from other buttons.

For example, a control could be made to respond to left and right clicks in different ways, with two handlers:

 
Sélectionnez
Item {
    TapHandler {
        onTapped: console.log("left clicked")
    }
    TapHandler {
        acceptedButtons: Qt.RightButton
        onTapped: console.log("right clicked")
    }
}

Tapping on a touchscreen or tapping the stylus on a graphics tablet emulates clicking the left mouse button. This behavior can be altered via acceptedDevices or acceptedPointerTypes.

acceptedDevices : flags▲

The types of pointing devices that can activate this handler.

By default, this property is set to PointerDevice.Mouse, so as to react only to events events from an actual mouse wheel.

WheelHandler can be made to respond to both mouse wheel and touchpad scrolling by setting acceptedDevices to PointerDevice.Mouse | PointerDevice.TouchPad.

Some non-mouse hardware (such as a touch-sensitive Wacom tablet, or a Linux laptop touchpad) generates real wheel events from gestures. WheelHandler will respond to those events as wheel events even if acceptedDevices remains set to its default value.

acceptedModifiers : flags▲

If this property is set, it will require the given keyboard modifiers to be pressed in order to react to pointer events, and otherwise ignore them.

If this property is set to Qt.KeyboardModifierMask (the default value), then the PointerHandler ignores the modifier keys.

For example, an Item could have two handlers of the same type, one of which is enabled only if the required keyboard modifiers are pressed:

 
Sélectionnez
Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier
       onTapped: console.log("control-tapped")
   }
   TapHandler {
       acceptedModifiers: Qt.NoModifier
       onTapped: console.log("tapped")
   }
}

If you set acceptedModifiers to an OR combination of modifier keys, it means all of those modifiers must be pressed to activate the handler:

 
Sélectionnez
Item {
   TapHandler {
       acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
       onTapped: console.log("control-alt-shift-tapped")
   }
}

The available modifiers are as follows:

Constant

Description

NoModifier

No modifier key is allowed.

ShiftModifier

A Shift key on the keyboard must be pressed.

ControlModifier

A Ctrl key on the keyboard must be pressed.

AltModifier

An Alt key on the keyboard must be pressed.

MetaModifier

A Meta key on the keyboard must be pressed.

KeypadModifier

A keypad button must be pressed.

GroupSwitchModifier

X11 only (unless activated on Windows by a command line argument). A Mode_switch key on the keyboard must be pressed.

KeyboardModifierMask

The handler does not care which modifiers are pressed.

If you need even more complex behavior than can be achieved with combinations of multiple handlers with multiple modifier flags, you can check the modifiers in JavaScript code:

 
Sélectionnez
Item {
    TapHandler {
        onTapped:
            switch (point.modifiers) {
            case Qt.ControlModifier | Qt.AltModifier:
                console.log("CTRL+ALT");
                break;
            case Qt.ControlModifier | Qt.AltModifier | Qt.MetaModifier:
                console.log("CTRL+META+ALT");
                break;
            default:
                console.log("other modifiers", point.modifiers);
                break;
            }
    }
}
See Also▲

See also Qt::KeyboardModifier

acceptedPointerTypes : flags▲

The types of pointing instruments (finger, stylus, eraser, etc.) that can activate this Pointer Handler.

By default, this property is set to PointerDevice.AllPointerTypes. If you set it to an OR combination of device types, it will ignore events from non-matching events.

For example, a control could be made to respond to mouse, touch, and stylus clicks in some way, but delete itself if tapped with an eraser tool on a graphics tablet, with two handlers:

 
Sélectionnez
Rectangle {
   id: rect
   TapHandler {
       acceptedPointerTypes: PointerDevice.GenericPointer | PointerDevice.Finger | PointerDevice.Pen
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedPointerTypes: PointerDevice.Eraser
       onTapped: rect.destroy()
   }
}

[read-only] active : bool▲

This holds true whenever this Input Handler has taken sole responsibility for handing one or more EventPoints, by successfully taking an exclusive grab of those points. This means that it is keeping its properties up-to-date according to the movements of those Event Points and actively manipulating its target (if any).

activeTimeout : real▲

The amount of time in seconds after which the active property will revert to false if no more wheel events are received. The default is 0.1 (100 ms).

When WheelHandler handles events that contain scroll phase information, such as events from some touchpads, the active property will become false as soon as an event with phase Qt::ScrollEnd is received; in that case the timeout is not necessary. But a conventional mouse with a wheel does not provide a scroll phase: the mouse cannot detect when the user has decided to stop scrolling, so the active property transitions to false after this much time has elapsed.

See Also▲

See also QWheelEvent::phase()

[since 6.3] blocking : bool▲

Whether this handler prevents other items or handlers behind it from handling the same wheel event. This property is true by default.

This property was introduced in Qt 6.3.

[since 5.15] cursorShape : Qt::CursorShape▲

This property holds the cursor shape that will appear whenever the mouse is hovering over the parent item while active is true.

The available cursor shapes are:

  • Qt.ArrowCursor

  • Qt.UpArrowCursor

  • Qt.CrossCursor

  • Qt.WaitCursor

  • Qt.IBeamCursor

  • Qt.SizeVerCursor

  • Qt.SizeHorCursor

  • Qt.SizeBDiagCursor

  • Qt.SizeFDiagCursor

  • Qt.SizeAllCursor

  • Qt.BlankCursor

  • Qt.SplitVCursor

  • Qt.SplitHCursor

  • Qt.PointingHandCursor

  • Qt.ForbiddenCursor

  • Qt.WhatsThisCursor

  • Qt.BusyCursor

  • Qt.OpenHandCursor

  • Qt.ClosedHandCursor

  • Qt.DragCopyCursor

  • Qt.DragMoveCursor

  • Qt.DragLinkCursor

The default value is not set, which allows the cursor of parent item to appear. This property can be reset to the same initial condition by setting it to undefined.

When this property has not been set, or has been set to undefined, if you read the value it will return Qt.ArrowCursor.

This property was introduced in Qt 5.15.

See Also▲

See also Qt::CursorShape, QQuickItem::cursor(), HoverHandler::cursorShape

[since 5.15] dragThreshold : int▲

The distance in pixels that the user must drag an event point in order to have it treated as a drag gesture.

The default value depends on the platform and screen resolution. It can be reset back to the default value by setting it to undefined. The behavior when a drag gesture begins varies in different handlers.

This property was introduced in Qt 5.15.

enabled : bool