From 616c430d2b7f36e70987df7b2dc97e71f0e8b589 Mon Sep 17 00:00:00 2001
From: Mitch Curtis <mitch.curtis@qt.io>
Date: Thu, 2 May 2019 16:50:31 +0200
Subject: ComboBox: document the behavior surrounding the accepted() signal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I65be8e54ded284d2f80b5a1f301b75223bd81bb3
Fixes: QTBUG-75338
Reviewed-by: Henning Gründl <henning.gruendl@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
---
 .../qtquickcontrols2-combobox-accepted.qml         | 45 ++++++++++++++++++++++
 src/quicktemplates2/qquickcombobox.cpp             | 35 ++++++++---------
 2 files changed, 62 insertions(+), 18 deletions(-)
 create mode 100644 src/imports/controls/doc/snippets/qtquickcontrols2-combobox-accepted.qml

diff --git a/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-accepted.qml b/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-accepted.qml
new file mode 100644
index 00000000..9f2ad928
--- /dev/null
+++ b/src/imports/controls/doc/snippets/qtquickcontrols2-combobox-accepted.qml
@@ -0,0 +1,45 @@
+/****************************************************************************
+**
+** Copyright (C) 2019 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 2.12
+import QtQuick.Controls 2.12
+
+//! [combobox]
+ComboBox {
+    editable: true
+    model: ListModel {
+        id: model
+        ListElement { text: "Banana" }
+        ListElement { text: "Apple" }
+        ListElement { text: "Coconut" }
+    }
+    onAccepted: {
+        if (find(editText) === -1)
+            model.append({text: editText})
+    }
+}
+//! [combobox]
diff --git a/src/quicktemplates2/qquickcombobox.cpp b/src/quicktemplates2/qquickcombobox.cpp
index 78ec7ef8..372b7905 100644
--- a/src/quicktemplates2/qquickcombobox.cpp
+++ b/src/quicktemplates2/qquickcombobox.cpp
@@ -90,21 +90,7 @@ QT_BEGIN_NAMESPACE
     The following example demonstrates appending content to an editable
     combo box by reacting to the \l accepted signal.
 
-    \code
-    ComboBox {
-        editable: true
-        model: ListModel {
-            id: model
-            ListElement { text: "Banana" }
-            ListElement { text: "Apple" }
-            ListElement { text: "Coconut" }
-        }
-        onAccepted: {
-            if (find(editText) === -1)
-                model.append({text: editText})
-        }
-    }
-    \endcode
+    \snippet qtquickcontrols2-combobox-accepted.qml combobox
 
     \section1 ComboBox Model Roles
 
@@ -167,9 +153,22 @@ QT_BEGIN_NAMESPACE
     \qmlsignal void QtQuick.Controls::ComboBox::accepted()
 
     This signal is emitted when the \uicontrol Return or \uicontrol Enter key is pressed
-    on an \l editable combo box. If the confirmed string is not currently in the model,
-    the \l currentIndex will be set to \c -1 and the \l currentText will be updated
-    accordingly.
+    on an \l editable combo box.
+
+    You can handle this signal in order to add the newly entered
+    item to the model, for example:
+
+    \snippet qtquickcontrols2-combobox-accepted.qml combobox
+
+    Before the signal is emitted, a check is done to see if the string
+    exists in the model. If it does, \l currentIndex will be set to its index,
+    and \l currentText to the string itself.
+
+    After the signal has been emitted, and if the first check failed (that is,
+    the item did not exist), another check will be done to see if the item was
+    added by the signal handler. If it was, the \l currentIndex and
+    \l currentText are updated accordingly. Otherwise, they will be set to
+    \c -1 and \c "", respectively.
 
     \note If there is a \l validator set on the combo box, the signal will only be
           emitted if the input is in an acceptable state.
-- 
cgit v1.2.3