diff options
author | Shawn Rutledge <shawn.rutledge@qt.io> | 2020-01-13 08:54:27 +0100 |
---|---|---|
committer | Shawn Rutledge <shawn.rutledge@qt.io> | 2020-01-13 17:36:37 +0100 |
commit | 96cf8a33c3c2fa8a3e010e33c37462e3a703fe3d (patch) | |
tree | 4bccc4cbef04358828aed1090de8fc7dc3e0ca94 /src | |
parent | 1f4cfccecdb423be66ac1f6eda70e87c382972f8 (diff) |
Register PointerScrollEvent and document the WheelHandler.wheel signal
Writing an onWheel() handler script was working and mentioned briefly
in docs; but PointerScrollEvent and the signal were not documented.
Also fixed the type of QtQuick::WheelEvent::inverted: bool not int.
Fixes: QTBUG-81302
Change-Id: I31342955c42e20ff52460a1b7ee95da325e38af6
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>
Diffstat (limited to 'src')
-rw-r--r-- | src/quick/handlers/qquickwheelhandler.cpp | 9 | ||||
-rw-r--r-- | src/quick/items/qquickevents.cpp | 133 | ||||
-rw-r--r-- | src/quick/items/qquickitemsmodule.cpp | 4 |
3 files changed, 142 insertions, 4 deletions
diff --git a/src/quick/handlers/qquickwheelhandler.cpp b/src/quick/handlers/qquickwheelhandler.cpp index aef2e8ebfb..16f38af962 100644 --- a/src/quick/handlers/qquickwheelhandler.cpp +++ b/src/quick/handlers/qquickwheelhandler.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the QtQuick module of the Qt Toolkit. @@ -500,6 +500,13 @@ void QQuickWheelHandler::timerEvent(QTimerEvent *event) } } +/*! + \qmlsignal QtQuick::WheelHandler::wheel(PointerScrollEvent event) + + This signal is emitted every time this handler receives a \l QWheelEvent: + that is, every time the wheel is moved or the scrolling gesture is updated. +*/ + QQuickWheelHandlerPrivate::QQuickWheelHandlerPrivate() : QQuickSinglePointHandlerPrivate() { diff --git a/src/quick/items/qquickevents.cpp b/src/quick/items/qquickevents.cpp index 0c697739fa..b5644d55e6 100644 --- a/src/quick/items/qquickevents.cpp +++ b/src/quick/items/qquickevents.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2017 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the QtQuick module of the Qt Toolkit. @@ -448,7 +448,7 @@ Item { */ /*! - \qmlproperty int QtQuick::WheelEvent::inverted + \qmlproperty bool QtQuick::WheelEvent::inverted Returns whether the delta values delivered with the event are inverted. @@ -1431,6 +1431,135 @@ QQuickEventPoint *QQuickSinglePointEvent::point(int i) const return nullptr; } + +/*! + \qmltype PointerScrollEvent + \instantiates QQuickPointerScrollEvent + \inqmlmodule QtQuick + \ingroup qtquick-input-events + \brief Provides information about a scrolling event, such as from a mouse wheel. + + \sa WheelHandler +*/ + +/*! + \internal + \class QQuickPointerScrollEvent +*/ + +/*! + \readonly + \qmlproperty PointerDevice QtQuick::PointerScrollEvent::device + + This property holds the device that generated the event. +*/ + +/*! + \qmlproperty int QtQuick::PointerScrollEvent::buttons + + This property holds the mouse buttons pressed when the wheel event was generated. + + It contains a bitwise combination of: + \list + \li \l {Qt::LeftButton} {Qt.LeftButton} + \li \l {Qt::RightButton} {Qt.RightButton} + \li \l {Qt::MiddleButton} {Qt.MiddleButton} + \endlist +*/ + +/*! + \readonly + \qmlproperty int QtQuick::PointerScrollEvent::modifiers + + This property holds the \l {Qt::KeyboardModifier}{keyboard modifier} keys + that were pressed immediately before the event occurred. + + It contains a bitwise combination of the following flags: + \value Qt.NoModifier + No modifier key is pressed. + \value Qt.ShiftModifier + A Shift key on the keyboard is pressed. + \value Qt.ControlModifier + A Ctrl key on the keyboard is pressed. + \value Qt.AltModifier + An Alt key on the keyboard is pressed. + \value Qt.MetaModifier + A Meta key on the keyboard is pressed. + \value Qt.KeypadModifier + A keypad button is pressed. + + For example, to react to a Shift key + Left mouse button click: + \qml + Item { + TapHandler { + onTapped: { + if ((event.button == Qt.LeftButton) && (event.modifiers & Qt.ShiftModifier)) + doSomething(); + } + } + } + \endqml +*/ + +/*! + \qmlproperty point QtQuick::PointerScrollEvent::angleDelta + + This property holds the distance that the wheel is rotated in wheel degrees. + The x and y cordinate of this property holds the delta in horizontal and + vertical orientation. + + A positive value indicates that the wheel was rotated up/right; + a negative value indicates that the wheel was rotated down/left. + + 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. +*/ + +/*! + \qmlproperty point QtQuick::PointerScrollEvent::pixelDelta + + This property holds the delta in screen pixels and is available in platforms that + have high-resolution trackpads, such as \macos. + The x and y coordinates of this property hold the delta in horizontal and + vertical orientation. The value should be used directly to scroll content on screen. + + For platforms without high-resolution touchpad support, pixelDelta will + always be (0,0), and angleDelta should be used instead. +*/ + +/*! + \qmlproperty bool QtQuick::PointerScrollEvent::hasAngleDelta + + Returns whether the \l angleDelta property has a non-null value. +*/ + +/*! + \qmlproperty bool QtQuick::PointerScrollEvent::hasPixelDelta + + Returns whether the \l pixelDelta property has a non-null value. +*/ + +/*! + \qmlproperty bool QtQuick::PointerScrollEvent::inverted + + Returns whether the delta values delivered with the event are inverted. + + Normally, a vertical wheel will produce a PointerScrollEvent 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 PointerScrollEvent 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). In a QML component (such as a tumbler or a slider) where + it is appropriate to synchronize the movement or rotation of an item with + the direction of the wheel, regardless of the system settings, the wheel + event handler can use the inverted property to decide whether to negate the + \l angleDelta or \l pixelDelta values. + + \note Many platforms provide no such information. On such platforms, + \c inverted always returns false. +*/ QQuickPointerEvent *QQuickPointerScrollEvent::reset(QEvent *event) { m_event = static_cast<QInputEvent*>(event); diff --git a/src/quick/items/qquickitemsmodule.cpp b/src/quick/items/qquickitemsmodule.cpp index 7bc6eefe0a..86253e770f 100644 --- a/src/quick/items/qquickitemsmodule.cpp +++ b/src/quick/items/qquickitemsmodule.cpp @@ -1,6 +1,6 @@ /**************************************************************************** ** -** Copyright (C) 2019 The Qt Company Ltd. +** Copyright (C) 2020 The Qt Company Ltd. ** Contact: https://www.qt.io/licensing/ ** ** This file is part of the QtQuick module of the Qt Toolkit. @@ -494,6 +494,8 @@ static void qt_quickitems_defineModule(const char *uri, int major, int minor) #endif #if QT_CONFIG(wheelevent) qmlRegisterType<QQuickWheelHandler>(uri, 2, 14, "WheelHandler"); + qmlRegisterUncreatableType<QQuickPointerScrollEvent>(uri, 2, 14, "PointerScrollEvent", + QQuickPointerHandler::tr("PointerScrollEvent is only available via the WheelHandler::wheel signal")); #endif qmlRegisterUncreatableType<QQuickImageBase, 14>(uri, 2, 14, "ImageBase", QQuickPointerHandler::tr("ImageBase is an abstract base class")); |