Docs: Switch

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

10 files changed, 72 insertions, 3 deletions

diff --git a/src/controls/doc/images/qtquickcontrols2-switch-background.png b/src/controls/doc/images/qtquickcontrols2-switch-background.png
new file mode 100644
index 00000000..bfa24fe6
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-background.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-checked.png b/src/controls/doc/images/qtquickcontrols2-switch-checked.png
new file mode 100644
index 00000000..fadf851a
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-checked.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-disabled.png b/src/controls/doc/images/qtquickcontrols2-switch-disabled.png
new file mode 100644
index 00000000..328ff6a9
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-disabled.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-focused.png b/src/controls/doc/images/qtquickcontrols2-switch-focused.png
new file mode 100644
index 00000000..795868b8
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-focused.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-indicator.png b/src/controls/doc/images/qtquickcontrols2-switch-indicator.png
new file mode 100644
index 00000000..5fc9c83b
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-indicator.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-label.png b/src/controls/doc/images/qtquickcontrols2-switch-label.png
new file mode 100644
index 00000000..57deabc6
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-label.png
diff --git a/src/controls/doc/images/qtquickcontrols2-switch-normal.png b/src/controls/doc/images/qtquickcontrols2-switch-normal.png
new file mode 100644
index 00000000..a162e898
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-switch-normal.png
diff --git a/src/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
index 6e4827a1..8b02a62b 100644
--- a/src/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -101,4 +101,28 @@
     \image qtquickcontrols2-radiobutton-indicator.png
 
     \snippet RadioButton.qml indicator
+
+    \section1 Customizing Switch
+
+    Switch consists of three parts: \l {Control::background}{background},
+    \l {Button::label}{label} and \l {Checkable::indicator}{indicator}. Their
+    implicit sizes are used to calculate the implicit size of the control.
+
+    \section3 Background
+
+    \image qtquickcontrols2-switch-background.png
+
+    Switch has no background item by default.
+
+    \section3 Label
+
+    \image qtquickcontrols2-switch-label.png
+
+    \snippet Switch.qml label
+
+    \section3 Indicator
+
+    \image qtquickcontrols2-switch-indicator.png
+
+    \snippet Switch.qml indicator
 */
diff --git a/src/controls/qquickswitch.cpp b/src/controls/qquickswitch.cpp
index 8f970c9b..7f6d3ebd 100644
--- a/src/controls/qquickswitch.cpp
+++ b/src/controls/qquickswitch.cpp
@@ -49,7 +49,32 @@ QT_BEGIN_NAMESPACE
     \ingroup buttons
     \brief A switch control.
 
-    TODO
+    Switch is an option button that can be dragged or toggled on (checked) or
+    off (unchecked). Switches are typically used to select between two states.
+
+    \table
+    \row \li \image qtquickcontrols2-switch-normal.png
+         \li A switch in its normal state.
+    \row \li \image qtquickcontrols2-switch-checked.png
+         \li A switch that is checked.
+    \row \li \image qtquickcontrols2-switch-focused.png
+         \li A switch that has active focus.
+    \row \li \image qtquickcontrols2-switch-disabled.png
+         \li A switch that is disabled.
+    \endtable
+
+    \code
+    ColumnLayout {
+        Switch {
+            text: qsTr("Wi-Fi")
+        }
+        Switch {
+            text: qsTr("Bluetooth")
+        }
+    }
+    \endcode
+
+    \sa {Customizing Switch}
 */
 
 class QQuickSwitchPrivate : public QQuickCheckablePrivate
@@ -81,7 +106,14 @@ QQuickSwitch::QQuickSwitch(QQuickItem *parent) :
 /*!
     \qmlproperty real QtQuickControls2::Switch::position
 
-    TODO
+    This property holds the logical position of the thumb indicator.
+
+    The position is defined as a percentage of the control's size, scaled to
+    \c 0.0 - \c 1.0. The position can be used for example to determine whether
+    the thumb has been dragged past the halfway. For visualizing a thumb
+    indicator, the right-to-left aware \l visualPosition should be used instead.
+
+    \sa visualPosition
 */
 qreal QQuickSwitch::position() const
 {
@@ -103,7 +135,16 @@ void QQuickSwitch::setPosition(qreal position)
 /*!
     \qmlproperty real QtQuickControls2::Switch::visualPosition
 
-    TODO
+    This property holds the visual position of the thumb indicator.
+
+    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
+    thumb indicator taking right-to-left support into account. In order to
+    for example determine whether the thumb has been dragged past the halfway,
+    the logical \l position should be used instead.
+
+    \sa position
 */
 qreal QQuickSwitch::visualPosition() const
 {
diff --git a/src/imports/controls/Switch.qml b/src/imports/controls/Switch.qml
index 97c1bd5c..c1661f35 100644
--- a/src/imports/controls/Switch.qml
+++ b/src/imports/controls/Switch.qml
@@ -56,6 +56,7 @@ AbstractSwitch {
 
     padding: Theme.padding
 
+    //! [indicator]
     indicator: Rectangle {
         implicitWidth: 36
         implicitHeight: 20
@@ -89,7 +90,9 @@ AbstractSwitch {
             }
         }
     }
+    //! [indicator]
 
+    //! [label]
     label: Text {
         x: control.mirrored ? control.leftPadding : (indicator.x + indicator.width + control.Theme.spacing)
         y: control.topPadding
@@ -103,4 +106,5 @@ AbstractSwitch {
         horizontalAlignment: Text.AlignLeft
         verticalAlignment: Text.AlignVCenter
     }
+    //! [label]
 }