20
21
** ensure the GNU Lesser General Public License version 2.1 requirements
21
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23
** In addition, as a special exception, Nokia gives you certain
24
** additional rights. These rights are described in the Nokia Qt LGPL
25
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
28
** GNU General Public License Usage
29
** Alternatively, this file may be used under the terms of the GNU
30
** General Public License version 3.0 as published by the Free Software
31
** Foundation and appearing in the file LICENSE.GPL included in the
32
** packaging of this file. Please review the following information to
33
** ensure the GNU General Public License version 3.0 requirements will be
34
** met: http://www.gnu.org/copyleft/gpl.html.
36
** If you are unsure which license is appropriate for your use, please
37
** contact the sales department at http://www.qtsoftware.com/contact.
24
** In addition, as a special exception, Nokia gives you certain additional
25
** rights. These rights are described in the Nokia Qt LGPL Exception
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28
** If you have questions regarding the use of this file, please contact
29
** Nokia at qt-info@nokia.com.
38
38
** $QT_END_LICENSE$
40
40
****************************************************************************/
467
471
return qEmptyModel();
475
struct DefaultRoleNames : public QHash<int, QByteArray>
478
(*this)[Qt::DisplayRole] = "display";
479
(*this)[Qt::DecorationRole] = "decoration";
480
(*this)[Qt::EditRole] = "edit";
481
(*this)[Qt::ToolTipRole] = "toolTip";
482
(*this)[Qt::StatusTipRole] = "statusTip";
483
(*this)[Qt::WhatsThisRole] = "whatsThis";
488
Q_GLOBAL_STATIC(DefaultRoleNames, qDefaultRoleNames)
490
const QHash<int,QByteArray> &QAbstractItemModelPrivate::defaultRoleNames()
492
return *qDefaultRoleNames();
496
static uint typeOfVariant(const QVariant &value)
498
//return 0 for integer, 1 for floating point and 2 for other
499
switch (value.userType()) {
503
case QVariant::LongLong:
504
case QVariant::ULongLong:
506
case QMetaType::Short:
507
case QMetaType::UShort:
508
case QMetaType::UChar:
509
case QMetaType::ULong:
510
case QMetaType::Long:
512
case QVariant::Double:
513
case QMetaType::Float:
522
return true if \a value contains a numerical type
524
This function is used by our Q{Tree,Widget,Table}WidgetModel classes to sort.
526
bool QAbstractItemModelPrivate::variantLessThan(const QVariant &v1, const QVariant &v2)
528
switch(qMax(typeOfVariant(v1), typeOfVariant(v2)))
530
case 0: //integer type
531
return v1.toLongLong() < v2.toLongLong();
532
case 1: //floating point
533
return v1.toReal() < v2.toReal();
535
return v1.toString() < v2.toString();
470
539
void QAbstractItemModelPrivate::removePersistentIndexData(QPersistentModelIndexData *data)
472
541
if (data->index.isValid()) {
525
594
if (data->index.isValid()) {
526
595
persistent.insertMultiAtEnd(data->index, data);
528
qWarning() << "QAbstractItemModel::endInsertRows: Invalid index (" << old.row() + count << "," << old.column() << ") in model" << q_func();
597
qWarning() << "QAbstractItemModel::endInsertRows: Invalid index (" << old.row() + count << ',' << old.column() << ") in model" << q_func();
602
void QAbstractItemModelPrivate::itemsAboutToBeMoved(const QModelIndex &srcParent, int srcFirst, int srcLast, const QModelIndex &destinationParent, int destinationChild, Qt::Orientation orientation)
604
QVector<QPersistentModelIndexData *> persistent_moved_explicitly;
605
QVector<QPersistentModelIndexData *> persistent_moved_in_source;
606
QVector<QPersistentModelIndexData *> persistent_moved_in_destination;
608
QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it;
609
const QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator begin = persistent.indexes.constBegin();
610
const QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator end = persistent.indexes.constEnd();
612
const bool sameParent = (srcParent == destinationParent);
613
const bool movingUp = (srcFirst > destinationChild);
615
for ( it = begin; it != end; ++it) {
616
QPersistentModelIndexData *data = *it;
617
const QModelIndex &index = data->index;
618
const QModelIndex &parent = index.parent();
619
const bool isSourceIndex = (parent == srcParent);
620
const bool isDestinationIndex = (parent == destinationParent);
623
if (orientation == Qt::Vertical)
624
childPosition = index.row();
626
childPosition = index.column();
628
if (!index.isValid() || !(isSourceIndex || isDestinationIndex ) )
631
if (!sameParent && isDestinationIndex) {
632
if (childPosition >= destinationChild)
633
persistent_moved_in_destination.append(data);
637
if (sameParent && movingUp && childPosition < destinationChild)
640
if (sameParent && !movingUp && childPosition < srcFirst )
643
if (!sameParent && childPosition < srcFirst)
646
if (sameParent && (childPosition > srcLast) && (childPosition >= destinationChild ))
649
if ((childPosition <= srcLast) && (childPosition >= srcFirst)) {
650
persistent_moved_explicitly.append(data);
652
persistent_moved_in_source.append(data);
655
persistent.moved.push(persistent_moved_explicitly);
656
persistent.moved.push(persistent_moved_in_source);
657
persistent.moved.push(persistent_moved_in_destination);
663
Moves persistent indexes \a indexes by amount \a change. The change will be either a change in row value or a change in
664
column value depending on the value of \a orientation. The indexes may also be moved to a different parent if \a parent
665
differs from the existing parent for the index.
667
void QAbstractItemModelPrivate::movePersistentIndexes(QVector<QPersistentModelIndexData *> indexes, int change, const QModelIndex &parent, Qt::Orientation orientation)
669
QVector<QPersistentModelIndexData *>::const_iterator it;
670
const QVector<QPersistentModelIndexData *>::const_iterator begin = indexes.constBegin();
671
const QVector<QPersistentModelIndexData *>::const_iterator end = indexes.constEnd();
673
for (it = begin; it != end; ++it)
675
QPersistentModelIndexData *data = *it;
677
int row = data->index.row();
678
int column = data->index.column();
680
if (Qt::Vertical == orientation)
685
persistent.indexes.erase(persistent.indexes.find(data->index));
686
data->index = q_func()->index(row, column, parent);
687
if (data->index.isValid()) {
688
persistent.insertMultiAtEnd(data->index, data);
690
qWarning() << "QAbstractItemModel::endMoveRows: Invalid index (" << row << "," << column << ") in model" << q_func();
695
void QAbstractItemModelPrivate::itemsMoved(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild, Qt::Orientation orientation)
697
QVector<QPersistentModelIndexData *> moved_in_destination = persistent.moved.pop();
698
QVector<QPersistentModelIndexData *> moved_in_source = persistent.moved.pop();
699
QVector<QPersistentModelIndexData *> moved_explicitly = persistent.moved.pop();
701
const bool sameParent = (sourceParent == destinationParent);
702
const bool movingUp = (sourceFirst > destinationChild);
704
const int explicit_change = (!sameParent || movingUp) ? destinationChild - sourceFirst : destinationChild - sourceLast - 1 ;
705
const int source_change = (!sameParent || !movingUp) ? -1*(sourceLast - sourceFirst + 1) : sourceLast - sourceFirst + 1 ;
706
const int destination_change = sourceLast - sourceFirst + 1;
708
movePersistentIndexes(moved_explicitly, explicit_change, destinationParent, orientation);
709
movePersistentIndexes(moved_in_source, source_change, sourceParent, orientation);
710
movePersistentIndexes(moved_in_destination, destination_change, destinationParent, orientation);
533
713
void QAbstractItemModelPrivate::rowsAboutToBeRemoved(const QModelIndex &parent,
688
868
\brief The QModelIndex class is used to locate data in a data model.
690
870
\ingroup model-view
693
873
This class is used as an index into item models derived from
694
874
QAbstractItemModel. The index is used by item views, delegates, and
695
875
selection models to locate an item in the model.
697
877
New QModelIndex objects are created by the model using the
698
QAbstractItemModel::createIndex() function. An \e invalid model index
699
can be constructed with the QModelIndex constructor. Invalid indexes are
700
often used as parent indexes when referring to top-level items in a model.
878
QAbstractItemModel::createIndex() function. An \e invalid model index can
879
be constructed with the QModelIndex constructor. Invalid indexes are often
880
used as parent indexes when referring to top-level items in a model.
702
882
Model indexes refer to items in models, and contain all the information
703
883
required to specify their locations in those models. Each index is located
704
in a given row and column, and may have a parent index; use row(), column(),
705
and parent() to obtain this information. Each top-level item in a model is
706
represented by a model index that does not have a parent index - in this
707
case, parent() will return an invalid model index, equivalent to an index
708
constructed with the zero argument form of the QModelIndex() constructor.
884
in a given row and column, and may have a parent index; use row(),
885
column(), and parent() to obtain this information. Each top-level item in a
886
model is represented by a model index that does not have a parent index -
887
in this case, parent() will return an invalid model index, equivalent to an
888
index constructed with the zero argument form of the QModelIndex()
710
891
To obtain a model index that refers to an existing item in a model, call
711
QAbstractItemModel::index() with the required row and column
712
values, and the model index of the parent. When referring to
713
top-level items in a model, supply QModelIndex() as the parent index.
892
QAbstractItemModel::index() with the required row and column values, and
893
the model index of the parent. When referring to top-level items in a
894
model, supply QModelIndex() as the parent index.
715
896
The model() function returns the model that the index references as a
717
The child() function is used to examine the items held beneath the index
719
The sibling() function allows you to traverse items in the model on the
720
same level as the index.
897
QAbstractItemModel. The child() function is used to examine items held
898
under the index in the model. The sibling() function allows you to traverse
899
items in the model on the same level as the index.
722
901
\note Model indexes should be used immediately and then discarded. You
723
902
should not rely on indexes to remain valid after calling model functions
724
903
that change the structure of the model or delete items. If you need to
725
904
keep a model index over time use a QPersistentModelIndex.
727
\sa \link model-view-programming.html Model/View Programming\endlink QPersistentModelIndex QAbstractItemModel
906
\sa {Model/View Programming}, QPersistentModelIndex, QAbstractItemModel
731
910
\fn QModelIndex::QModelIndex()
733
Creates a new empty model index.
734
This type of model index is used to indicate
735
that the position in the model is invalid.
912
Creates a new empty model index. This type of model index is used to
913
indicate that the position in the model is invalid.
737
915
\sa isValid() QAbstractItemModel
1130
1320
\fn void QAbstractItemModel::layoutChanged()
1132
1322
This signal is emitted whenever the layout of items exposed by the model
1133
has changed; for example, when the model has been sorted. When this signal is
1134
received by a view, it should update the layout of items to reflect this
1323
has changed; for example, when the model has been sorted. When this signal
1324
is received by a view, it should update the layout of items to reflect this
1137
When subclassing QAbstractItemModel or QAbstractProxyModel, ensure that
1138
you emit layoutAboutToBeChanged() before changing the order of items or
1327
When subclassing QAbstractItemModel or QAbstractProxyModel, ensure that you
1328
emit layoutAboutToBeChanged() before changing the order of items or
1139
1329
altering the structure of the data you expose to views, and emit
1140
1330
layoutChanged() after changing the layout.
1142
Subclasses should update any persistent model indexes before
1143
emitting layoutChanged().
1145
\sa layoutAboutToBeChanged(), dataChanged(), headerDataChanged(), reset(), changePersistentIndex()
1332
Subclasses should update any persistent model indexes before emitting
1333
layoutChanged(). In other words, when the structure changes:
1336
\o Call beginLayoutChanged()
1337
\o Remember the QModelIndex that will change
1338
\o Update your internal data
1339
\o Call changePersistentIndex()
1340
\o Call endLayoutChanged()
1344
\sa layoutAboutToBeChanged(), dataChanged(), headerDataChanged(), modelReset(),
1345
changePersistentIndex()
1487
\fn void QAbstractItemModel::rowsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)
1490
This signal is emitted after rows have been moved within the
1491
model. The items between \a sourceStart and \a sourceEnd
1492
inclusive, under the given \a sourceParent item have been moved to \a destinationParent
1493
starting at the row \a destinationRow.
1495
\bold{Note:} Components connected to this signal use it to adapt to changes
1496
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1497
implementation, and cannot be explicitly emitted in subclass code.
1503
\fn void QAbstractItemModel::rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)
1506
This signal is emitted just before rows are moved within the
1507
model. The items that will be moved are those between \a sourceStart and \a sourceEnd
1508
inclusive, under the given \a sourceParent item. They will be moved to \a destinationParent
1509
starting at the row \a destinationRow.
1511
\bold{Note:} Components connected to this signal use it to adapt to changes
1512
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1513
implementation, and cannot be explicitly emitted in subclass code.
1519
\fn void QAbstractItemModel::columnsMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)
1522
This signal is emitted after columns have been moved within the
1523
model. The items between \a sourceStart and \a sourceEnd
1524
inclusive, under the given \a sourceParent item have been moved to \a destinationParent
1525
starting at the column \a destinationColumn.
1527
\bold{Note:} Components connected to this signal use it to adapt to changes
1528
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1529
implementation, and cannot be explicitly emitted in subclass code.
1535
\fn void QAbstractItemModel::columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)
1538
This signal is emitted just before columns are moved within the
1539
model. The items that will be moved are those between \a sourceStart and \a sourceEnd
1540
inclusive, under the given \a sourceParent item. They will be moved to \a destinationParent
1541
starting at the column \a destinationColumn.
1543
\bold{Note:} Components connected to this signal use it to adapt to changes
1544
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1545
implementation, and cannot be explicitly emitted in subclass code.
1286
1551
\fn void QAbstractItemModel::columnsInserted(const QModelIndex &parent, int start, int end)
1288
This signal is emitted after columns have been inserted into the
1289
model. The new items are those between \a start and \a end
1290
inclusive, under the given \a parent item.
1553
This signal is emitted after columns have been inserted into the model. The
1554
new items are those between \a start and \a end inclusive, under the given
1292
\bold{Note:} Components connected to this signal use it to adapt to changes
1293
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1557
\note Components connected to this signal use it to adapt to changes in the
1558
model's dimensions. It can only be emitted by the QAbstractItemModel
1294
1559
implementation, and cannot be explicitly emitted in subclass code.
1296
1561
\sa insertColumns(), beginInsertColumns()
1328
1593
\fn void QAbstractItemModel::columnsAboutToBeRemoved(const QModelIndex &parent, int start, int end)
1330
This signal is emitted just before columns are removed
1331
from the model. The items to be removed are those between \a start and
1332
\a end inclusive, under the given \a parent item.
1595
This signal is emitted just before columns are removed from the model. The
1596
items to be removed are those between \a start and \a end inclusive, under
1597
the given \a parent item.
1334
\bold{Note:} Components connected to this signal use it to adapt to changes
1335
in the model's dimensions. It can only be emitted by the QAbstractItemModel
1599
\note Components connected to this signal use it to adapt to changes in the
1600
model's dimensions. It can only be emitted by the QAbstractItemModel
1336
1601
implementation, and cannot be explicitly emitted in subclass code.
1338
1603
\sa removeColumns(), beginRemoveColumns()
1342
Returns true if the model returns a valid QModelIndex for \a row and
1343
\a column with \a parent, otherwise returns false.
1607
Returns true if the model returns a valid QModelIndex for \a row and
1608
\a column with \a parent, otherwise returns false.
1345
1610
bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent) const
1475
1742
Handles the \a data supplied by a drag and drop operation that ended with
1476
the given \a action. Returns true if the data and action can be handled
1477
by the model; otherwise returns false.
1479
Although the specified \a row, \a column and \a parent indicate the location of
1480
an item in the model where the operation ended, it is the responsibility of the
1481
view to provide a suitable location for where the data should be inserted.
1483
For instance, a drop action on an item in a QTreeView can result in new items
1484
either being inserted as children of the item specified by \a row, \a column,
1485
and \a parent, or as siblings of the item.
1743
the given \a action.
1745
Returns true if the data and action can be handled by the model; otherwise
1748
Although the specified \a row, \a column and \a parent indicate the
1749
location of an item in the model where the operation ended, it is the
1750
responsibility of the view to provide a suitable location for where the
1751
data should be inserted.
1753
For instance, a drop action on an item in a QTreeView can result in new
1754
items either being inserted as children of the item specified by \a row,
1755
\a column, and \a parent, or as siblings of the item.
1487
1757
When row and column are -1 it means that it is up to the model to decide
1488
where to place the data. This can occur in a tree when data is dropped
1489
on a parent. Models will usually append the data to the parent in this case.
1491
Returns true if the dropping was successful otherwise false.
1758
where to place the data. This can occur in a tree when data is dropped on
1759
a parent. Models will usually append the data to the parent in this case.
1493
1761
\sa supportedDropActions(), {Using Drag and Drop with Item Views}
1572
On models that support this, inserts \a count rows into the model before the
1573
given \a row. The items in the new row will be children of the item
1574
represented by the \a parent model index.
1576
If \a row is 0, the rows are prepended to any existing rows in the parent.
1577
If \a row is rowCount(), the rows are appended to any existing rows in the
1579
If \a parent has no children, a single column with \a count rows is inserted.
1581
Returns true if the rows were successfully inserted; otherwise returns
1584
The base class implementation does nothing and returns false.
1586
If you implement your own model, you can reimplement this function
1587
if you want to support insertions. Alternatively, you can provide
1588
you own API for altering the data.
1590
\sa insertColumns(), removeRows(), beginInsertRows(), endInsertRows()
1840
\note The base class implementation of this function does nothing and
1843
On models that support this, inserts \a count rows into the model before
1844
the given \a row. Items in the new row will be children of the item
1845
represented by the \a parent model index.
1847
If \a row is 0, the rows are prepended to any existing rows in the parent.
1849
If \a row is rowCount(), the rows are appended to any existing rows in the
1852
If \a parent has no children, a single column with \a count rows is
1855
Returns true if the rows were successfully inserted; otherwise returns
1858
If you implement your own model, you can reimplement this function if you
1859
want to support insertions. Alternatively, you can provide your own API for
1860
altering the data. In either case, you will need to call
1861
beginInsertRows() and endInsertRows() to notify other components that the
1864
\sa insertColumns(), removeRows(), beginInsertRows(), endInsertRows()
1592
1866
bool QAbstractItemModel::insertRows(int, int, const QModelIndex &)
1598
On models that support this, inserts \a count new columns into the model
1599
before the given \a column. The items in each new column will be children
1600
of the item represented by the \a parent model index.
1602
If \a column is 0, the columns are prepended to any existing columns.
1603
If \a column is columnCount(), the columns are appended to any existing
1605
If \a parent has no children, a single row with \a count columns is inserted.
1607
Returns true if the columns were successfully inserted; otherwise returns
1610
The base class implementation does nothing and returns false.
1612
If you implement your own model, you can reimplement this function
1613
if you want to support insertions. Alternatively, you can provide
1614
you own API for altering the data.
1616
\sa insertRows(), removeColumns(), beginInsertColumns(), endInsertColumns()
1872
On models that support this, inserts \a count new columns into the model
1873
before the given \a column. The items in each new column will be children
1874
of the item represented by the \a parent model index.
1876
If \a column is 0, the columns are prepended to any existing columns.
1878
If \a column is columnCount(), the columns are appended to any existing
1881
If \a parent has no children, a single row with \a count columns is
1884
Returns true if the columns were successfully inserted; otherwise returns
1887
The base class implementation does nothing and returns false.
1889
If you implement your own model, you can reimplement this function if you
1890
want to support insertions. Alternatively, you can provide your own API for
1893
\sa insertRows(), removeColumns(), beginInsertColumns(), endInsertColumns()
1618
1895
bool QAbstractItemModel::insertColumns(int, int, const QModelIndex &)
1735
Returns a list of indexes for the items in the column of the \a
1736
start index where the data stored under the given \a role matches
1737
the specified \a value. The way the search is performed is defined
1738
by the \a flags given. The list that is returned may be empty.
2019
Returns a list of indexes for the items in the column of the \a start index
2020
where data stored under the given \a role matches the specified \a value.
2021
The way the search is performed is defined by the \a flags given. The list
2022
that is returned may be empty.
1740
The search starts from the \a start index, and continues until the
1741
number of matching data items equals \a hits, the search reaches
1742
the last row, or the search reaches \a start again, depending on
1743
whether \c MatchWrap is specified in \a flags. If you want to search
1744
for all matching items, use \a hits = -1.
2024
The search begins from the \a start index, and continues until the number
2025
of matching data items equals \a hits, the search reaches the last row, or
2026
the search reaches \a start again - depending on whether \c MatchWrap is
2027
specified in \a flags. If you want to search for all matching items, use
1746
2030
By default, this function will perform a wrapping, string-based comparison
1747
2031
on all items, searching for items that begin with the search term specified
1750
\note The default implementation of this function only searches columns,
1751
This function can be reimplemented to include other search behavior.
2034
\note The default implementation of this function only searches columns.
2035
Reimplement this function to include a different search behavior.
1753
2037
QModelIndexList QAbstractItemModel::match(const QModelIndex &start, int role,
1754
2038
const QVariant &value, int hits,
2025
2348
Begins a row insertion operation.
2027
When reimplementing insertRows() in a subclass, you must call this
2028
function \e before inserting data into the model's underlying data
2350
When reimplementing insertRows() in a subclass, you must call this function
2351
\e before inserting data into the model's underlying data store.
2031
The \a parent index corresponds to the parent into which the new
2032
rows are inserted; \a first and \a last are the row numbers that the
2033
new rows will have after they have been inserted.
2353
The \a parent index corresponds to the parent into which the new rows are
2354
inserted; \a first and \a last are the row numbers that the new rows will
2355
have after they have been inserted.
2036
\row \o \inlineimage modelview-begin-insert-rows.png Inserting rows
2037
\o Specify the first and last row numbers for the span of rows
2038
you want to insert into an item in a model.
2040
For example, as shown in the diagram, we insert three rows before
2041
row 2, so \a first is 2 and \a last is 4:
2042
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 0
2043
This inserts the three new rows as rows 2, 3, and 4.
2045
\o \inlineimage modelview-begin-append-rows.png Appending rows
2046
\o To append rows, insert them after the last row.
2048
For example, as shown in the diagram, we append two rows to a
2049
collection of 4 existing rows (ending in row 3), so \a first is 4
2051
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 1
2052
This appends the two new rows as rows 4 and 5.
2359
\o \inlineimage modelview-begin-insert-rows.png Inserting rows
2360
\o Specify the first and last row numbers for the span of rows you
2361
want to insert into an item in a model.
2363
For example, as shown in the diagram, we insert three rows before
2364
row 2, so \a first is 2 and \a last is 4:
2366
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 0
2368
This inserts the three new rows as rows 2, 3, and 4.
2370
\o \inlineimage modelview-begin-append-rows.png Appending rows
2371
\o To append rows, insert them after the last row.
2373
For example, as shown in the diagram, we append two rows to a
2374
collection of 4 existing rows (ending in row 3), so \a first is 4
2377
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 1
2379
This appends the two new rows as rows 4 and 5.
2382
\note This function emits the rowsAboutToBeInserted() signal which
2383
connected views (or proxies) must handle before the data is inserted.
2384
Otherwise, the views may end up in an invalid state.
2055
2385
\sa endInsertRows()
2057
2387
void QAbstractItemModel::beginInsertRows(const QModelIndex &parent, int first, int last)
2085
2414
Begins a row removal operation.
2087
2416
When reimplementing removeRows() in a subclass, you must call this
2088
function \e before removing data from the model's underlying data
2417
function \e before removing data from the model's underlying data store.
2091
The \a parent index corresponds to the parent from which the new
2092
rows are removed; \a first and \a last are the row numbers of the
2419
The \a parent index corresponds to the parent from which the new rows are
2420
removed; \a first and \a last are the row numbers of the rows to be
2096
\row \o \inlineimage modelview-begin-remove-rows.png Removing rows
2097
\o Specify the first and last row numbers for the span of rows
2098
you want to remove from an item in a model.
2100
For example, as shown in the diagram, we remove the two rows from
2101
row 2 to row 3, so \a first is 2 and \a last is 3:
2102
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 2
2425
\o \inlineimage modelview-begin-remove-rows.png Removing rows
2426
\o Specify the first and last row numbers for the span of rows you
2427
want to remove from an item in a model.
2429
For example, as shown in the diagram, we remove the two rows from
2430
row 2 to row 3, so \a first is 2 and \a last is 3:
2432
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 2
2435
\note This function emits the rowsAboutToBeRemoved() signal which connected
2436
views (or proxies) must handle before the data is removed. Otherwise, the
2437
views may end up in an invalid state.
2105
2439
\sa endRemoveRows()
2107
2441
void QAbstractItemModel::beginRemoveRows(const QModelIndex &parent, int first, int last)
2468
Returns whether a move operation is valid.
2470
A move operation is not allowed if it moves a continuous range of rows to a destination within
2471
itself, or if it attempts to move a row to one of its own descendants.
2475
bool QAbstractItemModelPrivate::allowMove(const QModelIndex &srcParent, int start, int end, const QModelIndex &destinationParent, int destinationStart, Qt::Orientation orientation)
2477
// Don't move the range within itself.
2478
if ( ( destinationParent == srcParent )
2479
&& ( destinationStart >= start )
2480
&& ( destinationStart <= end + 1) )
2483
QModelIndex destinationAncestor = destinationParent;
2484
int pos = (Qt::Vertical == orientation) ? destinationAncestor.row() : destinationAncestor.column();
2486
if (destinationAncestor == srcParent) {
2487
if (pos >= start && pos <= end)
2492
if (!destinationAncestor.isValid())
2495
pos = (Qt::Vertical == orientation) ? destinationAncestor.row() : destinationAncestor.column();
2496
destinationAncestor = destinationAncestor.parent();
2503
Begins a row move operation.
2505
When reimplementing a subclass, this method simplifies moving
2506
entities in your model. This method is responsible for moving
2507
persistent indexes in the model, which you would otherwise be
2508
required to do yourself.
2510
Using beginMoveRows and endMoveRows is an alternative to emitting
2511
layoutAboutToBeChanged and layoutChanged directly along with
2512
changePersistentIndexes. layoutAboutToBeChanged is emitted by
2513
this method for compatibility reasons.
2515
The \a sourceParent index corresponds to the parent from which the
2516
rows are moved; \a sourceFirst and \a sourceLast are the row
2517
numbers of the rows to be moved. The \a destinationParent index
2518
corresponds to the parent into which the rows are moved. The \a
2519
destinationChild is the row to which the rows will be moved. That
2520
is, the index at row \a sourceFirst in \a sourceParent will become
2521
row \a destinationChild in \a destinationParent. Its siblings will
2522
be moved correspondingly.
2524
Note that \a sourceParent and \a destinationParent may be the
2525
same, in which case you must ensure that the \a destinationChild is
2526
not within the range of \a sourceFirst and \a sourceLast. You
2527
must also ensure that you do not attempt to move a row to one of
2528
its own chilren or ancestors. This method returns false if either
2529
condition is true, in which case you should abort your move
2536
bool QAbstractItemModel::beginMoveRows(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)
2538
Q_ASSERT(sourceFirst >= 0);
2539
Q_ASSERT(sourceLast >= sourceFirst);
2540
Q_ASSERT(destinationChild >= 0);
2541
Q_D(QAbstractItemModel);
2543
if (!d->allowMove(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild, Qt::Vertical)) {
2547
d->changes.push(QAbstractItemModelPrivate::Change(sourceParent, sourceFirst, sourceLast));
2548
int destinationLast = destinationChild + (sourceLast - sourceFirst);
2549
d->changes.push(QAbstractItemModelPrivate::Change(destinationParent, destinationChild, destinationLast));
2551
d->itemsAboutToBeMoved(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild, Qt::Vertical);
2552
emit rowsAboutToBeMoved(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild);
2553
emit layoutAboutToBeChanged();
2558
Ends a row move operation.
2560
When implementing a subclass, you must call this
2561
function \e after moving data within the model's underlying data
2564
layoutChanged is emitted by this method for compatibility reasons.
2570
void QAbstractItemModel::endMoveRows()
2572
Q_D(QAbstractItemModel);
2574
QAbstractItemModelPrivate::Change insertChange = d->changes.pop();
2575
QAbstractItemModelPrivate::Change removeChange = d->changes.pop();
2577
d->itemsMoved(removeChange.parent, removeChange.first, removeChange.last, insertChange.parent, insertChange.first, Qt::Vertical);
2579
emit rowsMoved(removeChange.parent, removeChange.first, removeChange.last, insertChange.parent, insertChange.first);
2580
emit layoutChanged();
2135
2584
Begins a column insertion operation.
2137
2586
When reimplementing insertColumns() in a subclass, you must call this
2138
function \e before inserting data into the model's underlying data
2587
function \e before inserting data into the model's underlying data store.
2141
The \a parent index corresponds to the parent into which the new
2142
columns are inserted; \a first and \a last are the column numbers of
2143
the new columns will have after they have been inserted.
2589
The \a parent index corresponds to the parent into which the new columns
2590
are inserted; \a first and \a last are the column numbers of the new
2591
columns will have after they have been inserted.
2146
\row \o \inlineimage modelview-begin-insert-columns.png Inserting columns
2147
\o Specify the first and last column numbers for the span of columns
2148
you want to insert into an item in a model.
2150
For example, as shown in the diagram, we insert three columns before
2151
column 4, so \a first is 4 and \a last is 6:
2152
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 3
2153
This inserts the three new columns as columns 4, 5, and 6.
2155
\o \inlineimage modelview-begin-append-columns.png Appending columns
2156
\o To append columns, insert them after the last column.
2158
For example, as shown in the diagram, we append three columns to a
2159
collection of six existing columns (ending in column 5), so \a first
2160
is 6 and \a last is 8:
2161
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 4
2162
This appends the two new columns as columns 6, 7, and 8.
2595
\o \inlineimage modelview-begin-insert-columns.png Inserting columns
2596
\o Specify the first and last column numbers for the span of columns
2597
you want to insert into an item in a model.
2599
For example, as shown in the diagram, we insert three columns
2600
before column 4, so \a first is 4 and \a last is 6:
2602
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 3
2604
This inserts the three new columns as columns 4, 5, and 6.
2606
\o \inlineimage modelview-begin-append-columns.png Appending columns
2607
\o To append columns, insert them after the last column.
2609
For example, as shown in the diagram, we append three columns to a
2610
collection of six existing columns (ending in column 5), so
2611
\a first is 6 and \a last is 8:
2613
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 4
2615
This appends the two new columns as columns 6, 7, and 8.
2618
\note This function emits the columnsAboutToBeInserted() signal which
2619
connected views (or proxies) must handle before the data is inserted.
2620
Otherwise, the views may end up in an invalid state.
2165
2622
\sa endInsertColumns()
2167
2624
void QAbstractItemModel::beginInsertColumns(const QModelIndex &parent, int first, int last)
2195
2652
Begins a column removal operation.
2197
2654
When reimplementing removeColumns() in a subclass, you must call this
2198
function \e before removing data from the model's underlying data
2655
function \e before removing data from the model's underlying data store.
2201
The \a parent index corresponds to the parent from which the new
2202
columns are removed; \a first and \a last are the column numbers of
2203
the first and last columns to be removed.
2657
The \a parent index corresponds to the parent from which the new columns
2658
are removed; \a first and \a last are the column numbers of the first and
2659
last columns to be removed.
2206
\row \o \inlineimage modelview-begin-remove-columns.png Removing columns
2207
\o Specify the first and last column numbers for the span of columns
2208
you want to remove from an item in a model.
2210
For example, as shown in the diagram, we remove the three columns
2211
from column 4 to column 6, so \a first is 4 and \a last is 6:
2212
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 5
2663
\o \inlineimage modelview-begin-remove-columns.png Removing columns
2664
\o Specify the first and last column numbers for the span of columns
2665
you want to remove from an item in a model.
2667
For example, as shown in the diagram, we remove the three columns
2668
from column 4 to column 6, so \a first is 4 and \a last is 6:
2670
\snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 5
2673
\note This function emits the columnsAboutToBeRemoved() signal which
2674
connected views (or proxies) must handle before the data is removed.
2675
Otherwise, the views may end up in an invalid state.
2215
2677
\sa endRemoveColumns()
2217
2679
void QAbstractItemModel::beginRemoveColumns(const QModelIndex &parent, int first, int last)
2706
Begins a column move operation.
2708
When reimplementing a subclass, this method simplifies moving
2709
entities in your model. This method is responsible for moving
2710
persistent indexes in the model, which you would otherwise be
2711
required to do yourself.
2713
Using beginMoveColumns and endMoveColumns is an alternative to
2714
emitting layoutAboutToBeChanged and layoutChanged directly along
2715
with changePersistentIndexes. layoutAboutToBeChanged is emitted
2716
by this method for compatibility reasons.
2718
The \a sourceParent index corresponds to the parent from which the
2719
columns are moved; \a sourceFirst and \a sourceLast are the column
2720
numbers of the columns to be moved. The \a destinationParent index
2721
corresponds to the parent into which the columns are moved. The \a
2722
destinationChild is the column to which the columns will be
2723
moved. That is, the index at column \a sourceFirst in \a
2724
sourceParent will become column \a destinationChild in \a
2725
destinationParent. Its siblings will be moved correspondingly.
2727
Note that \a sourceParent and \a destinationParent may be the
2728
same, in which case you must ensure that the \a destinationChild
2729
is not within the range of \a sourceFirst and \a sourceLast. You
2730
must also ensure that you do not attempt to move a row to one of
2731
its own chilren or ancestors. This method returns false if either
2732
condition is true, in which case you should abort your move
2735
\sa endMoveColumns()
2739
bool QAbstractItemModel::beginMoveColumns(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationChild)
2741
Q_ASSERT(sourceFirst >= 0);
2742
Q_ASSERT(sourceLast >= sourceFirst);
2743
Q_ASSERT(destinationChild >= 0);
2744
Q_D(QAbstractItemModel);
2746
if (!d->allowMove(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild, Qt::Horizontal)) {
2750
d->changes.push(QAbstractItemModelPrivate::Change(sourceParent, sourceFirst, sourceLast));
2751
int destinationLast = destinationChild + (sourceLast - sourceFirst);
2752
d->changes.push(QAbstractItemModelPrivate::Change(destinationParent, destinationChild, destinationLast));
2754
d->itemsAboutToBeMoved(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild, Qt::Horizontal);
2756
emit columnsAboutToBeMoved(sourceParent, sourceFirst, sourceLast, destinationParent, destinationChild);
2757
emit layoutAboutToBeChanged();
2762
Ends a column move operation.
2764
When implementing a subclass, you must call this
2765
function \e after moving data within the model's underlying data
2768
layoutChanged is emitted by this method for compatibility reasons.
2770
\sa beginMoveColumns()
2774
void QAbstractItemModel::endMoveColumns()
2776
Q_D(QAbstractItemModel);
2778
QAbstractItemModelPrivate::Change insertChange = d->changes.pop();
2779
QAbstractItemModelPrivate::Change removeChange = d->changes.pop();
2781
d->itemsMoved(removeChange.parent, removeChange.first, removeChange.last, insertChange.parent, insertChange.first, Qt::Horizontal);
2783
emit columnsMoved(removeChange.parent, removeChange.first, removeChange.last, insertChange.parent, insertChange.first);
2784
emit layoutChanged();
2245
2788
Resets the model to its original state in any attached views.
2247
\note The view to which the model is attached to will be reset as well.
2790
\note Use beginResetModel() and endResetModel() instead whenever possible.
2791
Use this method only if there is no way to call beginResetModel() before invalidating the model.
2792
Otherwise it could lead to unexcpected behaviour, especially when used with proxy models.
2794
void QAbstractItemModel::reset()
2796
Q_D(QAbstractItemModel);
2797
emit modelAboutToBeReset();
2798
d->invalidatePersistentIndexes();
2803
Begins a model reset operation.
2805
A reset operation resets the model to its current state in any attached views.
2807
\note Any views attached to this model will be reset as well.
2249
2809
When a model is reset it means that any previous data reported from the
2250
model is now invalid and has to be queried for again.
2810
model is now invalid and has to be queried for again. This also means that
2811
the current item and any selected items will become invalid.
2252
2813
When a model radically changes its data it can sometimes be easier to just
2253
2814
call this function rather than emit dataChanged() to inform other
2254
2815
components when the underlying data source, or its structure, has changed.
2256
\sa modelAboutToBeReset(), modelReset()
2258
void QAbstractItemModel::reset()
2817
You must call this function before resetting any internal data structures in your model
2820
\sa modelAboutToBeReset(), modelReset(), endResetModel()
2823
void QAbstractItemModel::beginResetModel()
2825
emit modelAboutToBeReset();
2829
Completes a model reset operation.
2831
You must call this function after resetting any internal data structure in your model
2834
\sa beginResetModel()
2837
void QAbstractItemModel::endResetModel()
2260
2839
Q_D(QAbstractItemModel);
2261
emit modelAboutToBeReset();
2262
2840
d->invalidatePersistentIndexes();
2263
2841
emit modelReset();
2267
Changes the QPersistentModelIndex that is equal to the given \a from
2268
model index to the given \a to model index.
2270
If no persistent model index equal to the given \a from model index was
2271
found, nothing is changed.
2273
\sa persistentIndexList(), changePersistentIndexList()
2845
Changes the QPersistentModelIndex that is equal to the given \a from model
2846
index to the given \a to model index.
2848
If no persistent model index equal to the given \a from model index was
2849
found, nothing is changed.
2851
\sa persistentIndexList(), changePersistentIndexList()
2275
2853
void QAbstractItemModel::changePersistentIndex(const QModelIndex &from, const QModelIndex &to)