Doc: QAbstractItemModel: note unexpected behavior with beginMoveRows

The meaning of the destinationChild parameter differs when moving
down in the same parent, contrary to statements by the previous docs.

Reviewed-by: Olivier Goffart
Merge-Request: 600

1 files changed, 52 insertions, 40 deletions

diff --git a/src/corelib/kernel/qabstractitemmodel.cpp b/src/corelib/kernel/qabstractitemmodel.cpp
index 24c26b6223..b0e2f48dc3 100644
--- a/src/corelib/kernel/qabstractitemmodel.cpp
+++ b/src/corelib/kernel/qabstractitemmodel.cpp
@@ -2508,29 +2508,35 @@ bool QAbstractItemModelPrivate::allowMove(const QModelIndex &srcParent, int star
     When reimplementing a subclass, this method simplifies moving
     entities in your model. This method is responsible for moving
     persistent indexes in the model, which you would otherwise be
-    required to do yourself.
-
-    Using beginMoveRows and endMoveRows is an alternative to emitting
-    layoutAboutToBeChanged and layoutChanged directly along with
-    changePersistentIndexes.  layoutAboutToBeChanged is emitted by
-    this method for compatibility reasons.
+    required to do yourself. Using beginMoveRows and endMoveRows
+    is an alternative to emitting layoutAboutToBeChanged and
+    layoutChanged directly along with changePersistentIndexes.
+    layoutAboutToBeChanged is emitted by this method for compatibility
+    reasons.
 
     The \a sourceParent index corresponds to the parent from which the
-    rows are moved; \a sourceFirst and \a sourceLast are the row
-    numbers of the rows to be moved. The \a destinationParent index
-    corresponds to the parent into which the rows are moved. The \a
+    rows are moved; \a sourceFirst and \a sourceLast are the first and last
+    row numbers of the rows to be moved. The \a destinationParent index
+    corresponds to the parent into which those rows are moved. The \a
     destinationChild is the row to which the rows will be moved.  That
     is, the index at row \a sourceFirst in \a sourceParent will become
-    row \a destinationChild in \a destinationParent. Its siblings will
-    be moved correspondingly.
-
-    Note that \a sourceParent and \a destinationParent may be the
-    same, in which case you must ensure that the \a destinationChild is
-    not within the range of \a sourceFirst and \a sourceLast.  You
-    must also ensure that you do not attempt to move a row to one of
-    its own children or ancestors.  This method returns false if either
-    condition is true, in which case you should abort your move
-    operation.
+    row \a destinationChild in \a destinationParent, followed by all other
+    rows up to \a sourceLast.
+
+    However, when moving rows down in the same parent (\a sourceParent
+    and \a destinationParent are equal), the rows will be placed before the
+    \a destinationChild index. That is, if you wish to move rows 0 and 1 so
+    they will become rows 1 and 2, \a destinationChild should be 3. In this
+    case, the new index for the source row \c i (which is between
+    \a sourceFirst and \a sourceLast) is equal to
+    \c {(destinationChild-sourceLast-1+i)}.
+
+    Note that if \a sourceParent and \a destinationParent are the same,
+    you must ensure that the \a destinationChild is not within the range
+    of \a sourceFirst and \a sourceLast + 1.  You must also ensure that you
+    do not attempt to move a row to one of its own children or ancestors.
+    This method returns false if either condition is true, in which case you
+    should abort your move operation.
 
     \table 80%
     \row
@@ -2761,29 +2767,35 @@ void QAbstractItemModel::endRemoveColumns()
     When reimplementing a subclass, this method simplifies moving
     entities in your model. This method is responsible for moving
     persistent indexes in the model, which you would otherwise be
-    required to do yourself.
-
-    Using beginMoveColumns and endMoveColumns is an alternative to
-    emitting layoutAboutToBeChanged and layoutChanged directly along
-    with changePersistentIndexes.  layoutAboutToBeChanged is emitted
-    by this method for compatibility reasons.
+    required to do yourself. Using beginMoveRows and endMoveRows
+    is an alternative to emitting layoutAboutToBeChanged and
+    layoutChanged directly along with changePersistentIndexes.
+    layoutAboutToBeChanged is emitted by this method for compatibility
+    reasons.
 
     The \a sourceParent index corresponds to the parent from which the
-    columns are moved; \a sourceFirst and \a sourceLast are the column
-    numbers of the columns to be moved. The \a destinationParent index
-    corresponds to the parent into which the columns are moved. The \a
-    destinationChild is the column to which the columns will be
-    moved.  That is, the index at column \a sourceFirst in \a
-    sourceParent will become column \a destinationChild in \a
-    destinationParent. Its siblings will be moved correspondingly.
-
-    Note that \a sourceParent and \a destinationParent may be the
-    same, in which case you must ensure that the \a destinationChild
-    is not within the range of \a sourceFirst and \a sourceLast.  You
-    must also ensure that you do not attempt to move a row to one of
-    its own chilren or ancestors.  This method returns false if either
-    condition is true, in which case you should abort your move
-    operation.
+    columns are moved; \a sourceFirst and \a sourceLast are the first and last
+    column numbers of the columns to be moved. The \a destinationParent index
+    corresponds to the parent into which those columns are moved. The \a
+    destinationChild is the column to which the columns will be moved.  That
+    is, the index at column \a sourceFirst in \a sourceParent will become
+    column \a destinationChild in \a destinationParent, followed by all other
+    columns up to \a sourceLast.
+
+    However, when moving columns down in the same parent (\a sourceParent
+    and \a destinationParent are equal), the columnss will be placed before the
+    \a destinationChild index. That is, if you wish to move columns 0 and 1 so
+    they will become columns 1 and 2, \a destinationChild should be 3. In this
+    case, the new index for the source column \c i (which is between
+    \a sourceFirst and \a sourceLast) is equal to
+    \c {(destinationChild-sourceLast-1+i)}.
+
+    Note that if \a sourceParent and \a destinationParent are the same,
+    you must ensure that the \a destinationChild is not within the range
+    of \a sourceFirst and \a sourceLast + 1.  You must also ensure that you
+    do not attempt to move a column to one of its own children or ancestors.
+    This method returns false if either condition is true, in which case you
+    should abort your move operation.
 
     \sa endMoveColumns()