Docs: Slider

Change-Id: I9499ab27a74996f43db70ec3ddc49e04b39d2da6
Reviewed-by: J-P Nurmi <jpnurmi@theqtcompany.com>

9 files changed, 104 insertions, 12 deletions

diff --git a/src/controls/doc/images/qtquickcontrols2-slider-background.png b/src/controls/doc/images/qtquickcontrols2-slider-background.png
new file mode 100644
index 00000000..35fb12ca
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-background.png
diff --git a/src/controls/doc/images/qtquickcontrols2-slider-disabled.png b/src/controls/doc/images/qtquickcontrols2-slider-disabled.png
new file mode 100644
index 00000000..7d4584f8
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-disabled.png
diff --git a/src/controls/doc/images/qtquickcontrols2-slider-focused.png b/src/controls/doc/images/qtquickcontrols2-slider-focused.png
new file mode 100644
index 00000000..7f9ad18b
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-focused.png
diff --git a/src/controls/doc/images/qtquickcontrols2-slider-handle.png b/src/controls/doc/images/qtquickcontrols2-slider-handle.png
new file mode 100644
index 00000000..7878e0f8
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-handle.png
diff --git a/src/controls/doc/images/qtquickcontrols2-slider-normal.png b/src/controls/doc/images/qtquickcontrols2-slider-normal.png
new file mode 100644
index 00000000..dac102de
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-normal.png
diff --git a/src/controls/doc/images/qtquickcontrols2-slider-track.png b/src/controls/doc/images/qtquickcontrols2-slider-track.png
new file mode 100644
index 00000000..868fa420
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-slider-track.png
diff --git a/src/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
index 3843531c..7bbd0d71 100644
--- a/src/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -102,6 +102,30 @@
 
     \snippet RadioButton.qml indicator
 
+    \section1 Customizing Slider
+
+    Slider consists of three parts: \l {Control::background}{background},
+    \l {Slider::track}{track} and \l {Slider::handle}{handle}. Their
+    implicit sizes are used to calculate the implicit size of the control.
+
+    \section3 Background
+
+    \image qtquickcontrols2-slider-background.png
+
+    Slider has no background item by default.
+
+    \section3 Track
+
+    \image qtquickcontrols2-slider-track.png
+
+    \snippet Slider.qml track
+
+    \section3 Handle
+
+    \image qtquickcontrols2-slider-handle.png
+
+    \snippet Slider.qml handle
+
     \section1 Customizing Switch
 
     Switch consists of three parts: \l {Control::background}{background},
diff --git a/src/controls/qquickslider.cpp b/src/controls/qquickslider.cpp
index 3f60fc95..5ce3cb92 100644
--- a/src/controls/qquickslider.cpp
+++ b/src/controls/qquickslider.cpp
@@ -49,7 +49,24 @@ QT_BEGIN_NAMESPACE
     \ingroup sliders
     \brief A slider control.
 
-    TODO
+    Slider is used to select a value by sliding a handle along a track.
+
+    \table
+    \row \li \image qtquickcontrols2-slider-normal.png
+         \li A slider in its normal state.
+    \row \li \image qtquickcontrols2-slider-focused.png
+         \li A slider that has active focus.
+    \row \li \image qtquickcontrols2-slider-disabled.png
+         \li A slider that is disabled.
+    \endtable
+
+    \code
+    Slider {
+        value: 0.5
+    }
+    \endcode
+
+    \sa {Customizing Slider}
 */
 
 class QQuickSliderPrivate : public QQuickControlPrivate
@@ -115,7 +132,14 @@ QQuickSlider::QQuickSlider(QQuickItem *parent) :
 /*!
     \qmlproperty real QtQuickControls2::Slider::value
 
-    TODO
+    This property holds the value in the range \c 0.0 - \c 1.0. The default value is \c 0.0.
+
+    The value is defined as a percentage of the control's size, scaled
+    to \c 0.0 - \c 1.0. Unlike the \l position property, the \c value is
+    not updated while the handle is dragged. The value is updated after
+    the value has been chosen and the slider has been released.
+
+    \sa position
 */
 qreal QQuickSlider::value() const
 {
@@ -137,7 +161,14 @@ void QQuickSlider::setValue(qreal value)
 /*!
     \qmlproperty real QtQuickControls2::Slider::position
 
-    TODO
+    This property holds the logical position of the handle.
+
+    The position is defined as a percentage of the control's size, scaled
+    to \c 0.0 - \c 1.0. Unlike the \l value property, the \c position is
+    continuously updated while the handle is dragged. For visualizing a
+    slider, the right-to-left aware \l visualPosition should be used instead.
+
+    \sa value, visualPosition
 */
 qreal QQuickSlider::position() const
 {
@@ -147,8 +178,16 @@ qreal QQuickSlider::position() const
 
 /*!
     \qmlproperty real QtQuickControls2::Slider::visualPosition
+    \readonly
+
+    This property holds the visual position of the handle.
+
+    The position is defined as a percentage of the control's size, scaled to
+    \c 0.0 - \c 1.0. When the control is \l mirrored, the value is equal to
+    \c {1.0 - position}. This makes the value suitable for visualizing the
+    slider, taking right-to-left support into account.
 
-    TODO
+    \sa position
 */
 qreal QQuickSlider::visualPosition() const
 {
@@ -172,7 +211,9 @@ void QQuickSlider::setPosition(qreal position)
 /*!
     \qmlproperty real QtQuickControls2::Slider::stepSize
 
-    TODO
+    This property holds the step size. The default value is \c 0.0.
+
+    \sa snapMode, increase(), decrease()
 */
 qreal QQuickSlider::stepSize() const
 {
@@ -192,7 +233,16 @@ void QQuickSlider::setStepSize(qreal step)
 /*!
     \qmlproperty enumeration QtQuickControls2::Slider::snapMode
 
-    TODO
+    This property holds the snap mode.
+
+    Possible values:
+    \list
+    \li \c Slider.NoSnap (default) - The slider does not snap.
+    \li \c Slider.SnapAlways - The slider snaps while the handle is dragged.
+    \li \c Slider.SnapOnRelease - The slider does not snap while being dragged, but only after the handle is released.
+    \endlist
+
+    \sa stepSize
 */
 QQuickSlider::SnapMode QQuickSlider::snapMode() const
 {
@@ -212,7 +262,7 @@ void QQuickSlider::setSnapMode(SnapMode mode)
 /*!
     \qmlproperty bool QtQuickControls2::Slider::pressed
 
-    TODO
+    This property holds whether the slider is pressed.
 */
 bool QQuickSlider::isPressed() const
 {
@@ -232,7 +282,13 @@ void QQuickSlider::setPressed(bool pressed)
 /*!
     \qmlproperty enumeration QtQuickControls2::Slider::orientation
 
-    TODO
+    This property holds the orientation.
+
+    Possible values:
+    \list
+    \li \c Qt.Horizontal (default)
+    \li \c Qt.Vertical
+    \endlist
 */
 Qt::Orientation QQuickSlider::orientation() const
 {
@@ -252,7 +308,9 @@ void QQuickSlider::setOrientation(Qt::Orientation orientation)
 /*!
     \qmlproperty Item QtQuickControls2::Slider::handle
 
-    TODO
+    This property holds the handle item.
+
+    \sa {Customizing Slider}
 */
 QQuickItem *QQuickSlider::handle() const
 {
@@ -275,7 +333,9 @@ void QQuickSlider::setHandle(QQuickItem *handle)
 /*!
     \qmlproperty Item QtQuickControls2::Slider::track
 
-    TODO
+    This property holds the track item.
+
+    \sa {Customizing Slider}
 */
 QQuickItem *QQuickSlider::track() const
 {
@@ -298,7 +358,9 @@ void QQuickSlider::setTrack(QQuickItem *track)
 /*!
     \qmlmethod void QtQuickControls2::Slider::increase()
 
-    TODO
+    Increases the value by \l stepSize or \c 0.1 if stepSize is not defined.
+
+    \sa stepSize
 */
 void QQuickSlider::increase()
 {
@@ -310,7 +372,9 @@ void QQuickSlider::increase()
 /*!
     \qmlmethod void QtQuickControls2::Slider::decrease()
 
-    TODO
+    Decreases the value by \l stepSize or \c 0.1 if stepSize is not defined.
+
+    \sa stepSize
 */
 void QQuickSlider::decrease()
 {
diff --git a/src/imports/controls/Slider.qml b/src/imports/controls/Slider.qml
index cf9cecd3..79792709 100644
--- a/src/imports/controls/Slider.qml
+++ b/src/imports/controls/Slider.qml
@@ -52,6 +52,7 @@ AbstractSlider {
 
     padding: Theme.padding
 
+    //! [handle]
     handle: Rectangle {
         implicitWidth: 20
         implicitHeight: 20
@@ -76,7 +77,9 @@ AbstractSlider {
                             control.pressed ? control.Theme.pressColor : "transparent")
         }
     }
+    //! [handle]
 
+    //! [track]
     track: Rectangle {
         readonly property bool horizontal: control.orientation === Qt.Horizontal
         implicitWidth: horizontal ? 120 : 6
@@ -101,4 +104,5 @@ AbstractSlider {
             radius: control.Theme.roundness
         }
     }
+    //! [track]
 }