3 files changed, 69 insertions, 8 deletions

diff --git a/src/quick/handlers/qquickdraghandler.cpp b/src/quick/handlers/qquickdraghandler.cpp
index 22fe3df4d0..61b66beff4 100644
--- a/src/quick/handlers/qquickdraghandler.cpp
+++ b/src/quick/handlers/qquickdraghandler.cpp
@@ -114,8 +114,14 @@ void QQuickDragHandler::onGrabChanged(QQuickPointerHandler *grabber, QQuickEvent
     QQuickMultiPointHandler::onGrabChanged(grabber, transition, point);
     if (grabber == this && transition == QQuickEventPoint::GrabExclusive && target()) {
         // In case the grab got handed over from another grabber, we might not get the Press.
-        if (!m_pressedInsideTarget) {
-            if (target() != parentItem())
+
+        auto isDescendant = [](QQuickItem *parent, QQuickItem *target) {
+            return (target != parent) && !target->isAncestorOf(parent);
+        };
+        if (m_snapMode == SnapAlways
+            || (m_snapMode == SnapIfPressedOutsideTarget && !m_pressedInsideTarget)
+            || (m_snapMode == SnapAuto && !m_pressedInsideTarget && isDescendant(parentItem(), target()))
+            ) {
                 m_pressTargetPos = QPointF(target()->width(), target()->height()) / 2;
         } else if (m_pressTargetPos.isNull()) {
             m_pressTargetPos = targetCentroidPosition();
@@ -123,6 +129,33 @@ void QQuickDragHandler::onGrabChanged(QQuickPointerHandler *grabber, QQuickEvent
     }
 }
 
+/*!
+    \qmlproperty enumeration QtQuick.DragHandler::snapMode
+
+    This property holds the snap mode.
+
+    The snap mode configures snapping of the \l target item's center to the event point.
+
+    Possible values:
+    \value DragHandler.SnapNever Never snap
+    \value DragHandler.SnapAuto The \l target snaps if the event point was pressed outside of the \l target
+                                item \e and the \l target is a descendant of \l parentItem (default)
+    \value DragHandler.SnapWhenPressedOutsideTarget The \l target snaps if the event point was pressed outside of the \l target
+    \value DragHandler.SnapAlways Always snap
+*/
+QQuickDragHandler::SnapMode QQuickDragHandler::snapMode() const
+{
+    return m_snapMode;
+}
+
+void QQuickDragHandler::setSnapMode(QQuickDragHandler::SnapMode mode)
+{
+    if (mode == m_snapMode)
+        return;
+    m_snapMode = mode;
+    emit snapModeChanged();
+}
+
 void QQuickDragHandler::onActiveChanged()
 {
     QQuickMultiPointHandler::onActiveChanged();
diff --git a/src/quick/handlers/qquickdraghandler_p.h b/src/quick/handlers/qquickdraghandler_p.h
index 748026488a..18c1fd841d 100644
--- a/src/quick/handlers/qquickdraghandler_p.h
+++ b/src/quick/handlers/qquickdraghandler_p.h
@@ -62,8 +62,17 @@ class Q_QUICK_PRIVATE_EXPORT QQuickDragHandler : public QQuickMultiPointHandler
     Q_PROPERTY(QQuickDragAxis * xAxis READ xAxis CONSTANT)
     Q_PROPERTY(QQuickDragAxis * yAxis READ yAxis CONSTANT)
     Q_PROPERTY(QVector2D translation READ translation NOTIFY translationChanged)
+    Q_PROPERTY(SnapMode snapMode READ snapMode WRITE setSnapMode NOTIFY snapModeChanged)
 
 public:
+    enum SnapMode {
+        NoSnap = 0,
+        SnapAuto,
+        SnapIfPressedOutsideTarget,
+        SnapAlways
+    };
+    Q_ENUM(SnapMode)
+
     explicit QQuickDragHandler(QQuickItem *parent = nullptr);
 
     void handlePointerEventImpl(QQuickPointerEvent *event) override;
@@ -73,11 +82,14 @@ public:
 
     QVector2D translation() const { return m_translation; }
     void setTranslation(const QVector2D &trans);
+    QQuickDragHandler::SnapMode snapMode() const;
+    void setSnapMode(QQuickDragHandler::SnapMode mode);
 
     void enforceConstraints();
 
 Q_SIGNALS:
     void translationChanged();
+    void snapModeChanged();
 
 protected:
     void onActiveChanged() override;
@@ -97,6 +109,7 @@ private:
 
     QQuickDragAxis m_xAxis;
     QQuickDragAxis m_yAxis;
+    QQuickDragHandler::SnapMode m_snapMode = SnapAuto;
     bool m_pressedInsideTarget = false;
 
     friend class QQuickDragAxis;
diff --git a/src/quick/handlers/qquicktaphandler.cpp b/src/quick/handlers/qquicktaphandler.cpp
index 081645da71..40a4813527 100644
--- a/src/quick/handlers/qquicktaphandler.cpp
+++ b/src/quick/handlers/qquicktaphandler.cpp
@@ -381,35 +381,50 @@ void QQuickTapHandler::updateTimeHeld()
 */
 
 /*!
-    \qmlsignal QtQuick::TapHandler::tapped
+    \qmlsignal QtQuick::TapHandler::tapped(EventPoint eventPoint)
 
     This signal is emitted each time the \c parent Item is tapped.
 
     That is, if you press and release a touchpoint or button within a time
     period less than \l longPressThreshold, while any movement does not exceed
     the drag threshold, then the \c tapped signal will be emitted at the time
-    of release.
+    of release.  The \c eventPoint signal parameter contains information
+    from the release event about the point that was tapped:
+
+    \snippet pointerHandlers/tapHandlerOnTapped.qml 0
+
+    \note At the time this signal is emitted, \l point has been reset
+    (all coordinates are \c 0).
 */
 
 /*!
-    \qmlsignal QtQuick::TapHandler::singleTapped
+    \qmlsignal QtQuick::TapHandler::singleTapped(EventPoint eventPoint)
     \since 5.11
 
     This signal is emitted when the \c parent Item is tapped once.
     After an amount of time greater than QStyleHints::mouseDoubleClickInterval,
     it can be tapped again; but if the time until the next tap is less,
-    \l tapCount will increase.
+    \l tapCount will increase. The \c eventPoint signal parameter contains
+    information from the release event about the point that was tapped.
+
+    \note At the time this signal is emitted, \l point has been reset
+    (all coordinates are \c 0).
 */
 
 /*!
-    \qmlsignal QtQuick::TapHandler::doubleTapped
+    \qmlsignal QtQuick::TapHandler::doubleTapped(EventPoint eventPoint)
     \since 5.11
 
     This signal is emitted when the \c parent Item is tapped twice within a
     short span of time (QStyleHints::mouseDoubleClickInterval) and distance
     (QPlatformTheme::MouseDoubleClickDistance or
     QPlatformTheme::TouchDoubleTapDistance). This signal always occurs after
-    \l singleTapped, \l tapped, and \l tapCountChanged.
+    \l singleTapped, \l tapped, and \l tapCountChanged. The \c eventPoint
+    signal parameter contains information from the release event about the
+    point that was tapped.
+
+    \note At the time this signal is emitted, \l point has been reset
+    (all coordinates are \c 0).
 */
 
 /*!