Document where modelReset() is emitted

The resetModel() signal indicates that the model is reset. Previously
there was no note that the signal is emitted also when endResetModel()
is called.

Task-number: QTBUG-23755
Change-Id: I6c3c1ccef580e9c1112c3af79912cffca675e140
Reviewed-by: Robin Burchell <robin+qt@viroteck.net>
Reviewed-by: Stephen Kelly <stephen.kelly@kdab.com>

diff --git a/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp b/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp
index d0de0b8..f35a0c5 100644 (file)
--- a/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp
+++ b/doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp
@@ -86,3 +86,14 @@ beginMoveRows(parent, 2, 2, parent, 0);
 //! [9]
 beginMoveRows(parent, 2, 2, parent, 4);
 //! [9]
+
+//! [10]
+myData.clear();
+reset();
+//! [10]
+
+//! [11]
+beginResetModel();
+myData.clear();
+endResetModel();
+//! [11]

diff --git a/src/corelib/itemmodels/qabstractitemmodel.cpp b/src/corelib/itemmodels/qabstractitemmodel.cpp
index a6446b2..15a8852 100644 (file)
--- a/src/corelib/itemmodels/qabstractitemmodel.cpp
+++ b/src/corelib/itemmodels/qabstractitemmodel.cpp
@@ -2931,9 +2931,20 @@ void QAbstractItemModel::endMoveColumns()
 
     Resets the model to its original state in any attached views.
 
+    This function emits the signals modelAboutToBeReset() and modelReset().
+
     \note Use beginResetModel() and endResetModel() instead whenever possible.
     Use this method only if there is no way to call beginResetModel() before invalidating the model.
     Otherwise it could lead to unexpected behaviour, especially when used with proxy models.
+
+    For example, in this code both signals modelAboutToBeReset() and modelReset()
+    are emitted \e after the data changes:
+
+    \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 10
+
+    Instead you should use:
+
+    \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 11
 */
 
 /*!
@@ -2954,6 +2965,8 @@ void QAbstractItemModel::endMoveColumns()
     You must call this function before resetting any internal data structures in your model
     or proxy model.
 
+    This function emits the signal modelAboutToBeReset().
+
     \sa modelAboutToBeReset(), modelReset(), endResetModel()
     \since 4.6
 */
@@ -2968,6 +2981,8 @@ void QAbstractItemModel::beginResetModel()
     You must call this function after resetting any internal data structure in your model
     or proxy model.
 
+    This function emits the signal modelReset().
+
     \sa beginResetModel()
     \since 4.6
 */
@@ -3452,8 +3467,8 @@ bool QAbstractListModel::dropMimeData(const QMimeData *data, Qt::DropAction acti
     \fn QAbstractItemModel::modelReset()
     \since 4.1
 
-    This signal is emitted when reset() is called, after the model's internal
-    state (e.g. persistent model indexes) has been invalidated.
+    This signal is emitted when reset() or endResetModel() is called, after the
+    model's internal state (e.g. persistent model indexes) has been invalidated.
 
     Note that if a model is reset it should be considered that all information
     previously retrieved from it is invalid. This includes but is not limited