source: trunk/src/corelib/kernel/qabstractitemmodel.cpp@ 161

Last change on this file since 161 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.

File size: 92.4 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
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
26** package.
27**
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.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42#include "qabstractitemmodel.h"
43#include <private/qabstractitemmodel_p.h>
44#include <qdatastream.h>
45#include <qstringlist.h>
46#include <qsize.h>
47#include <qmimedata.h>
48#include <qdebug.h>
49#include <qvector.h>
50#include <qstack.h>
51#include <qbitarray.h>
52
53#include <limits.h>
54
55QT_BEGIN_NAMESPACE
56
57QPersistentModelIndexData *QPersistentModelIndexData::create(const QModelIndex &index)
58{
59 Q_ASSERT(index.isValid()); // we will _never_ insert an invalid index in the list
60 QPersistentModelIndexData *d = 0;
61 QAbstractItemModel *model = const_cast<QAbstractItemModel *>(index.model());
62 QHash<QModelIndex, QPersistentModelIndexData *> &indexes = model->d_func()->persistent.indexes;
63 const QHash<QModelIndex, QPersistentModelIndexData *>::iterator it = indexes.find(index);
64 if (it != indexes.end()) {
65 d = (*it);
66 } else {
67 d = new QPersistentModelIndexData(index);
68 indexes.insert(index, d);
69 }
70 Q_ASSERT(d);
71 return d;
72}
73
74void QPersistentModelIndexData::destroy(QPersistentModelIndexData *data)
75{
76 Q_ASSERT(data);
77 Q_ASSERT(data->ref == 0);
78 QAbstractItemModel *model = const_cast<QAbstractItemModel *>(data->model);
79 // a valid persistent model index with a null model pointer can only happen if the model was destroyed
80 if (model) {
81 QAbstractItemModelPrivate *p = model->d_func();
82 Q_ASSERT(p);
83 p->removePersistentIndexData(data);
84 }
85 delete data;
86}
87
88/*!
89 \class QPersistentModelIndex
90
91 \brief The QPersistentModelIndex class is used to locate data in a data model.
92
93 \ingroup model-view
94
95 A QPersistentModelIndex is a model index that can be stored by an
96 application, and later used to access information in a model.
97 Unlike the QModelIndex class, it is safe to store a
98 QPersistentModelIndex since the model will ensure that references
99 to items will continue to be valid as long as they can be accessed
100 by the model.
101
102 It is good practice to check that persistent model indexes are valid
103 before using them.
104
105 \sa {Model/View Programming}, QModelIndex, QAbstractItemModel
106*/
107
108
109/*!
110 \fn QPersistentModelIndex::QPersistentModelIndex()
111
112 \internal
113*/
114
115QPersistentModelIndex::QPersistentModelIndex()
116 : d(0)
117{
118}
119
120/*!
121 \fn QPersistentModelIndex::QPersistentModelIndex(const QPersistentModelIndex &other)
122
123 Creates a new QPersistentModelIndex that is a copy of the \a other persistent
124 model index.
125*/
126
127QPersistentModelIndex::QPersistentModelIndex(const QPersistentModelIndex &other)
128 : d(other.d)
129{
130 if (d) d->ref.ref();
131}
132
133/*!
134 Creates a new QPersistentModelIndex that is a copy of the model \a index.
135*/
136
137QPersistentModelIndex::QPersistentModelIndex(const QModelIndex &index)
138 : d(0)
139{
140 if (index.isValid()) {
141 d = QPersistentModelIndexData::create(index);
142 d->ref.ref();
143 }
144}
145
146/*!
147 \fn QPersistentModelIndex::~QPersistentModelIndex()
148
149 \internal
150*/
151
152QPersistentModelIndex::~QPersistentModelIndex()
153{
154 if (d && !d->ref.deref()) {
155 QPersistentModelIndexData::destroy(d);
156 d = 0;
157 }
158}
159
160/*!
161 Returns true if this persistent model index is equal to the \a other
162 persistent model index; otherwise returns false.
163
164 All values in the persistent model index are used when comparing
165 with another persistent model index.
166*/
167
168bool QPersistentModelIndex::operator==(const QPersistentModelIndex &other) const
169{
170 if (d && other.d)
171 return d->index == other.d->index;
172 return d == other.d;
173}
174
175/*!
176 \since 4.1
177
178 Returns true if this persistent model index is smaller than the \a other
179 persistent model index; otherwise returns false.
180
181 All values in the persistent model index are used when comparing
182 with another persistent model index.
183*/
184
185bool QPersistentModelIndex::operator<(const QPersistentModelIndex &other) const
186{
187 if (d && other.d)
188 return d->index < other.d->index;
189
190 return d < other.d;
191}
192
193/*!
194 \fn bool QPersistentModelIndex::operator!=(const QPersistentModelIndex &other) const
195 \since 4.2
196
197 Returns true if this persistent model index is not equal to the \a
198 other persistent model index; otherwise returns false.
199*/
200
201/*!
202 Sets the persistent model index to refer to the same item in a model
203 as the \a other persistent model index.
204*/
205
206QPersistentModelIndex &QPersistentModelIndex::operator=(const QPersistentModelIndex &other)
207{
208 if (d == other.d)
209 return *this;
210 if (d && !d->ref.deref())
211 QPersistentModelIndexData::destroy(d);
212 d = other.d;
213 if (d) d->ref.ref();
214 return *this;
215}
216
217/*!
218 Sets the persistent model index to refer to the same item in a model
219 as the \a other model index.
220*/
221
222QPersistentModelIndex &QPersistentModelIndex::operator=(const QModelIndex &other)
223{
224 if (d && !d->ref.deref())
225 QPersistentModelIndexData::destroy(d);
226 if (other.isValid()) {
227 d = QPersistentModelIndexData::create(other);
228 if (d) d->ref.ref();
229 } else {
230 d = 0;
231 }
232 return *this;
233}
234
235/*!
236 \fn QPersistentModelIndex::operator const QModelIndex&() const
237
238 Cast operator that returns a const QModelIndex&.
239*/
240
241QPersistentModelIndex::operator const QModelIndex&() const
242{
243 static const QModelIndex invalid;
244 if (d)
245 return d->index;
246 return invalid;
247}
248
249/*!
250 \fn bool QPersistentModelIndex::operator==(const QModelIndex &other) const
251
252 Returns true if this persistent model index refers to the same location as
253 the \a other model index; otherwise returns false.
254 Note that all values in the persistent model index are used when comparing
255 with another model index.
256*/
257
258bool QPersistentModelIndex::operator==(const QModelIndex &other) const
259{
260 if (d)
261 return d->index == other;
262 return !other.isValid();
263}
264
265/*!
266 \fn bool QPersistentModelIndex::operator!=(const QModelIndex &other) const
267
268 Returns true if this persistent model index does not refer to the same
269 location as the \a other model index; otherwise returns false.
270*/
271
272bool QPersistentModelIndex::operator!=(const QModelIndex &other) const
273{
274 if (d)
275 return d->index != other;
276 return other.isValid();
277}
278
279/*!
280 \fn int QPersistentModelIndex::row() const
281
282 Returns the row this persistent model index refers to.
283*/
284
285int QPersistentModelIndex::row() const
286{
287 if (d)
288 return d->index.row();
289 return -1;
290}
291
292/*!
293 \fn int QPersistentModelIndex::column() const
294
295 Returns the column this persistent model index refers to.
296*/
297
298int QPersistentModelIndex::column() const
299{
300 if (d)
301 return d->index.column();
302 return -1;
303}
304
305/*!
306 \fn void *QPersistentModelIndex::internalPointer() const
307
308 \internal
309
310 Returns a \c{void} \c{*} pointer used by the model to associate the index with
311 the internal data structure.
312*/
313
314void *QPersistentModelIndex::internalPointer() const
315{
316 if (d)
317 return d->index.internalPointer();
318 return 0;
319}
320
321/*!
322 \fn void *QPersistentModelIndex::internalId() const
323
324 \internal
325
326 Returns a \c{qint64} used by the model to associate the index with
327 the internal data structure.
328*/
329
330qint64 QPersistentModelIndex::internalId() const
331{
332 if (d)
333 return d->index.internalId();
334 return 0;
335}
336
337/*!
338 Returns the parent QModelIndex for this persistent index, or
339 QModelIndex() if it has no parent.
340
341 \sa child() sibling() model()
342*/
343QModelIndex QPersistentModelIndex::parent() const
344{
345 if (d)
346 return d->index.parent();
347 return QModelIndex();
348}
349
350/*!
351 Returns the sibling at \a row and \a column or an invalid
352 QModelIndex if there is no sibling at this position.
353
354 \sa parent() child()
355*/
356
357QModelIndex QPersistentModelIndex::sibling(int row, int column) const
358{
359 if (d)
360 return d->index.sibling(row, column);
361 return QModelIndex();
362}
363
364/*!
365 Returns the child of the model index that is stored in the given
366 \a row and \a column.
367
368 \sa parent() sibling()
369*/
370
371QModelIndex QPersistentModelIndex::child(int row, int column) const
372{
373 if (d)
374 return d->index.child(row, column);
375 return QModelIndex();
376}
377
378/*!
379 Returns the data for the given \a role for the item referred to by the index.
380
381 \sa Qt::ItemDataRole, QAbstractItemModel::setData()
382*/
383QVariant QPersistentModelIndex::data(int role) const
384{
385 if (d)
386 return d->index.data(role);
387 return QVariant();
388}
389
390/*!
391 \since 4.2
392
393 Returns the flags for the item referred to by the index.
394*/
395Qt::ItemFlags QPersistentModelIndex::flags() const
396{
397 if (d)
398 return d->index.flags();
399 return 0;
400}
401
402/*!
403 Returns the model that the index belongs to.
404*/
405const QAbstractItemModel *QPersistentModelIndex::model() const
406{
407 if (d)
408 return d->index.model();
409 return 0;
410}
411
412/*!
413 \fn bool QPersistentModelIndex::isValid() const
414
415 Returns true if this persistent model index is valid; otherwise returns
416 false.
417 A valid index belongs to a model, and has non-negative row and column numbers.
418
419 \sa model(), row(), column()
420*/
421
422bool QPersistentModelIndex::isValid() const
423{
424 return d && d->index.isValid();
425}
426
427#ifndef QT_NO_DEBUG_STREAM
428QDebug operator<<(QDebug dbg, const QModelIndex &idx)
429{
430#ifndef Q_BROKEN_DEBUG_STREAM
431 dbg.nospace() << "QModelIndex(" << idx.row() << "," << idx.column()
432 << "," << idx.internalPointer() << "," << idx.model() << ")";
433 return dbg.space();
434#else
435 qWarning("This compiler doesn't support streaming QModelIndex to QDebug");
436 return dbg;
437 Q_UNUSED(idx);
438#endif
439}
440
441QDebug operator<<(QDebug dbg, const QPersistentModelIndex &idx)
442{
443 if (idx.d)
444 dbg << idx.d->index;
445 else
446 dbg << QModelIndex();
447 return dbg;
448}
449#endif
450
451class QEmptyItemModel : public QAbstractItemModel
452{
453public:
454 explicit QEmptyItemModel(QObject *parent = 0) : QAbstractItemModel(parent) {}
455 QModelIndex index(int, int, const QModelIndex &) const { return QModelIndex(); }
456 QModelIndex parent(const QModelIndex &) const { return QModelIndex(); }
457 int rowCount(const QModelIndex &) const { return 0; }
458 int columnCount(const QModelIndex &) const { return 0; }
459 bool hasChildren(const QModelIndex &) const { return false; }
460 QVariant data(const QModelIndex &, int) const { return QVariant(); }
461};
462
463Q_GLOBAL_STATIC(QEmptyItemModel, qEmptyModel)
464
465QAbstractItemModel *QAbstractItemModelPrivate::staticEmptyModel()
466{
467 return qEmptyModel();
468}
469
470void QAbstractItemModelPrivate::removePersistentIndexData(QPersistentModelIndexData *data)
471{
472 if (data->index.isValid()) {
473 int removed = persistent.indexes.remove(data->index);
474 Q_ASSERT_X(removed == 1, "QPersistentModelIndex::~QPersistentModelIndex",
475 "persistent model indexes corrupted"); //maybe the index was somewhat invalid?
476 // This assert may happen if the model use changePersistentIndex in a way that could result on two
477 // QPersistentModelIndex pointing to the same index.
478 Q_UNUSED(removed);
479 }
480 // make sure our optimization still works
481 for (int i = persistent.moved.count() - 1; i >= 0; --i) {
482 int idx = persistent.moved[i].indexOf(data);
483 if (idx >= 0)
484 persistent.moved[i].remove(idx);
485 }
486 // update the references to invalidated persistent indexes
487 for (int i = persistent.invalidated.count() - 1; i >= 0; --i) {
488 int idx = persistent.invalidated[i].indexOf(data);
489 if (idx >= 0)
490 persistent.invalidated[i].remove(idx);
491 }
492
493}
494
495void QAbstractItemModelPrivate::rowsAboutToBeInserted(const QModelIndex &parent,
496 int first, int last)
497{
498 Q_Q(QAbstractItemModel);
499 Q_UNUSED(last);
500 QVector<QPersistentModelIndexData *> persistent_moved;
501 if (first < q->rowCount(parent)) {
502 for (QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it = persistent.indexes.constBegin();
503 it != persistent.indexes.constEnd(); ++it) {
504 QPersistentModelIndexData *data = *it;
505 const QModelIndex &index = data->index;
506 if (index.row() >= first && index.isValid() && index.parent() == parent) {
507 persistent_moved.append(data);
508 }
509 }
510 }
511 persistent.moved.push(persistent_moved);
512}
513
514void QAbstractItemModelPrivate::rowsInserted(const QModelIndex &parent,
515 int first, int last)
516{
517 QVector<QPersistentModelIndexData *> persistent_moved = persistent.moved.pop();
518 int count = (last - first) + 1; // it is important to only use the delta, because the change could be nested
519 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_moved.constBegin();
520 it != persistent_moved.constEnd(); ++it) {
521 QPersistentModelIndexData *data = *it;
522 QModelIndex old = data->index;
523 persistent.indexes.erase(persistent.indexes.find(old));
524 data->index = q_func()->index(old.row() + count, old.column(), parent);
525 if (data->index.isValid()) {
526 persistent.insertMultiAtEnd(data->index, data);
527 } else {
528 qWarning() << "QAbstractItemModel::endInsertRows: Invalid index (" << old.row() + count << "," << old.column() << ") in model" << q_func();
529 }
530 }
531}
532
533void QAbstractItemModelPrivate::rowsAboutToBeRemoved(const QModelIndex &parent,
534 int first, int last)
535{
536 QVector<QPersistentModelIndexData *> persistent_moved;
537 QVector<QPersistentModelIndexData *> persistent_invalidated;
538 // find the persistent indexes that are affected by the change, either by being in the removed subtree
539 // or by being on the same level and below the removed rows
540 for (QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it = persistent.indexes.constBegin();
541 it != persistent.indexes.constEnd(); ++it) {
542 QPersistentModelIndexData *data = *it;
543 bool level_changed = false;
544 QModelIndex current = data->index;
545 while (current.isValid()) {
546 QModelIndex current_parent = current.parent();
547 if (current_parent == parent) { // on the same level as the change
548 if (!level_changed && current.row() > last) // below the removed rows
549 persistent_moved.append(data);
550 else if (current.row() <= last && current.row() >= first) // in the removed subtree
551 persistent_invalidated.append(data);
552 break;
553 }
554 current = current_parent;
555 level_changed = true;
556 }
557 }
558
559 persistent.moved.push(persistent_moved);
560 persistent.invalidated.push(persistent_invalidated);
561}
562
563void QAbstractItemModelPrivate::rowsRemoved(const QModelIndex &parent,
564 int first, int last)
565{
566 QVector<QPersistentModelIndexData *> persistent_moved = persistent.moved.pop();
567 int count = (last - first) + 1; // it is important to only use the delta, because the change could be nested
568 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_moved.constBegin();
569 it != persistent_moved.constEnd(); ++it) {
570 QPersistentModelIndexData *data = *it;
571 QModelIndex old = data->index;
572 persistent.indexes.erase(persistent.indexes.find(old));
573 data->index = q_func()->index(old.row() - count, old.column(), parent);
574 if (data->index.isValid()) {
575 persistent.insertMultiAtEnd(data->index, data);
576 } else {
577 qWarning() << "QAbstractItemModel::endRemoveRows: Invalid index (" << old.row() - count << "," << old.column() << ") in model" << q_func();
578 }
579 }
580 QVector<QPersistentModelIndexData *> persistent_invalidated = persistent.invalidated.pop();
581 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_invalidated.constBegin();
582 it != persistent_invalidated.constEnd(); ++it) {
583 QPersistentModelIndexData *data = *it;
584 persistent.indexes.erase(persistent.indexes.find(data->index));
585 data->index = QModelIndex();
586 data->model = 0;
587 }
588}
589
590void QAbstractItemModelPrivate::columnsAboutToBeInserted(const QModelIndex &parent,
591 int first, int last)
592{
593 Q_Q(QAbstractItemModel);
594 Q_UNUSED(last);
595 QVector<QPersistentModelIndexData *> persistent_moved;
596 if (first < q->columnCount(parent)) {
597 for (QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it = persistent.indexes.constBegin();
598 it != persistent.indexes.constEnd(); ++it) {
599 QPersistentModelIndexData *data = *it;
600 const QModelIndex &index = data->index;
601 if (index.column() >= first && index.isValid() && index.parent() == parent)
602 persistent_moved.append(data);
603 }
604 }
605 persistent.moved.push(persistent_moved);
606}
607
608void QAbstractItemModelPrivate::columnsInserted(const QModelIndex &parent,
609 int first, int last)
610{
611 QVector<QPersistentModelIndexData *> persistent_moved = persistent.moved.pop();
612 int count = (last - first) + 1; // it is important to only use the delta, because the change could be nested
613 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_moved.constBegin();
614 it != persistent_moved.constEnd(); ++it) {
615 QPersistentModelIndexData *data = *it;
616 QModelIndex old = data->index;
617 persistent.indexes.erase(persistent.indexes.find(old));
618 data->index = q_func()->index(old.row(), old.column() + count, parent);
619 if (data->index.isValid()) {
620 persistent.insertMultiAtEnd(data->index, data);
621 } else {
622 qWarning() << "QAbstractItemModel::endInsertColumns: Invalid index (" << old.row() << "," << old.column() + count << ") in model" << q_func();
623 }
624 }
625}
626
627void QAbstractItemModelPrivate::columnsAboutToBeRemoved(const QModelIndex &parent,
628 int first, int last)
629{
630 QVector<QPersistentModelIndexData *> persistent_moved;
631 QVector<QPersistentModelIndexData *> persistent_invalidated;
632 // find the persistent indexes that are affected by the change, either by being in the removed subtree
633 // or by being on the same level and to the right of the removed columns
634 for (QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it = persistent.indexes.constBegin();
635 it != persistent.indexes.constEnd(); ++it) {
636 QPersistentModelIndexData *data = *it;
637 bool level_changed = false;
638 QModelIndex current = data->index;
639 while (current.isValid()) {
640 QModelIndex current_parent = current.parent();
641 if (current_parent == parent) { // on the same level as the change
642 if (!level_changed && current.column() > last) // right of the removed columns
643 persistent_moved.append(data);
644 else if (current.column() <= last && current.column() >= first) // in the removed subtree
645 persistent_invalidated.append(data);
646 break;
647 }
648 current = current_parent;
649 level_changed = true;
650 }
651 }
652
653 persistent.moved.push(persistent_moved);
654 persistent.invalidated.push(persistent_invalidated);
655
656}
657
658void QAbstractItemModelPrivate::columnsRemoved(const QModelIndex &parent,
659 int first, int last)
660{
661 QVector<QPersistentModelIndexData *> persistent_moved = persistent.moved.pop();
662 int count = (last - first) + 1; // it is important to only use the delta, because the change could be nested
663 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_moved.constBegin();
664 it != persistent_moved.constEnd(); ++it) {
665 QPersistentModelIndexData *data = *it;
666 QModelIndex old = data->index;
667 persistent.indexes.erase(persistent.indexes.find(old));
668 data->index = q_func()->index(old.row(), old.column() - count, parent);
669 if (data->index.isValid()) {
670 persistent.insertMultiAtEnd(data->index, data);
671 } else {
672 qWarning() << "QAbstractItemModel::endRemoveColumns: Invalid index (" << old.row() << "," << old.column() - count << ") in model" << q_func();
673 }
674 }
675 QVector<QPersistentModelIndexData *> persistent_invalidated = persistent.invalidated.pop();
676 for (QVector<QPersistentModelIndexData *>::const_iterator it = persistent_invalidated.constBegin();
677 it != persistent_invalidated.constEnd(); ++it) {
678 QPersistentModelIndexData *data = *it;
679 persistent.indexes.erase(persistent.indexes.find(data->index));
680 data->index = QModelIndex();
681 data->model = 0;
682 }
683}
684
685/*!
686 \class QModelIndex
687
688 \brief The QModelIndex class is used to locate data in a data model.
689
690 \ingroup model-view
691 \mainclass
692
693 This class is used as an index into item models derived from
694 QAbstractItemModel. The index is used by item views, delegates, and
695 selection models to locate an item in the model.
696
697 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.
701
702 Model indexes refer to items in models, and contain all the information
703 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.
709
710 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.
714
715 The model() function returns the model that the index references as a
716 QAbstractItemModel.
717 The child() function is used to examine the items held beneath the index
718 in the model.
719 The sibling() function allows you to traverse items in the model on the
720 same level as the index.
721
722 \note Model indexes should be used immediately and then discarded. You
723 should not rely on indexes to remain valid after calling model functions
724 that change the structure of the model or delete items. If you need to
725 keep a model index over time use a QPersistentModelIndex.
726
727 \sa \link model-view-programming.html Model/View Programming\endlink QPersistentModelIndex QAbstractItemModel
728*/
729
730/*!
731 \fn QModelIndex::QModelIndex()
732
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.
736
737 \sa isValid() QAbstractItemModel
738*/
739
740/*!
741 \fn QModelIndex::QModelIndex(int row, int column, void *data, const QAbstractItemModel *model)
742
743 \internal
744
745 Creates a new model index at the given \a row and \a column,
746 pointing to some \a data.
747*/
748
749/*!
750 \fn QModelIndex::QModelIndex(const QModelIndex &other)
751
752 Creates a new model index that is a copy of the \a other model
753 index.
754*/
755
756/*!
757 \fn QModelIndex::~QModelIndex()
758
759 Destroys the model index.
760*/
761
762/*!
763 \fn int QModelIndex::row() const
764
765 Returns the row this model index refers to.
766*/
767
768
769/*!
770 \fn int QModelIndex::column() const
771
772 Returns the column this model index refers to.
773*/
774
775
776/*!
777 \fn void *QModelIndex::internalPointer() const
778
779 Returns a \c{void} \c{*} pointer used by the model to associate
780 the index with the internal data structure.
781
782 \sa QAbstractItemModel::createIndex()
783*/
784
785/*!
786 \fn void *QModelIndex::internalId() const
787
788 Returns a \c{qint64} used by the model to associate
789 the index with the internal data structure.
790
791 \sa QAbstractItemModel::createIndex()
792*/
793
794/*!
795 \fn bool QModelIndex::isValid() const
796
797 Returns true if this model index is valid; otherwise returns false.
798 A valid index belongs to a model, and has non-negative row and column numbers.
799
800 \sa model(), row(), column()
801*/
802
803/*!
804 \fn const QAbstractItemModel *QModelIndex::model() const
805
806 Returns a pointer to the model containing the item that this index
807 refers to.
808
809 You receive a const pointer to the model because calls to
810 non-const functions of the model might invalidate the model index
811 - and possibly crash your application.
812*/
813
814/*!
815 \fn QModelIndex QModelIndex::sibling(int row, int column) const
816
817 Returns the sibling at \a row and \a column or an invalid
818 QModelIndex if there is no sibling at this position.
819
820 \sa parent() child()
821*/
822
823/*!
824 \fn QModelIndex QModelIndex::child(int row, int column) const
825
826 Returns the child of the model index that is stored in the given
827 \a row and \a column.
828
829 \sa parent() sibling()
830*/
831
832/*!
833 \fn QVariant QModelIndex::data(int role) const
834
835 Returns the data for the given \a role for the item referred to by the index.
836*/
837
838/*!
839 \fn Qt::ItemFlags QModelIndex::flags() const
840 \since 4.2
841
842 Returns the flags for the item referred to by the index.
843*/
844
845/*!
846 \fn bool QModelIndex::operator==(const QModelIndex &other) const
847
848 Returns true if this model index refers to the same location as
849 the \a other model index; otherwise returns false.
850 Note that all values in the model index are used when comparing
851 with another model index.
852*/
853
854
855/*!
856 \fn bool QModelIndex::operator!=(const QModelIndex &other) const
857
858 Returns true if this model index does not refer to the same
859 location as the \a other model index; otherwise returns false.
860*/
861
862
863/*!
864 \fn QModelIndex QModelIndex::parent() const
865
866 Returns the parent of the model index, or QModelIndex() if it has no
867 parent.
868
869 \sa child() sibling() model()
870*/
871
872/*!
873 \class QAbstractItemModel
874
875 \brief The QAbstractItemModel class provides the abstract interface for
876 item model classes.
877
878 \ingroup model-view
879 \mainclass
880
881 The QAbstractItemModel class defines the standard interface that item
882 models must use to be able to interoperate with other components in the
883 model/view architecture. It is not supposed to be instantiated directly.
884 Instead, you should subclass it to create new models.
885
886 The QAbstractItemModel class is one of the \l{Model/View Classes}
887 and is part of Qt's \l{Model/View Programming}{model/view framework}.
888
889 If you need a model to use with a QListView or a QTableView, you should
890 consider subclassing QAbstractListModel or QAbstractTableModel instead of
891 this class.
892
893 The underlying data model is exposed to views and delegates as a hierarchy
894 of tables. If you do not make use of the hierarchy, then the model is a
895 simple table of rows and columns. Each item has a unique index specified by
896 a QModelIndex.
897
898 \img modelindex-no-parent.png
899
900 Every item of data that can be accessed via a model has an associated model
901 index. You can obtain this model index using the index() function. Each
902 index may have a sibling() index; child items have a parent() index.
903
904 Each item has a number of data elements associated with it and they can be
905 retrieved by specifying a role (see \l Qt::ItemDataRole) to the model's
906 data() function. Data for all available roles can be obtained at the same
907 time using the itemData() function.
908
909 Data for each role is set using a particular \l Qt::ItemDataRole. Data for
910 individual roles are set individually with setData(), or they can be set
911 for all roles with setItemData().
912
913 Items can be queried with flags() (see \l Qt::ItemFlag) to see if they can
914 be selected, dragged, or manipulated in other ways.
915
916 If an item has child objects, hasChildren() returns true for the
917 corresponding index.
918
919 The model has a rowCount() and a columnCount() for each level of the
920 hierarchy. Rows and columns can be inserted and removed with insertRows(),
921 insertColumns(), removeRows(), and removeColumns().
922
923 The model emits signals to indicate changes. For example, dataChanged() is
924 emitted whenever items of data made available by the model are changed.
925 Changes to the headers supplied by the model cause headerDataChanged() to
926 be emitted. If the structure of the underlying data changes, the model can
927 emit layoutChanged() to indicate to any attached views that they should
928 redisplay any items shown, taking the new structure into account.
929
930 The items available through the model can be searched for particular data
931 using the match() function.
932
933 To sort the model, you can use sort().
934
935
936 \section1 Subclassing
937
938 \note Some general guidelines for subclassing models are available in the
939 \l{Model Subclassing Reference}.
940
941 When subclassing QAbstractItemModel, at the very least you must implement
942 index(), parent(), rowCount(), columnCount(), and data(). These functions
943 are used in all read-only models, and form the basis of editable models.
944
945 You can also reimplement hasChildren() to provide special behavior for
946 models where the implementation of rowCount() is expensive. This makes it
947 possible for models to restrict the amount of data requested by views, and
948 can be used as a way to implement lazy population of model data.
949
950 To enable editing in your model, you must also implement setData(), and
951 reimplement flags() to ensure that \c ItemIsEditable is returned. You can
952 also reimplement headerData() and setHeaderData() to control the way the
953 headers for your model are presented.
954
955 The dataChanged() and headerDataChanged() signals must be emitted
956 explicitly when reimplementing the setData() and setHeaderData() functions,
957 respectively.
958
959 Custom models need to create model indexes for other components to use. To
960 do this, call createIndex() with suitable row and column numbers for the
961 item, and an identifier for it, either as a pointer or as an integer value.
962 The combination of these values must be unique for each item. Custom models
963 typically use these unique identifiers in other reimplemented functions to
964 retrieve item data and access information about the item's parents and
965 children. See the \l{Simple Tree Model Example} for more information about
966 unique identifiers.
967
968 It is not necessary to support every role defined in Qt::ItemDataRole.
969 Depending on the type of data contained within a model, it may only be
970 useful to implement the data() function to return valid information for
971 some of the more common roles. Most models provide at least a textual
972 representation of item data for the Qt::DisplayRole, and well-behaved
973 models should also provide valid information for the Qt::ToolTipRole and
974 Qt::WhatsThisRole. Supporting these roles enables models to be used with
975 standard Qt views. However, for some models that handle highly-specialized
976 data, it may be appropriate to provide data only for user-defined roles.
977
978 Models that provide interfaces to resizable data structures can provide
979 implementations of insertRows(), removeRows(), insertColumns(),and
980 removeColumns(). When implementing these functions, it is important to
981 notify any connected views about changes to the model's dimensions both
982 \e before and \e after they occur:
983
984 \list
985 \o An insertRows() implementation must call beginInsertRows() \e before
986 inserting new rows into the data structure, and endInsertRows()
987 \e{immediately afterwards}.
988 \o An insertColumns() implementation must call beginInsertColumns()
989 \e before inserting new columns into the data structure, and
990 endInsertColumns() \e{immediately afterwards}.
991 \o A removeRows() implementation must call beginRemoveRows() \e before
992 the rows are removed from the data structure, and endRemoveRows()
993 \e{immediately afterwards}.
994 \o A removeColumns() implementation must call beginRemoveColumns()
995 \e before the columns are removed from the data structure, and
996 endRemoveColumns() \e{immediately afterwards}.
997 \endlist
998
999 The \e private signals that these functions emit give attached components
1000 the chance to take action before any data becomes unavailable. The
1001 encapsulation of the insert and remove operations with these begin and end
1002 functions also enables the model to manage \l{QPersistentModelIndex}
1003 {persistent model indexes} correctly. \bold{If you want selections to be
1004 handled properly, you must ensure that you call these functions.} If you
1005 insert or remove an item with children, you do not need to call these
1006 functions for the child items. In other words, the parent item will take
1007 care of its child items.
1008
1009 To create models that populate incrementally, you can reimplement
1010 fetchMore() and canFetchMore(). If the reimplementation of fetchMore() adds
1011 rows to the model, \l{QAbstractItemModel::}{beginInsertRows()} and
1012 \l{QAbstractItemModel::}{endInsertRows()} must be called.
1013
1014 \sa {Model Classes}, {Model Subclassing Reference}, QModelIndex,
1015 QAbstractItemView, {Using Drag and Drop with Item Views},
1016 {Simple DOM Model Example},
1017 {Simple Tree Model Example}, {Editable Tree Model Example},
1018 {Fetch More Example}
1019*/
1020
1021/*!
1022 \fn QModelIndex QAbstractItemModel::index(int row, int column, const QModelIndex &parent) const = 0
1023
1024 Returns the index of the item in the model specified by the given \a row,
1025 \a column and \a parent index.
1026
1027 When reimplementing this function in a subclass, call createIndex() to generate
1028 model indexes that other components can use to refer to items in your model.
1029
1030 \sa createIndex()
1031*/
1032
1033/*!
1034 \fn bool QAbstractItemModel::insertColumn(int column, const QModelIndex &parent)
1035
1036 Inserts a single column before the given \a column in the child items of
1037 the \a parent specified. Returns true if the column is inserted; otherwise
1038 returns false.
1039
1040 \sa insertColumns() insertRow() removeColumn()
1041*/
1042
1043/*!
1044 \fn bool QAbstractItemModel::insertRow(int row, const QModelIndex &parent)
1045
1046 Inserts a single row before the given \a row in the child items of the
1047 \a parent specified. Returns true if the row is inserted; otherwise
1048 returns false.
1049
1050 \sa insertRows() insertColumn() removeRow()
1051*/
1052
1053/*!
1054 \fn QObject *QAbstractItemModel::parent() const
1055 \internal
1056*/
1057
1058/*!
1059 \fn QModelIndex QAbstractItemModel::parent(const QModelIndex &index) const = 0
1060
1061 Returns the parent of the model item with the given \a index, or QModelIndex()
1062 if it has no parent.
1063
1064 A common convention used in models that expose tree data structures is that
1065 only items in the first column have children. For that case, when reimplementing
1066 this function in a subclass the column of the returned QModelIndex would be 0.
1067
1068 \note When reimplementing this function in a subclass, be careful to avoid
1069 calling QModelIndex member functions, such as QModelIndex::parent(), since
1070 indexes belonging to your model will simply call your implementation, leading
1071 to infinite recursion.
1072
1073 \sa createIndex()
1074*/
1075
1076/*!
1077 \fn bool QAbstractItemModel::removeColumn(int column, const QModelIndex &parent)
1078
1079 Removes the given \a column from the child items of the \a parent specified.
1080 Returns true if the column is removed; otherwise returns false.
1081
1082 \sa removeColumns(), removeRow(), insertColumn()
1083*/
1084
1085/*!
1086 \fn bool QAbstractItemModel::removeRow(int row, const QModelIndex &parent)
1087
1088 Removes the given \a row from the child items of the \a parent specified.
1089 Returns true if the row is removed; otherwise returns false.
1090
1091 The removeRow() is a convenience function that calls removeRows().
1092 The QAbstractItemModel implementation of removeRows does nothing.
1093
1094 \sa removeRows(), removeColumn(), insertRow()
1095*/
1096
1097/*!
1098 \fn void QAbstractItemModel::headerDataChanged(Qt::Orientation orientation, int first, int last)
1099
1100 This signal is emitted whenever a header is changed. The \a orientation
1101 indicates whether the horizontal or vertical header has changed. The
1102 sections in the header from the \a first to the \a last need to be updated.
1103
1104 Note that this signal must be emitted explicitly when
1105 reimplementing the setHeaderData() function.
1106
1107 If you are changing the number of columns or rows you don't need
1108 to emit this signal, but use the begin/end functions (see the
1109 section on subclassing in the QAbstractItemModel class description
1110 for details).
1111
1112 \sa headerData(), setHeaderData(), dataChanged()
1113*/
1114
1115/*!
1116 \fn void QAbstractItemModel::layoutAboutToBeChanged()
1117 \since 4.2
1118
1119 This signal is emitted just before the layout of a model is changed.
1120 Components connected to this signal use it to adapt to changes
1121 in the model's layout.
1122
1123 Subclasses should update any persistent model indexes after emitting
1124 layoutAboutToBeChanged().
1125
1126 \sa layoutChanged(), changePersistentIndex()
1127*/
1128
1129/*!
1130 \fn void QAbstractItemModel::layoutChanged()
1131
1132 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
1135 change.
1136
1137 When subclassing QAbstractItemModel or QAbstractProxyModel, ensure that
1138 you emit layoutAboutToBeChanged() before changing the order of items or
1139 altering the structure of the data you expose to views, and emit
1140 layoutChanged() after changing the layout.
1141
1142 Subclasses should update any persistent model indexes before
1143 emitting layoutChanged().
1144
1145 \sa layoutAboutToBeChanged(), dataChanged(), headerDataChanged(), reset(), changePersistentIndex()
1146*/
1147
1148/*!
1149 Constructs an abstract item model with the given \a parent.
1150*/
1151QAbstractItemModel::QAbstractItemModel(QObject *parent)
1152 : QObject(*new QAbstractItemModelPrivate, parent)
1153{
1154}
1155
1156/*!
1157 \internal
1158*/
1159QAbstractItemModel::QAbstractItemModel(QAbstractItemModelPrivate &dd, QObject *parent)
1160 : QObject(dd, parent)
1161{
1162}
1163
1164/*!
1165 Destroys the abstract item model.
1166*/
1167QAbstractItemModel::~QAbstractItemModel()
1168{
1169 d_func()->invalidatePersistentIndexes();
1170}
1171
1172/*!
1173 \fn QModelIndex QAbstractItemModel::sibling(int row, int column, const QModelIndex &index) const
1174
1175 Returns the sibling at \a row and \a column for the item at \a index, or
1176 an invalid QModelIndex if there is no sibling at that location.
1177
1178 sibling() is just a convenience function that finds the item's parent, and
1179 uses it to retrieve the index of the child item in the specified \a row
1180 and \a column.
1181
1182 \sa index(), QModelIndex::row(), QModelIndex::column()
1183*/
1184
1185
1186/*!
1187 \fn int QAbstractItemModel::rowCount(const QModelIndex &parent) const
1188
1189 Returns the number of rows under the given \a parent. When the parent
1190 is valid it means that rowCount is returning the number of children of parent.
1191
1192 \bold{Tip:} When implementing a table based model, rowCount() should return 0 when
1193 the parent is valid.
1194
1195 \sa columnCount()
1196*/
1197
1198/*!
1199 \fn int QAbstractItemModel::columnCount(const QModelIndex &parent) const
1200
1201 Returns the number of columns for the children of the given \a parent.
1202
1203 In most subclasses, the number of columns is independent of the
1204 \a parent. For example:
1205
1206 \snippet examples/itemviews/simpledommodel/dommodel.cpp 2
1207
1208 \bold{Tip:} When implementing a table based model, columnCount() should return 0 when
1209 the parent is valid.
1210
1211 \sa rowCount()
1212*/
1213
1214/*!
1215 \fn void QAbstractItemModel::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight)
1216
1217 This signal is emitted whenever the data in an existing item changes.
1218
1219 If the items are of the same parent, the affected ones are those between
1220 \a topLeft and \a bottomRight inclusive. If the items do not have the same
1221 parent, the behavior is undefined.
1222
1223 When reimplementing the setData() function, this signal must be emitted
1224 explicitly.
1225
1226 \sa headerDataChanged(), setData(), layoutChanged()
1227*/
1228
1229/*!
1230 \fn void QAbstractItemModel::rowsInserted(const QModelIndex &parent, int start, int end)
1231
1232 This signal is emitted after rows have been inserted into the
1233 model. The new items are those between \a start and \a end
1234 inclusive, under the given \a parent item.
1235
1236 \bold{Note:} Components connected to this signal use it to adapt to changes
1237 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1238 implementation, and cannot be explicitly emitted in subclass code.
1239
1240 \sa insertRows(), beginInsertRows()
1241*/
1242
1243/*!
1244 \fn void QAbstractItemModel::rowsAboutToBeInserted(const QModelIndex &parent, int start, int end)
1245
1246 This signal is emitted just before rows are inserted into the
1247 model. The new items will be positioned between \a start and \a end
1248 inclusive, under the given \a parent item.
1249
1250 \bold{Note:} Components connected to this signal use it to adapt to changes
1251 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1252 implementation, and cannot be explicitly emitted in subclass code.
1253
1254 \sa insertRows(), beginInsertRows()
1255*/
1256
1257/*!
1258 \fn void QAbstractItemModel::rowsRemoved(const QModelIndex &parent, int start, int end)
1259
1260 This signal is emitted after rows have been removed from the
1261 model. The removed items are those between \a start and \a end
1262 inclusive, under the given \a parent item.
1263
1264 \bold{Note:} Components connected to this signal use it to adapt to changes
1265 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1266 implementation, and cannot be explicitly emitted in subclass code.
1267
1268 \sa removeRows(), beginRemoveRows()
1269*/
1270
1271/*!
1272 \fn void QAbstractItemModel::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)
1273
1274 This signal is emitted just before rows are removed from the
1275 model. The items that will be removed are those between \a start and \a end
1276 inclusive, under the given \a parent item.
1277
1278 \bold{Note:} Components connected to this signal use it to adapt to changes
1279 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1280 implementation, and cannot be explicitly emitted in subclass code.
1281
1282 \sa removeRows(), beginRemoveRows()
1283*/
1284
1285/*!
1286 \fn void QAbstractItemModel::columnsInserted(const QModelIndex &parent, int start, int end)
1287
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.
1291
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
1294 implementation, and cannot be explicitly emitted in subclass code.
1295
1296 \sa insertColumns(), beginInsertColumns()
1297*/
1298
1299/*!
1300 \fn void QAbstractItemModel::columnsAboutToBeInserted(const QModelIndex &parent, int start, int end)
1301
1302 This signal is emitted just before columns are inserted into the
1303 model. The new items will be positioned between \a start and \a end
1304 inclusive, under the given \a parent item.
1305
1306 \bold{Note:} Components connected to this signal use it to adapt to changes
1307 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1308 implementation, and cannot be explicitly emitted in subclass code.
1309
1310 \sa insertColumns(), beginInsertColumns()
1311*/
1312
1313/*!
1314 \fn void QAbstractItemModel::columnsRemoved(const QModelIndex &parent, int start, int end)
1315
1316 This signal is emitted after columns have been removed from the
1317 model. The removed items are those between \a start and \a end
1318 inclusive, under the given \a parent item.
1319
1320 \bold{Note:} Components connected to this signal use it to adapt to changes
1321 in the model's dimensions. It can only be emitted by the QAbstractItemModel
1322 implementation, and cannot be explicitly emitted in subclass code.
1323
1324 \sa removeColumns(), beginRemoveColumns()
1325*/
1326
1327/*!
1328 \fn void QAbstractItemModel::columnsAboutToBeRemoved(const QModelIndex &parent, int start, int end)
1329
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.
1333
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
1336 implementation, and cannot be explicitly emitted in subclass code.
1337
1338 \sa removeColumns(), beginRemoveColumns()
1339*/
1340
1341/*!
1342 Returns true if the model returns a valid QModelIndex for \a row and
1343 \a column with \a parent, otherwise returns false.
1344*/
1345bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent) const
1346{
1347 if (row < 0 || column < 0)
1348 return false;
1349 return row < rowCount(parent) && column < columnCount(parent);
1350}
1351
1352
1353/*!
1354 Returns true if \a parent has any children; otherwise returns false.
1355 Use rowCount() on the parent to find out the number of children.
1356
1357 \sa parent() index()
1358*/
1359bool QAbstractItemModel::hasChildren(const QModelIndex &parent) const
1360{
1361 return (rowCount(parent) > 0) && (columnCount(parent) > 0);
1362}
1363
1364
1365/*!
1366 Returns a map with values for all predefined roles in the model
1367 for the item at the given \a index.
1368
1369 Reimplemented this function if you want to extend the default behavior
1370 of this function to include custom roles in the map.
1371
1372 \sa Qt::ItemDataRole, data()
1373*/
1374QMap<int, QVariant> QAbstractItemModel::itemData(const QModelIndex &index) const
1375{
1376 QMap<int, QVariant> roles;
1377 for (int i = 0; i < Qt::UserRole; ++i) {
1378 QVariant variantData = data(index, i);
1379 if (variantData.type() != QVariant::Invalid)
1380 roles.insert(i, variantData);
1381 }
1382 return roles;
1383}
1384
1385/*!
1386 Sets the \a role data for the item at \a index to \a value.
1387 Returns true if successful; otherwise returns false.
1388
1389 The dataChanged() signal should be emitted if the data was successfully set.
1390
1391 The base class implementation returns false. This function and
1392 data() must be reimplemented for editable models. Note that the
1393 dataChanged() signal must be emitted explicitly when
1394 reimplementing this function.
1395
1396 \sa Qt::ItemDataRole, data(), itemData()
1397*/
1398bool QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role)
1399{
1400 Q_UNUSED(index);
1401 Q_UNUSED(value);
1402 Q_UNUSED(role);
1403 return false;
1404}
1405
1406/*!
1407 \fn QVariant QAbstractItemModel::data(const QModelIndex &index, int role) const = 0
1408
1409 Returns the data stored under the given \a role for the item referred to
1410 by the \a index.
1411
1412 \note If you do not have a value to return, return an \bold invalid
1413 QVariant() instead of returning 0.
1414
1415 \sa Qt::ItemDataRole, setData(), headerData()
1416*/
1417
1418/*!
1419 Sets the role data for the item at \a index to the associated value in
1420 \a roles, for every Qt::ItemDataRole. Returns true if successful; otherwise
1421 returns false.
1422
1423 Roles that are not in \a roles will not be modified.
1424
1425 \sa setData() data() itemData()
1426*/
1427bool QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)
1428{
1429 bool b = true;
1430 for (QMap<int, QVariant>::ConstIterator it = roles.begin(); it != roles.end(); ++it)
1431 b = b && setData(index, it.value(), it.key());
1432 return b;
1433}
1434
1435/*!
1436 Returns a list of MIME types that can be used to describe a list of
1437 model indexes.
1438
1439 \sa mimeData()
1440*/
1441QStringList QAbstractItemModel::mimeTypes() const
1442{
1443 QStringList types;
1444 types << QLatin1String("application/x-qabstractitemmodeldatalist");
1445 return types;
1446}
1447
1448/*!
1449 Returns an object that contains serialized items of data corresponding to the
1450 list of \a indexes specified. The formats used to describe the encoded data
1451 is obtained from the mimeTypes() function.
1452
1453 If the list of indexes is empty, or there are no supported MIME types,
1454 0 is returned rather than a serialized empty list.
1455
1456 \sa mimeTypes(), dropMimeData()
1457*/
1458QMimeData *QAbstractItemModel::mimeData(const QModelIndexList &indexes) const
1459{
1460 if (indexes.count() <= 0)
1461 return 0;
1462 QStringList types = mimeTypes();
1463 if (types.isEmpty())
1464 return 0;
1465 QMimeData *data = new QMimeData();
1466 QString format = types.at(0);
1467 QByteArray encoded;
1468 QDataStream stream(&encoded, QIODevice::WriteOnly);
1469 encodeData(indexes, stream);
1470 data->setData(format, encoded);
1471 return data;
1472}
1473
1474/*!
1475 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.
1478
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.
1482
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.
1486
1487 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.
1490
1491 Returns true if the dropping was successful otherwise false.
1492
1493 \sa supportedDropActions(), {Using Drag and Drop with Item Views}
1494*/
1495bool QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action,
1496 int row, int column, const QModelIndex &parent)
1497{
1498 // check if the action is supported
1499 if (!data || !(action == Qt::CopyAction || action == Qt::MoveAction))
1500 return false;
1501 // check if the format is supported
1502 QStringList types = mimeTypes();
1503 if (types.isEmpty())
1504 return false;
1505 QString format = types.at(0);
1506 if (!data->hasFormat(format))
1507 return false;
1508 if (row > rowCount(parent))
1509 row = rowCount(parent);
1510 if (row == -1)
1511 row = rowCount(parent);
1512 if (column == -1)
1513 column = 0;
1514 // decode and insert
1515 QByteArray encoded = data->data(format);
1516 QDataStream stream(&encoded, QIODevice::ReadOnly);
1517 return decodeData(row, column, parent, stream);
1518}
1519
1520/*!
1521 \since 4.2
1522
1523 Returns the drop actions supported by this model.
1524
1525 The default implementation returns Qt::CopyAction. Reimplement this
1526 function if you wish to support additional actions. Note that you
1527 must also reimplement the dropMimeData() function to handle the
1528 additional operations.
1529
1530 \sa dropMimeData(), Qt::DropActions, {Using Drag and Drop with Item
1531 Views}
1532*/
1533Qt::DropActions QAbstractItemModel::supportedDropActions() const
1534{
1535 return Qt::CopyAction;
1536}
1537
1538/*!
1539 Returns the actions supported by the data in this model.
1540
1541 The default implementation returns supportedDropActions() unless
1542 specific values have been set with setSupportedDragActions().
1543
1544 supportedDragActions() is used by QAbstractItemView::startDrag() as
1545 the default values when a drag occurs.
1546
1547 \sa Qt::DropActions, {Using Drag and Drop with Item Views}
1548*/
1549Qt::DropActions QAbstractItemModel::supportedDragActions() const
1550{
1551 // ### Qt 5: make this virtual or these properties
1552 Q_D(const QAbstractItemModel);
1553 if (d->supportedDragActions != -1)
1554 return d->supportedDragActions;
1555 return supportedDropActions();
1556}
1557
1558/*!
1559 \since 4.2
1560
1561 Sets the supported drag \a actions for the items in the model.
1562
1563 \sa supportedDragActions(), {Using Drag and Drop with Item Views}
1564*/
1565void QAbstractItemModel::setSupportedDragActions(Qt::DropActions actions)
1566{
1567 Q_D(QAbstractItemModel);
1568 d->supportedDragActions = actions;
1569}
1570
1571/*!
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.
1575
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
1578 parent.
1579 If \a parent has no children, a single column with \a count rows is inserted.
1580
1581 Returns true if the rows were successfully inserted; otherwise returns
1582 false.
1583
1584 The base class implementation does nothing and returns false.
1585
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.
1589
1590 \sa insertColumns(), removeRows(), beginInsertRows(), endInsertRows()
1591*/
1592bool QAbstractItemModel::insertRows(int, int, const QModelIndex &)
1593{
1594 return false;
1595}
1596
1597/*!
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.
1601
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
1604 columns.
1605 If \a parent has no children, a single row with \a count columns is inserted.
1606
1607 Returns true if the columns were successfully inserted; otherwise returns
1608 false.
1609
1610 The base class implementation does nothing and returns false.
1611
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.
1615
1616 \sa insertRows(), removeColumns(), beginInsertColumns(), endInsertColumns()
1617*/
1618bool QAbstractItemModel::insertColumns(int, int, const QModelIndex &)
1619{
1620 return false;
1621}
1622
1623/*!
1624 On models that support this, removes \a count rows starting with the given
1625 \a row under parent \a parent from the model. Returns true if the rows
1626 were successfully removed; otherwise returns false.
1627
1628 The base class implementation does nothing and returns false.
1629
1630 If you implement your own model, you can reimplement this function
1631 if you want to support removing. Alternatively, you can provide
1632 you own API for altering the data.
1633
1634 \sa removeRow(), removeColumns(), insertColumns(), beginRemoveRows(), endRemoveRows()
1635*/
1636bool QAbstractItemModel::removeRows(int, int, const QModelIndex &)
1637{
1638 return false;
1639}
1640
1641/*!
1642 On models that support this, removes \a count columns starting with the
1643 given \a column under parent \a parent from the model. Returns true if the
1644 columns were successfully removed; otherwise returns false.
1645
1646 The base class implementation does nothing and returns false.
1647
1648 If you implement your own model, you can reimplement this function
1649 if you want to support removing. Alternatively, you can provide
1650 you own API for altering the data.
1651
1652 \sa removeColumn(), removeRows(), insertColumns(), beginRemoveColumns(), endRemoveColumns()
1653*/
1654bool QAbstractItemModel::removeColumns(int, int, const QModelIndex &)
1655{
1656 return false;
1657}
1658
1659/*!
1660 Fetches any available data for the items with the parent specified by the
1661 \a parent index.
1662
1663 Reimplement this if you are populating your model incrementally.
1664
1665 The default implementation does nothing.
1666
1667 \sa canFetchMore()
1668*/
1669void QAbstractItemModel::fetchMore(const QModelIndex &)
1670{
1671 // do nothing
1672}
1673
1674/*!
1675 Returns true if there is more data available for \a parent; otherwise returns
1676 false.
1677
1678 The default implementation always returns false.
1679
1680 If canFetchMore() returns true, QAbstractItemView will call fetchMore().
1681 However, the fetchMore() function is only called when the model is being
1682 populated incrementally.
1683
1684 \sa fetchMore()
1685*/
1686bool QAbstractItemModel::canFetchMore(const QModelIndex &) const
1687{
1688 return false;
1689}
1690
1691/*!
1692 Returns the item flags for the given \a index.
1693
1694 The base class implementation returns a combination of flags that
1695 enables the item (\c ItemIsEnabled) and allows it to be
1696 selected (\c ItemIsSelectable).
1697
1698 \sa Qt::ItemFlags
1699*/
1700Qt::ItemFlags QAbstractItemModel::flags(const QModelIndex &index) const
1701{
1702 Q_D(const QAbstractItemModel);
1703 if (!d->indexValid(index))
1704 return 0;
1705
1706 return Qt::ItemIsSelectable|Qt::ItemIsEnabled;
1707}
1708
1709/*!
1710 Sorts the model by \a column in the given \a order.
1711
1712 The base class implementation does nothing.
1713*/
1714void QAbstractItemModel::sort(int column, Qt::SortOrder order)
1715{
1716 Q_UNUSED(column);
1717 Q_UNUSED(order);
1718 // do nothing
1719}
1720
1721/*!
1722 Returns a model index for the buddy of the item represented by \a index.
1723 When the user wants to edit an item, the view will call this function to
1724 check whether another item in the model should be edited instead, and
1725 construct a delegate using the model index returned by the buddy item.
1726
1727 In the default implementation each item is its own buddy.
1728*/
1729QModelIndex QAbstractItemModel::buddy(const QModelIndex &index) const
1730{
1731 return index;
1732}
1733
1734/*!
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.
1739
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.
1745
1746 By default, this function will perform a wrapping, string-based comparison
1747 on all items, searching for items that begin with the search term specified
1748 by \a value.
1749
1750 \note The default implementation of this function only searches columns,
1751 This function can be reimplemented to include other search behavior.
1752*/
1753QModelIndexList QAbstractItemModel::match(const QModelIndex &start, int role,
1754 const QVariant &value, int hits,
1755 Qt::MatchFlags flags) const
1756{
1757 QModelIndexList result;
1758 uint matchType = flags & 0x0F;
1759 Qt::CaseSensitivity cs = flags & Qt::MatchCaseSensitive ? Qt::CaseSensitive : Qt::CaseInsensitive;
1760 bool recurse = flags & Qt::MatchRecursive;
1761 bool wrap = flags & Qt::MatchWrap;
1762 bool allHits = (hits == -1);
1763 QString text; // only convert to a string if it is needed
1764 QModelIndex p = parent(start);
1765 int from = start.row();
1766 int to = rowCount(p);
1767
1768 // iterates twice if wrapping
1769 for (int i = 0; (wrap && i < 2) || (!wrap && i < 1); ++i) {
1770 for (int r = from; (r < to) && (allHits || result.count() < hits); ++r) {
1771 QModelIndex idx = index(r, start.column(), p);
1772 if (!idx.isValid())
1773 continue;
1774 QVariant v = data(idx, role);
1775 // QVariant based matching
1776 if (matchType == Qt::MatchExactly) {
1777 if (value == v)
1778 result.append(idx);
1779 } else { // QString based matching
1780 if (text.isEmpty()) // lazy conversion
1781 text = value.toString();
1782 QString t = v.toString();
1783 switch (matchType) {
1784 case Qt::MatchRegExp:
1785 if (QRegExp(text, cs).exactMatch(t))
1786 result.append(idx);
1787 break;
1788 case Qt::MatchWildcard:
1789 if (QRegExp(text, cs, QRegExp::Wildcard).exactMatch(t))
1790 result.append(idx);
1791 break;
1792 case Qt::MatchStartsWith:
1793 if (t.startsWith(text, cs))
1794 result.append(idx);
1795 break;
1796 case Qt::MatchEndsWith:
1797 if (t.endsWith(text, cs))
1798 result.append(idx);
1799 break;
1800 case Qt::MatchFixedString:
1801 if (t.compare(text, cs) == 0)
1802 result.append(idx);
1803 break;
1804 case Qt::MatchContains:
1805 default:
1806 if (t.contains(text, cs))
1807 result.append(idx);
1808 }
1809 }
1810 if (recurse && hasChildren(idx)) { // search the hierarchy
1811 result += match(index(0, idx.column(), idx), role,
1812 (text.isEmpty() ? value : text),
1813 (allHits ? -1 : hits - result.count()), flags);
1814 }
1815 }
1816 // prepare for the next iteration
1817 from = 0;
1818 to = start.row();
1819 }
1820 return result;
1821}
1822
1823/*!
1824 Returns the row and column span of the item represented by \a index.
1825
1826 Note: span is not used currently, but will be in the future.
1827*/
1828
1829QSize QAbstractItemModel::span(const QModelIndex &) const
1830{
1831 return QSize(1, 1);
1832}
1833
1834/*!
1835 Called to let the model know that it should submit whatever it has cached
1836 to the permanent storage. Typically used for row editing.
1837
1838 Returns false on error, otherwise true.
1839*/
1840
1841bool QAbstractItemModel::submit()
1842{
1843 return true;
1844}
1845
1846/*!
1847 Called to let the model know that it should discard whatever it has cached.
1848 Typically used for row editing.
1849*/
1850
1851void QAbstractItemModel::revert()
1852{
1853 // do nothing
1854}
1855
1856/*!
1857 Returns the data for the given \a role and \a section in the header
1858 with the specified \a orientation.
1859
1860 For horizontal headers, the section number corresponds to the column
1861 number of items shown beneath it. For vertical headers, the section
1862 number typically to the row number of items shown alongside it.
1863
1864 \sa Qt::ItemDataRole, setHeaderData(), QHeaderView
1865*/
1866
1867QVariant QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role) const
1868{
1869 Q_UNUSED(orientation);
1870 if (role == Qt::DisplayRole)
1871 return section + 1;
1872 return QVariant();
1873}
1874
1875/*!
1876 Sets the data for the given \a role and \a section in the header with
1877 the specified \a orientation to the \a value supplied.
1878 Returns true if the header's data was updated; otherwise returns false.
1879
1880 Note that the headerDataChanged() signal must be emitted explicitly
1881 when reimplementing this function.
1882
1883 \sa Qt::ItemDataRole, headerData()
1884*/
1885
1886bool QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation,
1887 const QVariant &value, int role)
1888{
1889 Q_UNUSED(section);
1890 Q_UNUSED(orientation);
1891 Q_UNUSED(value);
1892 Q_UNUSED(role);
1893 return false;
1894}
1895
1896/*!
1897 \fn QModelIndex QAbstractItemModel::createIndex(int row, int column, void *ptr) const
1898
1899 Creates a model index for the given \a row and \a column with the internal pointer \a ptr.
1900
1901 Note that when you are using a QSortFilterProxyModel its indexes have their own
1902 internal pointer. It is not advisable to access the internal pointer in the index
1903 outside of the model. Use the data() function instead.
1904
1905 This function provides a consistent interface that model subclasses must
1906 use to create model indexes.
1907*/
1908
1909/*!
1910 \fn QModelIndex QAbstractItemModel::createIndex(int row, int column, int id) const
1911 \obsolete
1912
1913 Use QModelIndex QAbstractItemModel::createIndex(int row, int column, quint32 id) instead.
1914*/
1915
1916/*!
1917 \fn QModelIndex QAbstractItemModel::createIndex(int row, int column, quint32 id) const
1918
1919 Creates a model index for the given \a row and \a column with the internal
1920 identifier, \a id.
1921
1922 This function provides a consistent interface that model subclasses must
1923 use to create model indexes.
1924 \sa QModelIndex::internalId()
1925*/
1926
1927/*!
1928 \internal
1929*/
1930void QAbstractItemModel::encodeData(const QModelIndexList &indexes, QDataStream &stream) const
1931{
1932 QModelIndexList::ConstIterator it = indexes.begin();
1933 for (; it != indexes.end(); ++it)
1934 stream << (*it).row() << (*it).column() << itemData(*it);
1935}
1936
1937/*!
1938 \internal
1939 */
1940bool QAbstractItemModel::decodeData(int row, int column, const QModelIndex &parent,
1941 QDataStream &stream)
1942{
1943 int top = INT_MAX;
1944 int left = INT_MAX;
1945 int bottom = 0;
1946 int right = 0;
1947 QVector<int> rows, columns;
1948 QVector<QMap<int, QVariant> > data;
1949
1950 while (!stream.atEnd()) {
1951 int r, c;
1952 QMap<int, QVariant> v;
1953 stream >> r >> c >> v;
1954 rows.append(r);
1955 columns.append(c);
1956 data.append(v);
1957 top = qMin(r, top);
1958 left = qMin(c, left);
1959 bottom = qMax(r, bottom);
1960 right = qMax(c, right);
1961 }
1962
1963 // insert the dragged items into the table, use a bit array to avoid overwriting items,
1964 // since items from different tables can have the same row and column
1965 int dragRowCount = 0;
1966 int dragColumnCount = right - left + 1;
1967
1968 // Compute the number of continuous rows upon insertion and modify the rows to match
1969 QVector<int> rowsToInsert(bottom + 1);
1970 for (int i = 0; i < rows.count(); ++i)
1971 rowsToInsert[rows.at(i)] = 1;
1972 for (int i = 0; i < rowsToInsert.count(); ++i) {
1973 if (rowsToInsert[i] == 1){
1974 rowsToInsert[i] = dragRowCount;
1975 ++dragRowCount;
1976 }
1977 }
1978 for (int i = 0; i < rows.count(); ++i)
1979 rows[i] = top + rowsToInsert[rows[i]];
1980
1981 QBitArray isWrittenTo(dragRowCount * dragColumnCount);
1982
1983 // make space in the table for the dropped data
1984 int colCount = columnCount(parent);
1985 if (colCount == 0) {
1986 insertColumns(colCount, dragColumnCount - colCount, parent);
1987 colCount = columnCount(parent);
1988 }
1989 insertRows(row, dragRowCount, parent);
1990
1991 row = qMax(0, row);
1992 column = qMax(0, column);
1993
1994 QVector<QPersistentModelIndex> newIndexes(data.size());
1995 // set the data in the table
1996 for (int j = 0; j < data.size(); ++j) {
1997 int relativeRow = rows.at(j) - top;
1998 int relativeColumn = columns.at(j) - left;
1999 int destinationRow = relativeRow + row;
2000 int destinationColumn = relativeColumn + column;
2001 int flat = (relativeRow * dragColumnCount) + relativeColumn;
2002 // if the item was already written to, or we just can't fit it in the table, create a new row
2003 if (destinationColumn >= colCount || isWrittenTo.testBit(flat)) {
2004 destinationColumn = qBound(column, destinationColumn, colCount - 1);
2005 destinationRow = row + dragRowCount;
2006 insertRows(row + dragRowCount, 1, parent);
2007 flat = (dragRowCount * dragColumnCount) + relativeColumn;
2008 isWrittenTo.resize(++dragRowCount * dragColumnCount);
2009 }
2010 if (!isWrittenTo.testBit(flat)) {
2011 newIndexes[j] = index(destinationRow, destinationColumn, parent);
2012 isWrittenTo.setBit(flat);
2013 }
2014 }
2015
2016 for(int k = 0; k < newIndexes.size(); k++) {
2017 if (newIndexes.at(k).isValid())
2018 setItemData(newIndexes.at(k), data.at(k));
2019 }
2020
2021 return true;
2022}
2023
2024/*!
2025 Begins a row insertion operation.
2026
2027 When reimplementing insertRows() in a subclass, you must call this
2028 function \e before inserting data into the model's underlying data
2029 store.
2030
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.
2034
2035 \table 80%
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.
2039
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.
2044 \row
2045 \o \inlineimage modelview-begin-append-rows.png Appending rows
2046 \o To append rows, insert them after the last row.
2047
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
2050 and \a last is 5:
2051 \snippet doc/src/snippets/code/src_corelib_kernel_qabstractitemmodel.cpp 1
2052 This appends the two new rows as rows 4 and 5.
2053 \endtable
2054
2055 \sa endInsertRows()
2056*/
2057void QAbstractItemModel::beginInsertRows(const QModelIndex &parent, int first, int last)
2058{
2059 Q_ASSERT(first >= 0);
2060 Q_ASSERT(last >= first);
2061 Q_D(QAbstractItemModel);
2062 d->changes.push(QAbstractItemModelPrivate::Change(parent, first, last));
2063 emit rowsAboutToBeInserted(parent, first, last);
2064 d->rowsAboutToBeInserted(parent, first, last);
2065}
2066
2067/*!
2068 Ends a row insertion operation.
2069
2070 When reimplementing insertRows() in a subclass, you must call this
2071 function \e after inserting data into the model's underlying data
2072 store.
2073
2074 \sa beginInsertRows()
2075*/
2076void QAbstractItemModel::endInsertRows()
2077{
2078 Q_D(QAbstractItemModel);
2079 QAbstractItemModelPrivate::Change change = d->changes.pop();
2080 d->rowsInserted(change.parent, change.first, change.last);
2081 emit rowsInserted(change.parent, change.first, change.last);
2082}
2083
2084/*!
2085 Begins a row removal operation.
2086
2087 When reimplementing removeRows() in a subclass, you must call this
2088 function \e before removing data from the model's underlying data
2089 store.
2090
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
2093 rows to be removed.
2094
2095 \table 80%
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.
2099
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
2103 \endtable
2104
2105 \sa endRemoveRows()
2106*/
2107void QAbstractItemModel::beginRemoveRows(const QModelIndex &parent, int first, int last)
2108{
2109 Q_ASSERT(first >= 0);
2110 Q_ASSERT(last >= first);
2111 Q_D(QAbstractItemModel);
2112 d->changes.push(QAbstractItemModelPrivate::Change(parent, first, last));
2113 emit rowsAboutToBeRemoved(parent, first, last);
2114 d->rowsAboutToBeRemoved(parent, first, last);
2115}
2116
2117/*!
2118 Ends a row removal operation.
2119
2120 When reimplementing removeRows() in a subclass, you must call this
2121 function \e after removing data from the model's underlying data
2122 store.
2123
2124 \sa beginRemoveRows()
2125*/
2126void QAbstractItemModel::endRemoveRows()
2127{
2128 Q_D(QAbstractItemModel);
2129 QAbstractItemModelPrivate::Change change = d->changes.pop();
2130 d->rowsRemoved(change.parent, change.first, change.last);
2131 emit rowsRemoved(change.parent, change.first, change.last);
2132}
2133
2134/*!
2135 Begins a column insertion operation.
2136
2137 When reimplementing insertColumns() in a subclass, you must call this
2138 function \e before inserting data into the model's underlying data
2139 store.
2140
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.
2144
2145 \table 80%
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.
2149
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.
2154 \row
2155 \o \inlineimage modelview-begin-append-columns.png Appending columns
2156 \o To append columns, insert them after the last column.
2157
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.
2163 \endtable
2164
2165 \sa endInsertColumns()
2166*/
2167void QAbstractItemModel::beginInsertColumns(const QModelIndex &parent, int first, int last)
2168{
2169 Q_ASSERT(first >= 0);
2170 Q_ASSERT(last >= first);
2171 Q_D(QAbstractItemModel);
2172 d->changes.push(QAbstractItemModelPrivate::Change(parent, first, last));
2173 emit columnsAboutToBeInserted(parent, first, last);
2174 d->columnsAboutToBeInserted(parent, first, last);
2175}
2176
2177/*!
2178 Ends a column insertion operation.
2179
2180 When reimplementing insertColumns() in a subclass, you must call this
2181 function \e after inserting data into the model's underlying data
2182 store.
2183
2184 \sa beginInsertColumns()
2185*/
2186void QAbstractItemModel::endInsertColumns()
2187{
2188 Q_D(QAbstractItemModel);
2189 QAbstractItemModelPrivate::Change change = d->changes.pop();
2190 d->columnsInserted(change.parent, change.first, change.last);
2191 emit columnsInserted(change.parent, change.first, change.last);
2192}
2193
2194/*!
2195 Begins a column removal operation.
2196
2197 When reimplementing removeColumns() in a subclass, you must call this
2198 function \e before removing data from the model's underlying data
2199 store.
2200
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.
2204
2205 \table 80%
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.
2209
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
2213 \endtable
2214
2215 \sa endRemoveColumns()
2216*/
2217void QAbstractItemModel::beginRemoveColumns(const QModelIndex &parent, int first, int last)
2218{
2219 Q_ASSERT(first >= 0);
2220 Q_ASSERT(last >= first);
2221 Q_D(QAbstractItemModel);
2222 d->changes.push(QAbstractItemModelPrivate::Change(parent, first, last));
2223 emit columnsAboutToBeRemoved(parent, first, last);
2224 d->columnsAboutToBeRemoved(parent, first, last);
2225}
2226
2227/*!
2228 Ends a column removal operation.
2229
2230 When reimplementing removeColumns() in a subclass, you must call this
2231 function \e after removing data from the model's underlying data
2232 store.
2233
2234 \sa beginRemoveColumns()
2235*/
2236void QAbstractItemModel::endRemoveColumns()
2237{
2238 Q_D(QAbstractItemModel);
2239 QAbstractItemModelPrivate::Change change = d->changes.pop();
2240 d->columnsRemoved(change.parent, change.first, change.last);
2241 emit columnsRemoved(change.parent, change.first, change.last);
2242}
2243
2244/*!
2245 Resets the model to its original state in any attached views.
2246
2247 \note The view to which the model is attached to will be reset as well.
2248
2249 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.
2251
2252 When a model radically changes its data it can sometimes be easier to just
2253 call this function rather than emit dataChanged() to inform other
2254 components when the underlying data source, or its structure, has changed.
2255
2256 \sa modelAboutToBeReset(), modelReset()
2257*/
2258void QAbstractItemModel::reset()
2259{
2260 Q_D(QAbstractItemModel);
2261 emit modelAboutToBeReset();
2262 d->invalidatePersistentIndexes();
2263 emit modelReset();
2264}
2265
2266/*!
2267 Changes the QPersistentModelIndex that is equal to the given \a from
2268 model index to the given \a to model index.
2269
2270 If no persistent model index equal to the given \a from model index was
2271 found, nothing is changed.
2272
2273 \sa persistentIndexList(), changePersistentIndexList()
2274*/
2275void QAbstractItemModel::changePersistentIndex(const QModelIndex &from, const QModelIndex &to)
2276{
2277 Q_D(QAbstractItemModel);
2278 if (d->persistent.indexes.isEmpty())
2279 return;
2280 // find the data and reinsert it sorted
2281 const QHash<QModelIndex, QPersistentModelIndexData *>::iterator it = d->persistent.indexes.find(from);
2282 if (it != d->persistent.indexes.end()) {
2283 QPersistentModelIndexData *data = *it;
2284 d->persistent.indexes.erase(it);
2285 data->index = to;
2286 if (to.isValid())
2287 d->persistent.insertMultiAtEnd(to, data);
2288 else
2289 data->model = 0;
2290 }
2291}
2292
2293/*!
2294 \since 4.1
2295
2296 Changes the QPersistentModelIndexes that is equal to the indexes in the given \a from
2297 model index list to the given \a to model index list.
2298
2299 If no persistent model indexes equal to the indexes in the given \a from model index list
2300 was found, nothing is changed.
2301
2302 \sa persistentIndexList(), changePersistentIndex()
2303*/
2304void QAbstractItemModel::changePersistentIndexList(const QModelIndexList &from,
2305 const QModelIndexList &to)
2306{
2307 Q_D(QAbstractItemModel);
2308 if (d->persistent.indexes.isEmpty())
2309 return;
2310 QVector<QPersistentModelIndexData *> toBeReinserted;
2311 toBeReinserted.reserve(to.count());
2312 for (int i = 0; i < from.count(); ++i) {
2313 if (from.at(i) == to.at(i))
2314 continue;
2315 const QHash<QModelIndex, QPersistentModelIndexData *>::iterator it = d->persistent.indexes.find(from.at(i));
2316 if (it != d->persistent.indexes.end()) {
2317 QPersistentModelIndexData *data = *it;
2318 d->persistent.indexes.erase(it);
2319 data->index = to.at(i);
2320 if (data->index.isValid())
2321 toBeReinserted << data;
2322 else
2323 data->model = 0;
2324 }
2325 }
2326
2327 for (QVector<QPersistentModelIndexData *>::const_iterator it = toBeReinserted.constBegin();
2328 it != toBeReinserted.constEnd() ; ++it) {
2329 QPersistentModelIndexData *data = *it;
2330 d->persistent.insertMultiAtEnd(data->index, data);
2331 }
2332}
2333
2334/*!
2335 \since 4.2
2336
2337 Returns the list of indexes stored as persistent indexes in the model.
2338*/
2339QModelIndexList QAbstractItemModel::persistentIndexList() const
2340{
2341 Q_D(const QAbstractItemModel);
2342 QModelIndexList result;
2343 for (QHash<QModelIndex, QPersistentModelIndexData *>::const_iterator it = d->persistent.indexes.constBegin();
2344 it != d->persistent.indexes.constEnd(); ++it) {
2345 QPersistentModelIndexData *data = *it;
2346 result.append(data->index);
2347 }
2348 return result;
2349}
2350
2351
2352/*!
2353 \class QAbstractTableModel
2354 \brief The QAbstractTableModel class provides an abstract model that can be
2355 subclassed to create table models.
2356
2357 \ingroup model-view
2358
2359 QAbstractTableModel provides a standard interface for models that represent
2360 their data as a two-dimensional array of items. It is not used directly,
2361 but must be subclassed.
2362
2363 Since the model provides a more specialized interface than
2364 QAbstractItemModel, it is not suitable for use with tree views, although
2365 it can be used to provide data to a QListView. If you need to represent
2366 a simple list of items, and only need a model to contain a single column
2367 of data, subclassing the QAbstractListModel may be more appropriate.
2368
2369 The rowCount() and columnCount() functions return the dimensions of the
2370 table. To retrieve a model index corresponding to an item in the model, use
2371 index() and provide only the row and column numbers.
2372
2373 \section1 Subclassing
2374
2375 \bold{Note:} Some general guidelines for subclassing models are
2376 available in the \l{Model Subclassing Reference}.
2377
2378 When subclassing QAbstractTableModel, you must implement rowCount(),
2379 columnCount(), and data(). Default implementations of the index() and
2380 parent() functions are provided by QAbstractTableModel.
2381 Well behaved models will also implement headerData().
2382
2383 Editable models need to implement setData(), and implement flags() to
2384 return a value containing
2385 \l{Qt::ItemFlags}{Qt::ItemIsEditable}.
2386
2387 Models that provide interfaces to resizable data structures can
2388 provide implementations of insertRows(), removeRows(), insertColumns(),
2389 and removeColumns(). When implementing these functions, it is
2390 important to call the appropriate functions so that all connected views
2391 are aware of any changes:
2392
2393 \list
2394 \o An insertRows() implementation must call beginInsertRows()
2395 \e before inserting new rows into the data structure, and it must
2396 call endInsertRows() \e{immediately afterwards}.
2397 \o An insertColumns() implementation must call beginInsertColumns()
2398 \e before inserting new columns into the data structure, and it must
2399 call endInsertColumns() \e{immediately afterwards}.
2400 \o A removeRows() implementation must call beginRemoveRows()
2401 \e before the rows are removed from the data structure, and it must
2402 call endRemoveRows() \e{immediately afterwards}.
2403 \o A removeColumns() implementation must call beginRemoveColumns()
2404 \e before the columns are removed from the data structure, and it must
2405 call endRemoveColumns() \e{immediately afterwards}.
2406 \endlist
2407
2408 \sa {Model Classes}, {Model Subclassing Reference}, QAbstractItemModel,
2409 QAbstractListModel,
2410 {Pixelator Example}
2411*/
2412
2413/*!
2414 Constructs an abstract table model for the given \a parent.
2415*/
2416
2417QAbstractTableModel::QAbstractTableModel(QObject *parent)
2418 : QAbstractItemModel(parent)
2419{
2420
2421}
2422
2423/*!
2424 \internal
2425
2426 Constructs an abstract table model with \a dd and the given \a parent.
2427*/
2428
2429QAbstractTableModel::QAbstractTableModel(QAbstractItemModelPrivate &dd, QObject *parent)
2430 : QAbstractItemModel(dd, parent)
2431{
2432
2433}
2434
2435/*!
2436 Destroys the abstract table model.
2437*/
2438
2439QAbstractTableModel::~QAbstractTableModel()
2440{
2441
2442}
2443
2444/*!
2445 \fn QModelIndex QAbstractTableModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const
2446
2447 Returns the index of the data in \a row and \a column with \a parent.
2448
2449 \sa parent()
2450*/
2451
2452QModelIndex QAbstractTableModel::index(int row, int column, const QModelIndex &parent) const
2453{
2454 return hasIndex(row, column, parent) ? createIndex(row, column, 0) : QModelIndex();
2455}
2456
2457/*!
2458 \fn QModelIndex QAbstractTableModel::parent(const QModelIndex &index) const
2459
2460 Returns the parent of the model item with the given \a index.
2461
2462 \sa index() hasChildren()
2463*/
2464
2465QModelIndex QAbstractTableModel::parent(const QModelIndex &) const
2466{
2467 return QModelIndex();
2468}
2469
2470bool QAbstractTableModel::hasChildren(const QModelIndex &parent) const
2471{
2472 if (parent.model() == this || !parent.isValid())
2473 return rowCount(parent) > 0 && columnCount(parent) > 0;
2474 return false;
2475}
2476
2477/*!
2478 \class QAbstractListModel
2479 \brief The QAbstractListModel class provides an abstract model that can be
2480 subclassed to create one-dimensional list models.
2481
2482 \ingroup model-view
2483
2484 QAbstractListModel provides a standard interface for models that represent
2485 their data as a simple non-hierarchical sequence of items. It is not used
2486 directly, but must be subclassed.
2487
2488 Since the model provides a more specialized interface than
2489 QAbstractItemModel, it is not suitable for use with tree views; you will
2490 need to subclass QAbstractItemModel if you want to provide a model for
2491 that purpose. If you need to use a number of list models to manage data,
2492 it may be more appropriate to subclass QAbstractTableModel class instead.
2493
2494 Simple models can be created by subclassing this class and implementing
2495 the minimum number of required functions. For example, we could implement
2496 a simple read-only QStringList-based model that provides a list of strings
2497 to a QListView widget. In such a case, we only need to implement the
2498 rowCount() function to return the number of items in the list, and the
2499 data() function to retrieve items from the list.
2500
2501 Since the model represents a one-dimensional structure, the rowCount()
2502 function returns the total number of items in the model. The columnCount()
2503 function is implemented for interoperability with all kinds of views, but
2504 by default informs views that the model contains only one column.
2505
2506 \section1 Subclassing
2507
2508 \bold{Note:} Some general guidelines for subclassing models are
2509 available in the \l{Model Subclassing Reference}.
2510
2511 When subclassing QAbstractListModel, you must provide implementations
2512 of the rowCount() and data() functions. Well behaved models also provide
2513 a headerData() implementation.
2514
2515 For editable list models, you must also provide an implementation of
2516 setData(), implement the flags() function so that it returns a value
2517 containing \l{Qt::ItemFlags}{Qt::ItemIsEditable}.
2518
2519 Note that QAbstractListModel provides a default implementation of
2520 columnCount() that informs views that there is only a single column
2521 of items in this model.
2522
2523 Models that provide interfaces to resizable list-like data structures
2524 can provide implementations of insertRows() and removeRows(). When
2525 implementing these functions, it is important to call the appropriate
2526 functions so that all connected views are aware of any changes:
2527
2528 \list
2529 \o An insertRows() implementation must call beginInsertRows()
2530 \e before inserting new rows into the data structure, and it must
2531 call endInsertRows() \e{immediately afterwards}.
2532 \o A removeRows() implementation must call beginRemoveRows()
2533 \e before the rows are removed from the data structure, and it must
2534 call endRemoveRows() \e{immediately afterwards}.
2535 \endlist
2536
2537 \sa {Model Classes}, {Model Subclassing Reference}, QAbstractItemView,
2538 QAbstractTableModel, {Item Views Puzzle Example}
2539*/
2540
2541/*!
2542 Constructs an abstract list model with the given \a parent.
2543*/
2544
2545QAbstractListModel::QAbstractListModel(QObject *parent)
2546 : QAbstractItemModel(parent)
2547{
2548
2549}
2550
2551/*!
2552 \internal
2553
2554 Constructs an abstract list model with \a dd and the given \a parent.
2555*/
2556
2557QAbstractListModel::QAbstractListModel(QAbstractItemModelPrivate &dd, QObject *parent)
2558 : QAbstractItemModel(dd, parent)
2559{
2560
2561}
2562
2563/*!
2564 Destroys the abstract list model.
2565*/
2566
2567QAbstractListModel::~QAbstractListModel()
2568{
2569
2570}
2571
2572/*!
2573 \fn QModelIndex QAbstractListModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const
2574
2575 Returns the index of the data in \a row and \a column with \a parent.
2576
2577 \sa parent()
2578*/
2579
2580QModelIndex QAbstractListModel::index(int row, int column, const QModelIndex &parent) const
2581{
2582 return hasIndex(row, column, parent) ? createIndex(row, column, 0) : QModelIndex();
2583}
2584
2585/*!
2586 Returns the parent of the model item with the given \a index.
2587
2588 \sa index() hasChildren()
2589*/
2590
2591QModelIndex QAbstractListModel::parent(const QModelIndex & /* index */) const
2592{
2593 return QModelIndex();
2594}
2595
2596/*!
2597 \internal
2598
2599 Returns the number of columns in the list with the given \a parent.
2600
2601 \sa rowCount()
2602*/
2603
2604int QAbstractListModel::columnCount(const QModelIndex &parent) const
2605{
2606 return parent.isValid() ? 0 : 1;
2607}
2608
2609bool QAbstractListModel::hasChildren(const QModelIndex &parent) const
2610{
2611 return parent.isValid() ? false : (rowCount() > 0);
2612}
2613
2614/*!
2615 \typedef QModelIndexList
2616 \relates QModelIndex
2617
2618 Synonym for QList<QModelIndex>.
2619*/
2620
2621/*!
2622 \reimp
2623*/
2624bool QAbstractTableModel::dropMimeData(const QMimeData *data, Qt::DropAction action,
2625 int row, int column, const QModelIndex &parent)
2626{
2627 if (!data || !(action == Qt::CopyAction || action == Qt::MoveAction))
2628 return false;
2629
2630 QStringList types = mimeTypes();
2631 if (types.isEmpty())
2632 return false;
2633 QString format = types.at(0);
2634 if (!data->hasFormat(format))
2635 return false;
2636
2637 QByteArray encoded = data->data(format);
2638 QDataStream stream(&encoded, QIODevice::ReadOnly);
2639
2640 // if the drop is on an item, replace the data in the items
2641 if (parent.isValid() && row == -1 && column == -1) {
2642 int top = INT_MAX;
2643 int left = INT_MAX;
2644 QVector<int> rows, columns;
2645 QVector<QMap<int, QVariant> > data;
2646
2647 while (!stream.atEnd()) {
2648 int r, c;
2649 QMap<int, QVariant> v;
2650 stream >> r >> c >> v;
2651 rows.append(r);
2652 columns.append(c);
2653 data.append(v);
2654 top = qMin(r, top);
2655 left = qMin(c, left);
2656 }
2657
2658 for (int i = 0; i < data.size(); ++i) {
2659 int r = (rows.at(i) - top) + parent.row();
2660 int c = (columns.at(i) - left) + parent.column();
2661 if (hasIndex(r, c))
2662 setItemData(index(r, c), data.at(i));
2663 }
2664
2665 return true;
2666 }
2667
2668 // otherwise insert new rows for the data
2669 return decodeData(row, column, parent, stream);
2670}
2671
2672/*!
2673 \reimp
2674*/
2675bool QAbstractListModel::dropMimeData(const QMimeData *data, Qt::DropAction action,
2676 int row, int column, const QModelIndex &parent)
2677{
2678 if (!data || !(action == Qt::CopyAction || action == Qt::MoveAction))
2679 return false;
2680
2681 QStringList types = mimeTypes();
2682 if (types.isEmpty())
2683 return false;
2684 QString format = types.at(0);
2685 if (!data->hasFormat(format))
2686 return false;
2687
2688 QByteArray encoded = data->data(format);
2689 QDataStream stream(&encoded, QIODevice::ReadOnly);
2690
2691 // if the drop is on an item, replace the data in the items
2692 if (parent.isValid() && row == -1 && column == -1) {
2693 int top = INT_MAX;
2694 int left = INT_MAX;
2695 QVector<int> rows, columns;
2696 QVector<QMap<int, QVariant> > data;
2697
2698 while (!stream.atEnd()) {
2699 int r, c;
2700 QMap<int, QVariant> v;
2701 stream >> r >> c >> v;
2702 rows.append(r);
2703 columns.append(c);
2704 data.append(v);
2705 top = qMin(r, top);
2706 left = qMin(c, left);
2707 }
2708
2709 for (int i = 0; i < data.size(); ++i) {
2710 int r = (rows.at(i) - top) + parent.row();
2711 if (columns.at(i) == left && hasIndex(r, 0))
2712 setItemData(index(r), data.at(i));
2713 }
2714
2715 return true;
2716 }
2717
2718 if (row == -1)
2719 row = rowCount(parent);
2720
2721 // otherwise insert new rows for the data
2722 return decodeData(row, column, parent, stream);
2723}
2724
2725/*!
2726 \fn QAbstractItemModel::modelAboutToBeReset()
2727 \since 4.2
2728
2729 This signal is emitted when reset() is called, before the model's internal
2730 state (e.g. persistent model indexes) has been invalidated.
2731
2732 \sa reset(), modelReset()
2733*/
2734
2735/*!
2736 \fn QAbstractItemModel::modelReset()
2737 \since 4.1
2738
2739 This signal is emitted when reset() is called, after the model's internal
2740 state (e.g. persistent model indexes) has been invalidated.
2741
2742 \sa reset(), modelAboutToBeReset()
2743*/
2744
2745/*!
2746 \fn bool QModelIndex::operator<(const QModelIndex &other) const
2747 \since 4.1
2748
2749 Returns true if this model index is smaller than the \a other
2750 model index; otherwise returns false.
2751*/
2752
2753/*!
2754 \fn uint qHash(const QPersistentModelIndex &index)
2755 \since 4.5
2756
2757 Returns a hash of the QPersistentModelIndex
2758 */
2759
2760
2761/*!
2762 \internal
2763 QHash::insertMulti insert the value before the old value. and find() return the new value.
2764 We need insertMultiAtEnd because we don't want to overwrite the old one, which should be removed later
2765
2766 There should be only one instance QPersistentModelIndexData per index, but in some intermediate state there may be
2767 severals of PersistantModelIndex pointing to the same index, but one is already updated, and the other one is not.
2768 This make sure than when updating the first one we don't overwrite the second one in the hash, and the second one
2769 will be updated right later.
2770 */
2771void QAbstractItemModelPrivate::Persistent::insertMultiAtEnd(const QModelIndex& key, QPersistentModelIndexData *data)
2772{
2773 QHash<QModelIndex,QPersistentModelIndexData *>::iterator newIt =
2774 indexes.insertMulti(key, data);
2775 QHash<QModelIndex,QPersistentModelIndexData *>::iterator it = newIt + 1;
2776 while (it != indexes.end() && it.key() == key) {
2777 qSwap(*newIt,*it);
2778 newIt = it;
2779 ++it;
2780 }
2781}
2782
2783QT_END_NAMESPACE
Note: See TracBrowser for help on using the repository browser.