Fix axis constraints API and documentation:v5.12.1

This should have been done properly for 5.12.
Since this API was introduced in 5.12.0, we simply hide the
documentation for the old properties and make sure the properties we want
to expose are documented:

* Document the xAxis and yAxis properties.
* Deprecate the {min,max}imum{X,Y} properties, and hide them in the
  documentation.

Fixes: QTBUG-73137
Change-Id: Ic749bcfec63dc4772f193ccae2a2750c20cb63aa
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

3 files changed, 54 insertions, 27 deletions

diff --git a/dist/changes-5.12.1 b/dist/changes-5.12.1
index 36fbdb6a72..39767ade87 100644
--- a/dist/changes-5.12.1
+++ b/dist/changes-5.12.1
@@ -66,6 +66,9 @@ information about a particular change.
  - [QTBUG-71955] TapHandler ignores scroll events and native gestures.
  - [QTBUG-71317] Event Handlers can now be used in Windows and Dialogs.
  - [QTBUG-71427] Event Handlers now function properly when created dynamically.
+ - [QTBUG-73137] The PinchHandler {min,max}imum{X,Y} properties that were
+   unintentionally included in the 5.12.0 release have now been deprecated.
+   Please use the xAxis and yAxis properties instead.
  - [QTBUG-72376] In Text with StyledText textFormat, <s></s> and <del></del>
    tags will now be interpreted as strikethrough style.
  - [QTBUG-59310] Fixed vertical alignment of images in a text document.
diff --git a/src/quick/handlers/qquickpinchhandler.cpp b/src/quick/handlers/qquickpinchhandler.cpp
index e6442e7258..95ac0985f0 100644
--- a/src/quick/handlers/qquickpinchhandler.cpp
+++ b/src/quick/handlers/qquickpinchhandler.cpp
@@ -38,6 +38,7 @@
 ****************************************************************************/
 
 #include "qquickpinchhandler_p.h"
+#include <QtQml/qqmlinfo.h>
 #include <QtQuick/qquickwindow.h>
 #include <private/qsgadaptationlayer_p.h>
 #include <private/qquickitem_p.h>
@@ -151,57 +152,48 @@ void QQuickPinchHandler::setMaximumRotation(qreal maximumRotation)
     emit maximumRotationChanged();
 }
 
-/*!
-    \qmlproperty real QtQuick::PinchHandler::minimumX
+#if QT_DEPRECATED_SINCE(5, 12)
+void QQuickPinchHandler::warnAboutMinMaxDeprecated() const
+{
+    qmlWarning(this) << "min and max constraints are now part of the xAxis and yAxis properties";
+}
 
-    The minimum acceptable x coordinate of the centroid
-*/
 void QQuickPinchHandler::setMinimumX(qreal minX)
 {
+    warnAboutMinMaxDeprecated();
     if (m_minimumX == minX)
         return;
     m_minimumX = minX;
     emit minimumXChanged();
 }
 
-/*!
-    \qmlproperty real QtQuick::PinchHandler::maximumX
-
-    The maximum acceptable x coordinate of the centroid
-*/
 void QQuickPinchHandler::setMaximumX(qreal maxX)
 {
+    warnAboutMinMaxDeprecated();
     if (m_maximumX == maxX)
         return;
     m_maximumX = maxX;
     emit maximumXChanged();
 }
 
-/*!
-    \qmlproperty real QtQuick::PinchHandler::minimumY
-
-    The minimum acceptable y coordinate of the centroid
-*/
 void QQuickPinchHandler::setMinimumY(qreal minY)
 {
+    warnAboutMinMaxDeprecated();
     if (m_minimumY == minY)
         return;
     m_minimumY = minY;
     emit minimumYChanged();
 }
 
-/*!
-    \qmlproperty real QtQuick::PinchHandler::maximumY
-
-    The maximum acceptable y coordinate of the centroid
-*/
 void QQuickPinchHandler::setMaximumY(qreal maxY)
 {
+    warnAboutMinMaxDeprecated();
     if (m_maximumY == maxY)
         return;
     m_maximumY = maxY;
     emit maximumYChanged();
 }
+#endif
 
 bool QQuickPinchHandler::wantsPointerEvent(QQuickPointerEvent *event)
 {
@@ -230,6 +222,32 @@ bool QQuickPinchHandler::wantsPointerEvent(QQuickPointerEvent *event)
 }
 
 /*!
+    \qmlpropertygroup QtQuick::PinchHandler::xAxis
+    \qmlproperty real QtQuick::PinchHandler::xAxis.minimum
+    \qmlproperty real QtQuick::PinchHandler::xAxis.maximum
+    \qmlproperty bool QtQuick::PinchHandler::xAxis.enabled
+
+    \c xAxis controls the constraints for horizontal translation of the \l target item.
+
+    \c minimum is the minimum acceptable x coordinate of the translation.
+    \c maximum is the maximum acceptable x coordinate of the translation.
+    If \c enabled is true, horizontal dragging is allowed.
+ */
+
+/*!
+    \qmlpropertygroup QtQuick::PinchHandler::yAxis
+    \qmlproperty real QtQuick::PinchHandler::yAxis.minimum
+    \qmlproperty real QtQuick::PinchHandler::yAxis.maximum
+    \qmlproperty bool QtQuick::PinchHandler::yAxis.enabled
+
+    \c yAxis controls the constraints for vertical translation of the \l target item.
+
+    \c minimum is the minimum acceptable y coordinate of the translation.
+    \c maximum is the maximum acceptable y coordinate of the translation.
+    If \c enabled is true, vertical dragging is allowed.
+ */
+
+/*!
     \qmlproperty int QtQuick::PinchHandler::minimumTouchPoints
 
     The pinch begins when this number of fingers are pressed.
diff --git a/src/quick/handlers/qquickpinchhandler_p.h b/src/quick/handlers/qquickpinchhandler_p.h
index 8f24d18166..11d895468c 100644
--- a/src/quick/handlers/qquickpinchhandler_p.h
+++ b/src/quick/handlers/qquickpinchhandler_p.h
@@ -70,10 +70,12 @@ class Q_AUTOTEST_EXPORT QQuickPinchHandler : public QQuickMultiPointHandler
     Q_PROPERTY(qreal activeScale READ activeScale NOTIFY updated)
     Q_PROPERTY(qreal rotation READ rotation NOTIFY updated)
     Q_PROPERTY(QVector2D translation READ translation NOTIFY updated)
-    Q_PROPERTY(qreal minimumX READ minimumX WRITE setMinimumX NOTIFY minimumXChanged)
-    Q_PROPERTY(qreal maximumX READ maximumX WRITE setMaximumX NOTIFY maximumXChanged)
-    Q_PROPERTY(qreal minimumY READ minimumY WRITE setMinimumY NOTIFY minimumYChanged)
-    Q_PROPERTY(qreal maximumY READ maximumY WRITE setMaximumY NOTIFY maximumYChanged)
+#if QT_DEPRECATED_SINCE(5, 12)
+    Q_PROPERTY(qreal minimumX READ minimumX WRITE setMinimumX NOTIFY minimumXChanged)   // ### Qt 6: remove
+    Q_PROPERTY(qreal maximumX READ maximumX WRITE setMaximumX NOTIFY maximumXChanged)   // ### Qt 6: remove
+    Q_PROPERTY(qreal minimumY READ minimumY WRITE setMinimumY NOTIFY minimumYChanged)   // ### Qt 6: remove
+    Q_PROPERTY(qreal maximumY READ maximumY WRITE setMaximumY NOTIFY maximumYChanged)   // ### Qt 6: remove
+#endif
     Q_PROPERTY(QQuickDragAxis * xAxis READ xAxis CONSTANT)
     Q_PROPERTY(QQuickDragAxis * yAxis READ yAxis CONSTANT)
 
@@ -96,14 +98,18 @@ public:
     qreal scale() const { return m_accumulatedScale; }
     qreal activeScale() const { return m_activeScale; }
     qreal rotation() const { return m_activeRotation; }
-    qreal minimumX() const { return m_minimumX; }
+
+#if QT_DEPRECATED_SINCE(5, 12)
+    void warnAboutMinMaxDeprecated() const;
+    qreal minimumX() const { warnAboutMinMaxDeprecated(); return m_minimumX; }
     void setMinimumX(qreal minX);
-    qreal maximumX() const { return m_maximumX; }
+    qreal maximumX() const { warnAboutMinMaxDeprecated(); return m_maximumX; }
     void setMaximumX(qreal maxX);
-    qreal minimumY() const { return m_minimumY; }
+    qreal minimumY() const { warnAboutMinMaxDeprecated(); return m_minimumY; }
     void setMinimumY(qreal minY);
-    qreal maximumY() const { return m_maximumY; }
+    qreal maximumY() const { warnAboutMinMaxDeprecated(); return m_maximumY; }
     void setMaximumY(qreal maxY);
+#endif
 
     QQuickDragAxis *xAxis() { return &m_xAxis; }
     QQuickDragAxis *yAxis() { return &m_yAxis; }