ComboBox: fix documentation review findings

Change-Id: Iba9bdd74ab5b9865a2314ccc460fa44b9ea35be5
Task-number: QTBUG-55904
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

6 files changed, 153 insertions, 8 deletions

diff --git a/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif b/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif
new file mode 100644
index 00000000..966a2d4a
--- /dev/null
+++ b/src/imports/controls/doc/images/qtquickcontrols2-combobox.gif
diff --git a/src/imports/controls/doc/images/qtquickcontrols2-combobox.png b/src/imports/controls/doc/images/qtquickcontrols2-combobox.png
deleted file mode 100644
index e687fb0e..00000000
--- a/src/imports/controls/doc/images/qtquickcontrols2-combobox.png
+++ /dev/null
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
index c3583fd1..ce7b6aa4 100644
--- a/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
+++ b/src/imports/controls/doc/src/qtquickcontrols2-input.qdoc
@@ -42,7 +42,7 @@
 
     \section1 ComboBox Control
 
-    \image qtquickcontrols2-combobox.png
+    \image qtquickcontrols2-combobox.gif
 
     \l ComboBox is used to select a value from a static multiple-line drop-down list.
     It is not possible to add new values, and only one option can be selected.
diff --git a/src/quicktemplates2/qquickcombobox.cpp b/src/quicktemplates2/qquickcombobox.cpp
index 278f8608..52ee2b49 100644
--- a/src/quicktemplates2/qquickcombobox.cpp
+++ b/src/quicktemplates2/qquickcombobox.cpp
@@ -58,15 +58,15 @@ QT_BEGIN_NAMESPACE
     \ingroup qtquickcontrols2-input
     \brief A combined button and popup list taking minimal space.
 
-    \image qtquickcontrols2-combobox.png
+    \image qtquickcontrols2-combobox.gif
 
     ComboBox is a combined button and popup list. It provides a means of
     presenting a list of options to the user in a way that takes up the
     minimum amount of screen space.
 
     ComboBox is populated with a data model. The data model is commonly
-    a JavaScript array, a \l ListModel or an integer, but also other types
-    of \l {qml-data-models}{data models} are supported.
+    a JavaScript array, a \l ListModel or an integer, but other types
+    of \l {qml-data-models}{data models} are also supported.
 
     \code
     ComboBox {
@@ -74,6 +74,8 @@ QT_BEGIN_NAMESPACE
     }
     \endcode
 
+    \section1 ComboBox Model Roles
+
     ComboBox is able to visualize standard \l {qml-data-models}{data models}
     that provide the \c modelData role:
     \list
@@ -108,6 +110,12 @@ QT_BEGIN_NAMESPACE
 
     This signal is emitted when the item at \a index is activated by the user.
 
+    An item is activated when it is selected while the popup is open,
+    causing the popup to close (and \l currentIndex to change),
+    or while the popup is closed and the combo box is navigated via
+    keyboard, causing the \l currentIndex to change.
+    The \l currentIndex property is set to \a index.
+
     \sa currentIndex
 */
 
@@ -116,6 +124,9 @@ QT_BEGIN_NAMESPACE
 
     This signal is emitted when the item at \a index in the popup list is highlighted by the user.
 
+    The highlighted signal is only emitted when the popup is open and an item
+    is highlighted, but not necessarily \l activated.
+
     \sa highlightedIndex
 */
 
@@ -468,6 +479,10 @@ void QQuickComboBox::setPressed(bool pressed)
 
     This property holds the index of the highlighted item in the combo box popup list.
 
+    When a highlighted item is activated, the popup is closed, \l currentIndex
+    is set to \c highlightedIndex, and the value of this property is reset to
+    \c -1, as there is no longer a highlighted item.
+
     \sa highlighted(), currentIndex
 */
 int QQuickComboBox::highlightedIndex() const
@@ -481,7 +496,7 @@ int QQuickComboBox::highlightedIndex() const
 
     This property holds the index of the current item in the combo box.
 
-    \sa activated(), currentText
+    \sa activated(), currentText, highlightedIndex
 */
 int QQuickComboBox::currentIndex() const
 {
@@ -567,7 +582,10 @@ void QQuickComboBox::resetDisplayText()
 
     This property holds the model role used for populating the combo box.
 
-    \sa model, currentText, displayText
+    When the model has multiple roles, \c textRole can be set to determine
+    which role should be displayed.
+
+    \sa model, currentText, displayText, {ComboBox Model Roles}
 */
 QString QQuickComboBox::textRole() const
 {
@@ -592,6 +610,22 @@ void QQuickComboBox::setTextRole(const QString &role)
 
     This property holds a delegate that presents an item in the combo box popup.
 
+    It is recommended to use \l ItemDelegate (or any other \l AbstractButton
+    derivatives) as the delegate. This ensures that the interaction works as
+    expected, and the popup will automatically close when appropriate. When
+    other types are used as the delegate, the popup must be closed manually.
+    For example, if \l MouseArea is used:
+
+    \code
+    delegate: Rectangle {
+        // ...
+        MouseArea {
+            // ...
+            onClicked: comboBox.popup.close()
+        }
+    }
+    \endcode
+
     \sa ItemDelegate, {Customizing ComboBox}
 */
 QQmlComponent *QQuickComboBox::delegate() const
@@ -618,6 +652,8 @@ void QQuickComboBox::setDelegate(QQmlComponent* delegate)
     \qmlproperty Item QtQuick.Controls::ComboBox::indicator
 
     This property holds the drop indicator item.
+
+    \sa {Customizing ComboBox}
 */
 QQuickItem *QQuickComboBox::indicator() const
 {
@@ -645,6 +681,12 @@ void QQuickComboBox::setIndicator(QQuickItem *indicator)
 
     This property holds the popup.
 
+    The popup can be opened or closed manually, if necessary:
+
+    \code
+    onSpecialEvent: comboBox.popup.close()
+    \endcode
+
     \sa {Customizing ComboBox}
 */
 QQuickPopup *QQuickComboBox::popup() const
@@ -761,7 +803,7 @@ int QQuickComboBox::find(const QString &text, Qt::MatchFlags flags) const
     \qmlmethod void QtQuick.Controls::ComboBox::incrementCurrentIndex()
 
     Increments the current index of the combo box, or the highlighted
-    index if the popup list when it is visible.
+    index if the popup list is visible.
 
     \sa currentIndex, highlightedIndex
 */
@@ -775,7 +817,7 @@ void QQuickComboBox::incrementCurrentIndex()
     \qmlmethod void QtQuick.Controls::ComboBox::decrementCurrentIndex()
 
     Decrements the current index of the combo box, or the highlighted
-    index if the popup list when it is visible.
+    index if the popup list is visible.
 
     \sa currentIndex, highlightedIndex
 */
diff --git a/tests/manual/gifs/data/qtquickcontrols2-combobox.qml b/tests/manual/gifs/data/qtquickcontrols2-combobox.qml
new file mode 100644
index 00000000..718ed166
--- /dev/null
+++ b/tests/manual/gifs/data/qtquickcontrols2-combobox.qml
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** You may use this file under the terms of the BSD license as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick 2.6
+import QtQuick.Controls 2.0
+import QtQuick.Layouts 1.1
+import QtQuick.Window 2.0
+
+Window {
+    width: 140
+    height: 180
+    visible: true
+
+    property alias comboBox: comboBox
+
+    ComboBox {
+        id: comboBox
+        model: ["First", "Second", "Third"]
+        y: 10
+        anchors.horizontalCenter: parent.horizontalCenter
+    }
+}
diff --git a/tests/manual/gifs/tst_gifs.cpp b/tests/manual/gifs/tst_gifs.cpp
index b64d3573..a147a45d 100644
--- a/tests/manual/gifs/tst_gifs.cpp
+++ b/tests/manual/gifs/tst_gifs.cpp
@@ -75,6 +75,7 @@ private slots:
     void triState();
     void checkables_data();
     void checkables();
+    void comboBox();
 
 private:
     void moveSmoothly(QQuickWindow *window, const QPoint &from, const QPoint &to, int movements,
@@ -707,6 +708,49 @@ void tst_Gifs::checkables()
     gifRecorder.waitForFinish();
 }
 
+void tst_Gifs::comboBox()
+{
+    GifRecorder gifRecorder;
+    gifRecorder.setDataDirPath(dataDirPath);
+    gifRecorder.setOutputDir(outputDir);
+    gifRecorder.setRecordingDuration(6);
+    gifRecorder.setQmlFileName(QStringLiteral("qtquickcontrols2-combobox.qml"));
+
+    gifRecorder.start();
+
+    QQuickWindow *window = gifRecorder.window();
+    QQuickItem *comboBox = window->property("comboBox").value<QQuickItem*>();
+    QVERIFY(comboBox);
+
+    // Open the popup.
+    const QPoint center = comboBox->mapToScene(
+        QPoint(comboBox->width() / 2, comboBox->height() / 2)).toPoint();
+    QTest::mousePress(window, Qt::LeftButton, Qt::NoModifier, center, 800);
+    QTest::mouseRelease(window, Qt::LeftButton, Qt::NoModifier, center, 80);
+
+    // Select the third item.
+    QObject *popup = comboBox->property("popup").value<QObject*>();
+    QVERIFY(popup);
+    QQuickItem *popupContent = popup->property("contentItem").value<QQuickItem*>();
+    QVERIFY(popupContent);
+    const QPoint lastItemPos = popupContent->mapToScene(
+        QPoint(popupContent->width() / 2, popupContent->height() * 0.8)).toPoint();
+    QTest::mousePress(window, Qt::LeftButton, Qt::NoModifier, lastItemPos, 600);
+    QTest::mouseRelease(window, Qt::LeftButton, Qt::NoModifier, lastItemPos, 200);
+
+    // Open the popup.
+    QTest::mousePress(window, Qt::LeftButton, Qt::NoModifier, center, 1500);
+    QTest::mouseRelease(window, Qt::LeftButton, Qt::NoModifier, center, 80);
+
+    // Select the first item.
+    const QPoint firstItemPos = popupContent->mapToScene(
+        QPoint(popupContent->width() / 2, popupContent->height() * 0.2)).toPoint();
+    QTest::mousePress(window, Qt::LeftButton, Qt::NoModifier, firstItemPos, 600);
+    QTest::mouseRelease(window, Qt::LeftButton, Qt::NoModifier, firstItemPos, 200);
+
+    gifRecorder.waitForFinish();
+}
+
 void tst_Gifs::triState_data()
 {
     QTest::addColumn<QString>("name");