Standardize Drag/PinchHandler active/persistent scale, rotation, translation

PinchHandler.scale is persistent between gestures, whereas rotation and
translation were active-gesture properties; that wasn't consistent.
We fixed up DragHandler in just this way in 6.2.

The translationChanged() signal now comes with a vector delta, which is
often useful when writing an onTranslationChanged JS handler. Likewise,
scaleChanged() and rotationChanged() come with qreal deltas. The
scaleChanged() delta is multiplicative rather than additive, because
an additive delta would not be useful in cases when some target item's
scale can be adjusted by alternative means: you need to multiply it
in your onScaleChanged function.

Now that PinchHandler has 4 axes as grouped properties, some properties
in the handlers themselves begin to look redundant; but at least the
translation properties are useful to group x and y together. So in this
patch we continue to follow the pattern that was set in
60d11e1f69470d588666b76092cd40ae5644a855. PinchHandler.scale is
equivalent to persistentScale, whereas rotation is equivalent to
activeRotation; so we have a reason to deprecate those properties, as in
ea63ee523377bd11b957a9e74185792edd9b32e8.

The persistent values have setters, to provide another way for
applications to compensate when the values are adjusted by other means,
as an alternative to incremental changes via a script such as
rotationAxis.onValueDelta, onRotationChanged etc.

[ChangeLog][QtQuick][Event Handlers] PinchHandler.activeTranslation now
holds the amount of movement since the pinch gesture began.
PinchHandler.persistentTranslation holds the accumulated sum of
movement that has occurred during subsequent pinch gestures, and can
be set to arbitrary values between gestures. Likewise, activeScale,
persistentScale, activeRotation and persistentRotation follow the
same pattern. The scaleChanged, rotationChanged, and translationChanged
signals include delta arguments, which are useful for incrementally
adjusting a non-default item property when the target is null.

Fixes: QTBUG-76739
Task-number: QTBUG-94168
Change-Id: I6aaa1aa3356b85e6d27abc64bfa67781ecb4f062
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

3 files changed, 35 insertions, 9 deletions

diff --git a/src/quick/doc/snippets/pointerHandlers/images/album-cover.jpg b/src/quick/doc/snippets/pointerHandlers/images/album-cover.jpg
new file mode 100644
index 0000000000..48bd6231ba
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/images/album-cover.jpg
diff --git a/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml b/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml
index f844ce9c98..6884e39e6a 100644
--- a/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml
+++ b/src/quick/doc/snippets/pointerHandlers/pinchHandlerNullTarget.qml
@@ -1,22 +1,31 @@
 // Copyright (C) 2017 The Qt Company Ltd.
 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
 //![0]
-import QtQuick 2.12
+import QtQuick
 
-Item {
-    width: 640
-    height: 480
+Window {
+    width: 320; height: 240
+    visible: true
+    title: handler.persistentRotation.toFixed(1) + "° " +
+           handler.persistentTranslation.x.toFixed(1) + ", " +
+           handler.persistentTranslation.y.toFixed(1) + " " +
+           (handler.persistentScale * 100).toFixed(1) + "%"
 
     PinchHandler {
         id: handler
         target: null
+        persistentScale: 0.25
+        onTranslationChanged: (delta) => {
+            image.x -= delta.x
+            image.y -= delta.y
+        }
     }
 
-    Text {
-        color: handler.active ? "darkgreen" : "black"
-        text: handler.rotation.toFixed(1) + " degrees\n" +
-              handler.translation.x.toFixed(1) + ", " + handler.translation.y.toFixed(1) + "\n" +
-              (handler.scale * 100).toFixed(1) + "%"
+    Image {
+        id: image
+        source: "images/album-cover.jpg"
+        scale: handler.persistentScale
+        x: -600; y: -450
     }
 }
 //![0]
diff --git a/src/quick/doc/snippets/pointerHandlers/pinchHandlerScaleOrRotationChanged.qml b/src/quick/doc/snippets/pointerHandlers/pinchHandlerScaleOrRotationChanged.qml
new file mode 100644
index 0000000000..3baa93eb7c
--- /dev/null
+++ b/src/quick/doc/snippets/pointerHandlers/pinchHandlerScaleOrRotationChanged.qml
@@ -0,0 +1,17 @@
+// Copyright (C) 2022 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+//![0]
+import QtQuick
+
+Rectangle {
+    width: 100; height: 100
+    color: "lightsteelblue"
+
+    PinchHandler {
+        id: handler
+        target: null
+        onRotationChanged: (delta) => parent.rotation += delta // add
+        onScaleChanged: (delta) => parent.scale *= delta // multiply
+    }
+}
+//![0]