Doc: some ComboBox functions must be used after component completion

The internal QQmlDelegate model may not be ready until after
componentComplete() is called. For example, the following code will
print -1 for the find call, even though printing the model will
show the "Hello" entry:

    ComboBox {
        id: comboBug
        anchors.centerIn: parent
        model: ["123", "BlaBla", "Hello", "Turtle"]
        currentIndex: {
            console.log("Model: " + comboBug.model)
            console.log("Find:  " + comboBug.find("Hello"))
            return comboBug.find("Hello")
        }
    }

Fixes: QTBUG-94257
Change-Id: I6e8c2a4eb8ca7ffca0a38d2f2e914cf791d3bd2e
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 332011c8e6a96cd2b0c685b72f96337660f690e0)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 96 insertions, 0 deletions

diff --git a/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-find.qml b/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-find.qml
new file mode 100644
index 00000000..c14ebbbe
--- /dev/null
+++ b/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-find.qml
@@ -0,0 +1,40 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick
+import QtQuick.Controls
+
+//! [find]
+ComboBox {
+    model: ListModel {
+        ListElement { text: "Banana" }
+        ListElement { text: "Apple" }
+        ListElement { text: "Coconut" }
+    }
+    Component.onCompleted: currentIndex = find("Coconut")
+}
+//! [find]
diff --git a/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-textat.qml b/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-textat.qml
new file mode 100644
index 00000000..524886d0
--- /dev/null
+++ b/src/quickcontrols2/doc/snippets/qtquickcontrols2-combobox-textat.qml
@@ -0,0 +1,40 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+import QtQuick
+import QtQuick.Controls
+
+//! [textat]
+ComboBox {
+    model: ListModel {
+        ListElement { text: "Banana" }
+        ListElement { text: "Apple" }
+        ListElement { text: "Coconut" }
+    }
+    onActivated: (index) => { print(textAt(index)) }
+}
+//! [textat]
diff --git a/src/quickcontrols2/doc/src/includes/qquickcombobox.qdocinc b/src/quickcontrols2/doc/src/includes/qquickcombobox.qdocinc
new file mode 100644
index 00000000..5e19f5f1
--- /dev/null
+++ b/src/quickcontrols2/doc/src/includes/qquickcombobox.qdocinc
@@ -0,0 +1,6 @@
+//! [functions-after-component-completion]
+
+\note This function can only be used after
+\l {Component::completed()}{Component.completed()} is emitted for the ComboBox.
+
+//! [functions-after-component-completion]
diff --git a/src/quicktemplates2/qquickcombobox.cpp b/src/quicktemplates2/qquickcombobox.cpp
index 7832e147..3a966f73 100644
--- a/src/quicktemplates2/qquickcombobox.cpp
+++ b/src/quicktemplates2/qquickcombobox.cpp
@@ -1681,6 +1681,8 @@ QVariant QQuickComboBox::valueAt(int index) const
 
     For an example of how to use this method, see \l {ComboBox Model Roles}.
 
+    \include qquickcombobox.qdocinc functions-after-component-completion
+
     \sa find(), currentValue, currentIndex, valueRole
 */
 int QQuickComboBox::indexOfValue(const QVariant &value) const
@@ -1794,6 +1796,10 @@ void QQuickComboBox::setImplicitContentWidthPolicy(QQuickComboBox::ImplicitConte
     Returns the text for the specified \a index, or an empty string
     if the index is out of bounds.
 
+    \include qquickcombobox.qdocinc functions-after-component-completion
+    For example:
+    \snippet qtquickcontrols2-combobox-textat.qml textat
+
     \sa textRole
 */
 QString QQuickComboBox::textAt(int index) const
@@ -1823,6 +1829,10 @@ QString QQuickComboBox::textAt(int index) const
     \value Qt.MatchContains          The search term is contained in the item.
     \value Qt.MatchCaseSensitive     The search is case sensitive.
 
+    \include qquickcombobox.qdocinc functions-after-component-completion
+    For example:
+    \snippet qtquickcontrols2-combobox-find.qml find
+
     \sa textRole
 */
 int QQuickComboBox::find(const QString &text, Qt::MatchFlags flags) const