Add diagrams for illustrating the process of moving rows.

1 files changed, 56 insertions, 0 deletions

diff --git a/src/corelib/kernel/qabstractitemmodel.cpp b/src/corelib/kernel/qabstractitemmodel.cpp
index b0503be..3660a3c 100644
--- a/src/corelib/kernel/qabstractitemmodel.cpp
+++ b/src/corelib/kernel/qabstractitemmodel.cpp
@@ -2530,6 +2530,62 @@ bool QAbstractItemModelPrivate::allowMove(const QModelIndex &srcParent, int star
     condition is true, in which case you should abort your move
     operation.
 
+    \table 80%
+    \row
+        \o  \inlineimage modelview-move-rows-1.png Moving rows to another parent
+        \o  Specify the first and last row numbers for the span of rows in
+            the source parent you want to move in the model. Also specify
+            the row in the destination parent to move the span to.
+
+            For example, as shown in the diagram, we move three rows from
+            row 2 to 4 in the source, so \a sourceFirst is 2 and \a sourceLast is 4.
+            We move those items to above row 2 in the destination, so \a destinationRow is 2.
+
+            \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 6
+
+            This moves the three rows rows 2, 3, and 4 in the source to become 2, 3 and 4 in
+            the destination. Other affected siblings are displaced accordingly.
+    \row
+        \o  \inlineimage modelview-move-rows-2.png Moving rows to append to another parent
+        \o  To append rows to another parent, move them to after the last row.
+
+            For example, as shown in the diagram, we move three rows to a
+            collection of 6 existing rows (ending in row 5), so \a destinationStart is 6:
+
+            \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 7
+
+            This moves the target rows to the end of the target parent as 6, 7 and 8.
+    \row
+        \o  \inlineimage modelview-move-rows-3.png Moving rows in the same parent up
+        \o  To move rows within the same parent, specify the row to move them to.
+
+            For example, as shown in the diagram, we move one item from row 2 to row 0,
+            so \a sourceFirst and \a sourceLast are 2 and \a destinationChild is 0.
+
+            \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 8
+
+            Note that other rows may be displaced accordingly. Note also that when moving
+            items within the same parent you should not attempt invalid or no-op moves. In
+            the above example, item 2 is at row 2 before the move, so it can not be moved
+            to row 2 (where it is already) or row 3 (no-op as row 3 means above row 3, where
+            it is already)
+
+    \row
+        \o  \inlineimage modelview-move-rows-4.png Moving rows in the same parent down
+        \o  To move rows within the same parent, specify the row to move them to.
+
+            For example, as shown in the diagram, we move one item from row 2 to row 4,
+            so \a sourceFirst and \a sourceLast are 2 and \a destinationChild is 4.
+
+            \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 9
+
+            Note that other rows may be displaced accordingly.
+    \endtable
+
+    \note This function emits the rowsAboutToBeInserted() signal which
+    connected views (or proxies) must handle before the data is inserted.
+    Otherwise, the views may end up in an invalid state.
+
     \sa endMoveRows()
 
     \since 4.6