Docs: TextField

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

8 files changed, 69 insertions, 0 deletions

diff --git a/src/controls/doc/images/qtquickcontrols2-textfield-background.png b/src/controls/doc/images/qtquickcontrols2-textfield-background.png
new file mode 100644
index 00000000..a2908200
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-textfield-background.png
diff --git a/src/controls/doc/images/qtquickcontrols2-textfield-disabled.png b/src/controls/doc/images/qtquickcontrols2-textfield-disabled.png
new file mode 100644
index 00000000..bb5b779e
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-textfield-disabled.png
diff --git a/src/controls/doc/images/qtquickcontrols2-textfield-focused.png b/src/controls/doc/images/qtquickcontrols2-textfield-focused.png
new file mode 100644
index 00000000..5d8592c1
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-textfield-focused.png
diff --git a/src/controls/doc/images/qtquickcontrols2-textfield-normal.png b/src/controls/doc/images/qtquickcontrols2-textfield-normal.png
new file mode 100644
index 00000000..26ad9c11
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-textfield-normal.png
diff --git a/src/controls/doc/images/qtquickcontrols2-textfield-placeholder.png b/src/controls/doc/images/qtquickcontrols2-textfield-placeholder.png
new file mode 100644
index 00000000..b040315f
--- /dev/null
+++ b/src/controls/doc/images/qtquickcontrols2-textfield-placeholder.png
diff --git a/src/controls/doc/src/qtquickcontrols2-customize.qdoc b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
index a89c8d69..be6fc368 100644
--- a/src/controls/doc/src/qtquickcontrols2-customize.qdoc
+++ b/src/controls/doc/src/qtquickcontrols2-customize.qdoc
@@ -168,6 +168,24 @@
 
     \snippet Switch.qml indicator
 
+    \section1 Customizing TextField
+
+    TextField consists of two parts: \l {TextField::background}{background}
+    and \l {TextField::placeholder}{placeholder}. Their implicit sizes are
+    used to calculate the implicit size of the control.
+
+    \section3 Background
+
+    \image qtquickcontrols2-textfield-background.png
+
+    \snippet TextField.qml background
+
+    \section3 Placeholder
+
+    \image qtquickcontrols2-textfield-placeholder.png
+
+    \snippet TextField.qml placeholder
+
     \section1 Customizing ToggleButton
 
     ToggleButton consists of three parts: \l {Control::background}{background},
diff --git a/src/controls/qquicktextfield.cpp b/src/controls/qquicktextfield.cpp
index 8c7cb310..ba79fbed 100644
--- a/src/controls/qquicktextfield.cpp
+++ b/src/controls/qquicktextfield.cpp
@@ -42,6 +42,35 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    \qmltype TextField
+    \inherits TextInput
+    \instantiates QQuickTextField
+    \inqmlmodule QtQuick.Controls
+    \ingroup editors
+    \brief A single line text input control.
+
+    TextField is a single line text editor. TextField extends TextInput
+    with a \l placeholder text functionality, and adds decoration.
+
+    \table
+    \row \li \image qtquickcontrols2-textfield-normal.png
+         \li A text field in its normal state.
+    \row \li \image qtquickcontrols2-textfield-focused.png
+         \li A text field that has active focus.
+    \row \li \image qtquickcontrols2-textfield-disabled.png
+         \li A text field that is disabled.
+    \endtable
+
+    \code
+    TextField {
+        placeholder.text: qsTr("Enter name")
+    }
+    \endcode
+
+    \sa TextArea, {Customizing TextField}
+*/
+
 class QQuickTextFieldPrivate
 {
     Q_DECLARE_PUBLIC(QQuickTextField)
@@ -83,6 +112,17 @@ QQuickTextField::~QQuickTextField()
 {
 }
 
+/*!
+    \qmlproperty Item QtQuickControls2::TextField::background
+
+    This property holds the background item.
+
+    \note If the background item has no explicit size specified, it automatically
+          follows the control's size. In most cases, there is no need to specify
+          width or height for a background item.
+
+    \sa {Customizing TextField}
+*/
 QQuickItem *QQuickTextField::background() const
 {
     Q_D(const QQuickTextField);
@@ -106,6 +146,13 @@ void QQuickTextField::setBackground(QQuickItem *background)
     }
 }
 
+/*!
+    \qmlproperty Text QtQuickControls2::TextField::placeholder
+
+    This property holds the placeholder text item.
+
+    \sa {Customizing TextField}
+*/
 QQuickText *QQuickTextField::placeholder() const
 {
     Q_D(const QQuickTextField);
diff --git a/src/imports/controls/TextField.qml b/src/imports/controls/TextField.qml
index 37802184..a4f7c66c 100644
--- a/src/imports/controls/TextField.qml
+++ b/src/imports/controls/TextField.qml
@@ -53,6 +53,7 @@ AbstractTextField {
     selectedTextColor: Theme.selectedTextColor
     verticalAlignment: TextInput.AlignVCenter
 
+    //! [placeholder]
     placeholder: Text {
         x: control.leftPadding
         y: control.topPadding
@@ -63,11 +64,14 @@ AbstractTextField {
         opacity: control.Theme.disabledOpacity
         visible: !control.displayText
     }
+    //! [placeholder]
 
+    //! [background]
     background: Rectangle {
         implicitWidth: 120 // TODO
         radius: control.Theme.roundness
         border.width: control.activeFocus ? 2 : 1
         border.color: control.activeFocus ? control.Theme.focusColor : control.Theme.frameColor
     }
+    //! [background]
 }