Add ScrollBar::snapMode

[ChangeLog][Controls][ScrollBar] Added snapMode property incremental
or discrete scrolling.

Task-number: QTBUG-56569
Change-Id: Id0d463b85063a62b7df6307af8fe8b203155a5de
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

6 files changed, 74 insertions, 4 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-nosnap.gif b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-nosnap.gif
new file mode 100644
index 00000000..f61ac5b4
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-nosnap.gif
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snapalways.gif b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snapalways.gif
new file mode 100644
index 00000000..438d4a33
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snapalways.gif
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snaponrelease.gif b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snaponrelease.gif
new file mode 100644
index 00000000..c2fa67b0
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-scrollbar-snaponrelease.gif
diff --git a/src/imports/templates/qtquicktemplates2plugin.cpp b/src/imports/templates/qtquicktemplates2plugin.cpp
index 1f00a99f..d8dce4c9 100644
--- a/src/imports/templates/qtquicktemplates2plugin.cpp
+++ b/src/imports/templates/qtquicktemplates2plugin.cpp
@@ -230,6 +230,7 @@ void QtQuickTemplates2Plugin::registerTypes(const char *uri)
     qmlRegisterType<QQuickDial, 2>(uri, 2, 2, "Dial");
     qmlRegisterType<QQuickDrawer, 2>(uri, 2, 2, "Drawer");
     qmlRegisterType<QQuickRangeSlider, 2>(uri, 2, 2, "RangeSlider");
+    qmlRegisterType<QQuickScrollBar, 2>(uri, 2, 2, "ScrollBar");
     qmlRegisterType<QQuickSlider, 2>(uri, 2, 2, "Slider");
     qmlRegisterType<QQuickSpinBox, 2>(uri, 2, 2, "SpinBox");
     qmlRegisterType<QQuickSwipeDelegate, 2>(uri, 2, 2, "SwipeDelegate");
diff --git a/src/quicktemplates2/qquickscrollbar.cpp b/src/quicktemplates2/qquickscrollbar.cpp
index a4ed68bf..c862002b 100644
--- a/src/quicktemplates2/qquickscrollbar.cpp
+++ b/src/quicktemplates2/qquickscrollbar.cpp
@@ -158,7 +158,7 @@ class QQuickScrollBarPrivate : public QQuickControlPrivate
 public:
     QQuickScrollBarPrivate() : size(0), position(0), stepSize(0), offset(0),
         active(false), pressed(false), moving(false),
-        orientation(Qt::Vertical)
+        orientation(Qt::Vertical), snapMode(QQuickScrollBar::NoSnap)
     {
     }
 
@@ -167,6 +167,7 @@ public:
         return bar->d_func();
     }
 
+    qreal snapPosition(qreal position) const;
     qreal positionAt(const QPointF &point) const;
     void updateActive();
     void resizeContent() override;
@@ -184,8 +185,18 @@ public:
     bool pressed;
     bool moving;
     Qt::Orientation orientation;
+    QQuickScrollBar::SnapMode snapMode;
 };
 
+qreal QQuickScrollBarPrivate::snapPosition(qreal position) const
+{
+    const qreal effectiveStep = stepSize * (1.0 - size);
+    if (qFuzzyIsNull(effectiveStep))
+        return position;
+
+    return qRound(position / effectiveStep) * effectiveStep;
+}
+
 qreal QQuickScrollBarPrivate::positionAt(const QPointF &point) const
 {
     Q_Q(const QQuickScrollBar);
@@ -228,13 +239,19 @@ void QQuickScrollBarPrivate::handlePress(const QPointF &point)
 void QQuickScrollBarPrivate::handleMove(const QPointF &point)
 {
     Q_Q(QQuickScrollBar);
-    q->setPosition(qBound<qreal>(0.0, positionAt(point) - offset, 1.0 - size));
+    qreal pos = qBound<qreal>(0.0, positionAt(point) - offset, 1.0 - size);
+    if (snapMode == QQuickScrollBar::SnapAlways)
+        pos = snapPosition(pos);
+    q->setPosition(pos);
 }
 
 void QQuickScrollBarPrivate::handleRelease(const QPointF &point)
 {
     Q_Q(QQuickScrollBar);
-    q->setPosition(qBound<qreal>(0.0, positionAt(point) - offset, 1.0 - size));
+    qreal pos = qBound<qreal>(0.0, positionAt(point) - offset, 1.0 - size);
+    if (snapMode != QQuickScrollBar::NoSnap)
+        pos = snapPosition(pos);
+    q->setPosition(pos);
     offset = 0.0;
     q->setPressed(false);
 }
@@ -325,7 +342,7 @@ void QQuickScrollBar::setPosition(qreal position)
 
     This property holds the step size. The default value is \c 0.0.
 
-    \sa increase(), decrease()
+    \sa snapMode, increase(), decrease()
 */
 qreal QQuickScrollBar::stepSize() const
 {
@@ -425,6 +442,46 @@ void QQuickScrollBar::setOrientation(Qt::Orientation orientation)
 }
 
 /*!
+    \since QtQuick.Controls 2.2
+    \qmlproperty enumeration QtQuick.Controls::ScrollBar::snapMode
+
+    This property holds the snap mode.
+
+    Possible values:
+    \value ScrollBar.NoSnap The scrollbar does not snap (default).
+    \value ScrollBar.SnapAlways The scrollbar snaps while dragged.
+    \value ScrollBar.SnapOnRelease The scrollbar does not snap while being dragged, but only after released.
+
+    In the following table, the various modes are illustrated with animations.
+    The movement and the \l stepSize (\c 0.25) are identical in each animation.
+
+    \table
+    \header
+        \row \li \b Value \li \b Example
+        \row \li \c ScrollBar.NoSnap \li \image qtquickcontrols2-scrollbar-nosnap.gif
+        \row \li \c ScrollBar.SnapAlways \li \image qtquickcontrols2-scrollbar-snapalways.gif
+        \row \li \c ScrollBar.SnapOnRelease \li \image qtquickcontrols2-scrollbar-snaponrelease.gif
+    \endtable
+
+    \sa stepSize
+*/
+QQuickScrollBar::SnapMode QQuickScrollBar::snapMode() const
+{
+    Q_D(const QQuickScrollBar);
+    return d->snapMode;
+}
+
+void QQuickScrollBar::setSnapMode(SnapMode mode)
+{
+    Q_D(QQuickScrollBar);
+    if (d->snapMode == mode)
+        return;
+
+    d->snapMode = mode;
+    emit snapModeChanged();
+}
+
+/*!
     \qmlmethod void QtQuick.Controls::ScrollBar::increase()
 
     Increases the position by \l stepSize or \c 0.1 if stepSize is \c 0.0.
diff --git a/src/quicktemplates2/qquickscrollbar_p.h b/src/quicktemplates2/qquickscrollbar_p.h
index 4f90af47..7632e565 100644
--- a/src/quicktemplates2/qquickscrollbar_p.h
+++ b/src/quicktemplates2/qquickscrollbar_p.h
@@ -65,6 +65,7 @@ class Q_QUICKTEMPLATES2_PRIVATE_EXPORT QQuickScrollBar : public QQuickControl
     Q_PROPERTY(bool active READ isActive WRITE setActive NOTIFY activeChanged FINAL)
     Q_PROPERTY(bool pressed READ isPressed WRITE setPressed NOTIFY pressedChanged FINAL)
     Q_PROPERTY(Qt::Orientation orientation READ orientation WRITE setOrientation NOTIFY orientationChanged FINAL)
+    Q_PROPERTY(SnapMode snapMode READ snapMode WRITE setSnapMode NOTIFY snapModeChanged FINAL REVISION 2)
 
 public:
     explicit QQuickScrollBar(QQuickItem *parent = nullptr);
@@ -86,6 +87,16 @@ public:
     Qt::Orientation orientation() const;
     void setOrientation(Qt::Orientation orientation);
 
+    enum SnapMode {
+        NoSnap,
+        SnapAlways,
+        SnapOnRelease
+    };
+    Q_ENUM(SnapMode)
+
+    SnapMode snapMode() const;
+    void setSnapMode(SnapMode mode);
+
 public Q_SLOTS:
     void increase();
     void decrease();
@@ -99,6 +110,7 @@ Q_SIGNALS:
     void activeChanged();
     void pressedChanged();
     void orientationChanged();
+    void snapModeChanged();
 
 protected:
     void mousePressEvent(QMouseEvent *event) override;