Enhance the documentation about changing model data from QML

Since 4253f11774ed113cfc69794435e7e66b373bc2cd (5.6),
write access to QQmlListModel model properties is implemented.

QAbstractItemModel derived models seem to have implemented
setData invocation on model property writes since 5.0.

However this was never mentioned in the documentation, so it
has been a rather unknown but very useful feature.

Task-number: QTBUG-32064
Change-Id: I0424bd440480166f1c36ce9fbad2c36a0e73f08e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

2 files changed, 80 insertions, 28 deletions

diff --git a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
index e8265b92d2..a849a30b4e 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/cppmodels.qdoc
@@ -233,34 +233,10 @@ contact details from an SQLite database.
 
 \section3 Editable Data Model
 
-Besides the \c roleNames() and \c data(), the editable models must reimplement
-the \l{QSqlTableModel::}{setData} method to save changes to existing SQL data.
-The following version of the method checks if the given model index is valid
-and the \c role is equal to \l Qt::EditRole, before calling the parent class
-version:
-
-\code
-bool SqlEditableModel::setData(const QModelIndex &item, const QVariant &value, int role)
-{
-    if (item.isValid() && role == Qt::EditRole) {
-        QSqlTableModel::setData(item, value,role);
-        emit dataChanged(item, item);
-        return true;
-    }
-    return false;
+QSqlTableModel implements setData() as described \l{#changing-model-data}{below}.
 
-}
-\endcode
-
-\note It is important to emit the \l{QAbstractItemModel::}{dataChanged}()
-signal after saving the changes.
-
-Unlike the C++ item views such as QListView or QTableView, the \c setData()
-method must be explicitly invoked from QML whenever appropriate. For example,
-on the \l[QML]{TextField::}{editingFinished}() or \l[QML]{TextField::}{accepted}()
-signal of \l[QtQuickControls]{TextField}. Depending on the
-\l{QSqlTableModel::}{EditStrategy} used by the model, the changes are either
-queued for submission later or submitted immediately.
+Depending on the \l{QSqlTableModel::}{EditStrategy} used by the model, the
+changes are either queued for submission later or submitted immediately.
 
 You can also insert new data into the model by calling
 \l {QSqlTableModel::insertRecord}(). In the following example snippet,
@@ -327,5 +303,51 @@ ListView {
 See \l {Writing QML Extensions with C++} for details on writing QML C++
 plugins.
 
+\section2 Changing Model Data
+
+Besides the \c roleNames() and \c data(), editable models must reimplement
+the \l{QAbstractItemModel::}{setData} method to save changes to existing model data.
+The following version of the method checks if the given model index is valid
+and the \c role is equal to \l Qt::EditRole:
+
+\code
+bool EditableModel::setData(const QModelIndex &index, const QVariant &value, int role)
+{
+    if (index.isValid() && role == Qt::EditRole) {
+        // Set data in model here. It can also be a good idea to check whether
+        // the new value actually differs from the current value
+        if (m_entries[index.row()] != value.toString()) {
+            m_entries[index.row()] = value.toString();
+            emit dataChanged(index, index, { Qt::EditRole, Qt::DisplayRole });
+            return true;
+        }
+    }
+    return false;
+}
+\endcode
+
+\note It is important to emit the \l{QAbstractItemModel::}{dataChanged}()
+signal after saving the changes.
+
+Unlike the C++ item views such as QListView or QTableView, the \c setData()
+method must be explicitly invoked from QML delegates whenever appropriate. This is done
+by simply assigning a new value to the corresponding model property. For example,
+on the \l[QML]{TextField::}{editingFinished}() or \l[QML]{TextField::}{accepted}()
+signal of \l[QtQuickControls]{TextField}.
+
+\qml
+ListView {
+    anchors.fill: parent
+    model: EditableModel {}
+    delegate: TextField {
+        width: ListView.view.width
+        text: model.edit
+        onAccepted: model.edit = text
+    }
+}
+\endqml
+
+\note The \c edit role is equal to \l Qt::EditRole. See \l{QAbstractItemModel::}{roleNames}()
+for the built-in role names. However, real life models would usually register custom roles.
 
 */
diff --git a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
index 89b7929755..0c6aaecf42 100644
--- a/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
+++ b/src/quick/doc/src/concepts/modelviewsdata/modelview.qdoc
@@ -46,7 +46,8 @@ types for creating models.
 display the data in a list or a grid.
 \li \b Delegate - dictates how the data should appear in the view.
 The delegate takes each data in the model and encapsulates it. The data is
-accessible through the delegate.
+accessible through the delegate. The delegate can also write data
+back into editable models (e.g. in a TextField's onAccepted Handler).
 \endlist
 
 To visualize data, bind the view's \c model property to a model and the
@@ -390,6 +391,35 @@ If the model is a string list, the delegate is also exposed to a read-only
 It is also possible to use a delegate as the template for the items created
 by a Repeater. This is specified using the \l{Repeater::}{delegate} property.
 
+\section1 Changing Model Data
+
+To change model data, you can assign updated values to the \c model properties.
+The QML ListModel is editable by default whereas C++ models must implement
+setData() to become editable. Integer and JavaScript array models are read-only.
+
+Supposed a \l{QAbstractItemModel} based C++ model that implements the
+\l{QAbstractItemModel::}{setData} method is registered as a QML type named
+\c EditableModel. Data could then be written to the model like this:
+
+\qml
+ListView {
+    anchors.fill: parent
+    model: EditableModel {}
+    delegate: TextEdit {
+        width: ListView.view.width
+        height: 30
+        text: model.edit
+        Keys.onReturnPressed: model.edit = text
+    }
+}
+\endqml
+
+\note The \c edit role is equal to \l Qt::EditRole. See \l{QAbstractItemModel::}{roleNames}()
+for the built-in role names. However, real life models would usually register custom roles.
+
+For more information, visit the \l{qtquick-modelviewsdata-cppmodels.html#changing-model-data}{Using C++ Models with Qt Quick Views}
+article.
+
 \section1 Using Transitions
 
 Transitions can be used to animate items that are added to, moved within,