Button docs

Change-Id: I387ecb0cac328e99645b92371687cfc3678b5c71
Reviewed-by: Mitch Curtis <mitch.curtis@digia.com>

8 files changed, 79 insertions, 8 deletions

diff --git a/src/controls/doc/images/qtquickcontrols2-button-background.png b/src/controls/doc/images/qtquickcontrols2-button-background.png
new file mode 100644
index 00000000..f8e9342c
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-background.png
diff --git a/src/controls/doc/images/qtquickcontrols2-button-disabled.png b/src/controls/doc/images/qtquickcontrols2-button-disabled.png
new file mode 100644
index 00000000..9b9d1eb3
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-disabled.png
diff --git a/src/controls/doc/images/qtquickcontrols2-button-focused.png b/src/controls/doc/images/qtquickcontrols2-button-focused.png
new file mode 100644
index 00000000..172bf9fe
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-focused.png
diff --git a/src/controls/doc/images/qtquickcontrols2-button-label.png b/src/controls/doc/images/qtquickcontrols2-button-label.png
new file mode 100644
index 00000000..6875fc06
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-label.png
diff --git a/src/controls/doc/images/qtquickcontrols2-button-normal.png b/src/controls/doc/images/qtquickcontrols2-button-normal.png
new file mode 100644
index 00000000..f59669a2
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-normal.png
diff --git a/src/controls/doc/images/qtquickcontrols2-button-pressed.png b/src/controls/doc/images/qtquickcontrols2-button-pressed.png
new file mode 100644
index 00000000..c9b14992
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-button-pressed.png
diff --git a/src/controls/doc/qtquickcontrols2.qdocconf b/src/controls/doc/qtquickcontrols2.qdocconf
index 993493d5..b7a6daf1 100644
--- a/src/controls/doc/qtquickcontrols2.qdocconf
+++ b/src/controls/doc/qtquickcontrols2.qdocconf
@@ -28,7 +28,7 @@ depends = qtcore qtgui qtdoc qtqml qtquick qtquicklayouts qtquickdialogs
 # Specify the install path under QT_INSTALL_EXAMPLES
 # Examples will be installed under quick/controls - 'controls' subdirectory
 # is given as part of \example commands
-exampledirs += ../../../examples/quick/controls
+exampledirs += ../../../examples/quick/controls ../../imports/controls
 examplesinstallpath = quick/controls
 
 headerdirs += ../
diff --git a/src/controls/qquickbutton.cpp b/src/controls/qquickbutton.cpp
index 65d16494..240c4397 100644
--- a/src/controls/qquickbutton.cpp
+++ b/src/controls/qquickbutton.cpp
@@ -47,25 +47,83 @@ QT_BEGIN_NAMESPACE
     \ingroup buttons
     \brief A button control.
 
-    TODO
+    Button presents a push-button control that can be pushed or clicked by
+    the user. Buttons are normally used to perform an action, or to answer
+    a question. Typical buttons are \e OK, \e Apply, \e Cancel, \e Close,
+    \e Yes, \e No and \e Help.
+
+    \table
+    \row \li \image qtquickcontrols2-button-normal.png
+         \li A button in its normal state.
+    \row \li \image qtquickcontrols2-button-pressed.png
+         \li A button that is pressed.
+    \row \li \image qtquickcontrols2-button-focused.png
+         \li A button that has active focus.
+    \row \li \image qtquickcontrols2-button-disabled.png
+         \li A button that is disabled.
+    \endtable
+
+    \code
+    RowLayout {
+        Button {
+            text: "Ok"
+            onClicked: model.submit()
+        }
+        Button {
+            text: "Cancel"
+            onClicked: model.revert()
+        }
+    }
+    \endcode
+
+
+    \section1 Structure
+
+    Button consists of two delegates, \l {Control::background}{background}
+    and \l {Button::label}{label}. The implicit sizes of both delegates are
+    used to calculate the implicit size of the control.
+
+    \section3 Background
+
+    \image qtquickcontrols2-button-background.png
+
+    If the \l {Control::background}{background} delegate has no explicit size
+    specified, it automatically follows the control's size. The following
+    snippet presents the default background delegate implementation.
+
+    \snippet Button.qml background
+
+    \section3 Label
+
+    \image qtquickcontrols2-button-label.png
+
+    If the \l {Button::label}{label} delegate has no explicit size specified,
+    it automatically follows the control's size without padding. The following
+    snippet presents the default label delegate implementation.
+
+    \snippet Button.qml label
+
+    \section1 Theming
+
+    \note ### TODO: Document what is used and how to customize.
 */
 
 /*!
     \qmlsignal QtQuickControls2::Button::pressed()
 
-    TODO
+    This signal is emitted when the button is pressed.
 */
 
 /*!
     \qmlsignal QtQuickControls2::Button::released()
 
-    TODO
+    This signal is emitted when the button is released.
 */
 
 /*!
     \qmlsignal QtQuickControls2::Button::clicked()
 
-    TODO
+    This signal is emitted when the button is clicked.
 */
 
 QQuickButtonPrivate::QQuickButtonPrivate() :
@@ -105,7 +163,12 @@ QQuickButton::QQuickButton(QQuickButtonPrivate &dd, QQuickItem *parent) :
 /*!
     \qmlproperty string QtQuickControls2::Button::text
 
-    TODO
+    This property holds the text shown on the button.
+
+    \note The text is used for accessibility purposes, so it makes sense to
+          set a textual description even if the label delegate is an image.
+
+    \sa label
 */
 QString QQuickButton::text() const
 {
@@ -125,7 +188,7 @@ void QQuickButton::setText(const QString &text)
 /*!
     \qmlproperty bool QtQuickControls2::Button::pressed
 
-    TODO
+    This property holds whether the button is pressed.
 */
 bool QQuickButton::isPressed() const
 {
@@ -149,7 +212,15 @@ void QQuickButton::setPressed(bool isPressed)
 /*!
     \qmlproperty Item QtQuickControls2::Button::label
 
-    TODO
+    This property holds the label delegate.
+
+    If the label delegate has no explicit size specified, it
+    automatically follows the control's size without padding.
+
+    The implicit size of the label delegate is used to calculate
+    the implicit size of the control.
+
+    \sa Structure, text
 */
 QQuickItem *QQuickButton::label() const
 {