WheelHandler QML Type▲

  • Import Statement: import QtQuick 2.15

  • 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: 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. Optionally it can handle smooth-scrolling events from touchpad gestures, 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 regardless of the setting of the acceptedDevices property.

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 Pointer Handler.

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

For example, a control could be made to respond to mouse and stylus clicks in one way, and touchscreen taps in another way, with two handlers:

 
Sélectionnez
Item {
   TapHandler {
       acceptedDevices: PointerDevice.Mouse | PointerDevice.Stylus
       onTapped: console.log("clicked")
   }
   TapHandler {
       acceptedDevices: PointerDevice.TouchScreen
       onTapped: console.log("tapped")
   }
}

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