doc: explain more about acceptedModifiers in PointerDeviceHandler

Having neither a list of all possible modifiers nor a link to
Qt::KeyboardModifier was inconvenient.  Clarify that bitwise OR
results in logical-AND behavior, while having multiple handlers
results in logical-OR behavior, and that a switch statement in JS
allows you do anything you like with modifiers.  Fix the manual test
to test the switch statement and deal with the fact that
point.event.modifiers is undefined: TapHandler can use
eventPoint.modifiers, but any DeviceHandler can use point.modifiers.

Fixes: QTBUG-78234
Change-Id: Iba2a03950aa1279ef454cc76fc8de1b2dab14dfb
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Jan Arve Sæther <jan-arve.saether@qt.io>

2 files changed, 62 insertions, 3 deletions

diff --git a/src/quick/handlers/qquickpointerdevicehandler.cpp b/src/quick/handlers/qquickpointerdevicehandler.cpp
index 246686e4f4..2964042f39 100644
--- a/src/quick/handlers/qquickpointerdevicehandler.cpp
+++ b/src/quick/handlers/qquickpointerdevicehandler.cpp
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2016 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the QtQuick module of the Qt Toolkit.
@@ -230,6 +230,55 @@ void QQuickPointerDeviceHandler::setAcceptedPointerTypes(QQuickPointerDevice::Po
        }
     }
     \endqml
+
+    If you set \c acceptedModifiers to an OR combination of modifier keys,
+    it means \e all of those modifiers must be pressed to activate the handler:
+
+    \qml
+    Item {
+       TapHandler {
+           acceptedModifiers: Qt.ControlModifier | Qt.AltModifier | Qt.ShiftModifier
+           onTapped: console.log("control-alt-shift-tapped")
+       }
+    }
+    \endqml
+
+    The available modifiers are as follows:
+
+    \value NoModifier       No modifier key is allowed.
+    \value ShiftModifier    A Shift key on the keyboard must be pressed.
+    \value ControlModifier  A Ctrl key on the keyboard must be pressed.
+    \value AltModifier      An Alt key on the keyboard must be pressed.
+    \value MetaModifier     A Meta key on the keyboard must be pressed.
+    \value KeypadModifier   A keypad button must be pressed.
+    \value GroupSwitchModifier X11 only (unless activated on Windows by a command line argument).
+                            A Mode_switch key on the keyboard must be pressed.
+    \value 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:
+
+    \qml
+    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;
+                }
+        }
+    }
+    \endqml
+
+    \sa Qt::KeyboardModifier
 */
 void QQuickPointerDeviceHandler::setAcceptedModifiers(Qt::KeyboardModifiers acceptedModifiers)
 {
diff --git a/tests/manual/pointer/tapWithModifiers.qml b/tests/manual/pointer/tapWithModifiers.qml
index 8ca1c1bd63..da3c0cb30a 100644
--- a/tests/manual/pointer/tapWithModifiers.qml
+++ b/tests/manual/pointer/tapWithModifiers.qml
@@ -1,6 +1,6 @@
 /****************************************************************************
 **
-** Copyright (C) 2017 The Qt Company Ltd.
+** Copyright (C) 2019 The Qt Company Ltd.
 ** Contact: https://www.qt.io/licensing/
 **
 ** This file is part of the manual tests of the Qt Toolkit.
@@ -40,6 +40,16 @@ Item {
         onTapped: console.log("tapped with no modifiers")
     }
     TapHandler {
-        onTapped: console.log("tapped with modifiers " + point.event.modifiers)
+        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)
+            }
     }
 }