QAbstractItemModel Class

The QAbstractItemModel class provides the abstract interface for item model classes. More…

List of all members, including inherited members

Public Types

Public Functions

Public Slots

Signals

Protected Functions

Protected Slots

Detailed Description

An item model presents data as a table of items, where each item can have a table of child items. Subclasses implement index(), parent(), rowCount(), columnCount() and data(); editable models also implement setData() and flags(), and resizable models insertRows() and removeRows().

Changes are announced with the begin and end functions, such as beginInsertRows() and endInsertRows(), which emit the matching signals and keep persistent indexes up to date:

bool MyModel::insertRows(int row, int count, const QModelIndex &parent)
{
    beginInsertRows(parent, row, row + count - 1);
    m_items.insert(row, count, QString());
    endInsertRows();
    return true;
}

See also QModelIndex, QAbstractListModel, QAbstractTableModel and QSortFilterProxyModel.

Differences from Qt

Member Type Documentation

enum QAbstractItemModel::CheckIndexOption

This function was introduced in 5.11.

typedef QAbstractItemModel::CheckIndexOptions

The CheckIndexOptions type is a typedef for QFlags<CheckIndexOption>. It stores an OR combination of CheckIndexOption values.

enum QAbstractItemModel::LayoutChangeHint

Member Function Documentation

[explicit] QAbstractItemModel::QAbstractItemModel(QObject *parent = nullptr)

Constructs an item model with the given parent.

[override] QAbstractItemModel::~QAbstractItemModel()

Destroys the model. Persistent indexes of the model become invalid.

[protected] void QAbstractItemModel::beginInsertColumns(const QModelIndex &parent, int first, int last)

Begins inserting columns first to last under parent: emits columnsAboutToBeInserted(). Call endInsertColumns() afterwards.

[protected] void QAbstractItemModel::beginInsertRows(const QModelIndex &parent, int first, int last)

Begins inserting rows first to last under parent: emits rowsAboutToBeInserted(). Call endInsertRows() after inserting the rows.

[protected] bool QAbstractItemModel::beginMoveColumns(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationColumn)

Begins moving columns sourceFirst to sourceLast under sourceParent to before column destinationColumn under destinationParent, and emits columnsAboutToBeMoved(). Returns false, doing nothing, if the move is not possible; otherwise call endMoveColumns() afterwards.

[protected] bool QAbstractItemModel::beginMoveRows(const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationRow)

Begins moving rows sourceFirst to sourceLast under sourceParent to before row destinationRow under destinationParent, and emits rowsAboutToBeMoved(). Returns false, doing nothing, if the move is not possible (the destination is inside the moved rows, or the move would not change anything); otherwise call endMoveRows() after moving the rows.

[protected] void QAbstractItemModel::beginRemoveColumns(const QModelIndex &parent, int first, int last)

Begins removing columns first to last under parent: emits columnsAboutToBeRemoved(). Call endRemoveColumns() afterwards.

[protected] void QAbstractItemModel::beginRemoveRows(const QModelIndex &parent, int first, int last)

Begins removing rows first to last under parent: emits rowsAboutToBeRemoved(). Call endRemoveRows() after removing the rows.

[protected] void QAbstractItemModel::beginResetModel()

Begins resetting the model: emits modelAboutToBeReset(). Call endResetModel() after changing the data.

[virtual] QModelIndex QAbstractItemModel::buddy(const QModelIndex &index) const

Returns the item that is edited in place of the item at index; the default returns index.

[virtual] bool QAbstractItemModel::canDropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent) const

Returns true if data can be dropped with action at row and column under parent; otherwise returns false. The default checks the format and the action.

[virtual] bool QAbstractItemModel::canFetchMore(const QModelIndex &parent) const

Returns true if more items can be fetched under parent; the default returns false.

[protected] void QAbstractItemModel::changePersistentIndex(const QModelIndex &from, const QModelIndex &to)

Changes the persistent indexes that refer to from so that they refer to to. An invalid to invalidates them. Models call this between layoutAboutToBeChanged() and layoutChanged().

[protected] void QAbstractItemModel::changePersistentIndexList(const QModelIndexList &from, const QModelIndexList &to)

Changes the persistent indexes that refer to the indexes in from to the corresponding indexes in to.

This function was introduced in 4.1.

bool QAbstractItemModel::checkIndex(const QModelIndex &index, CheckIndexOptions options = CheckIndexOption::NoOption) const

Returns true if index is a valid index of this model, checked according to options; otherwise prints a warning and returns false. An invalid index passes unless IndexIsValid is set.

This function was introduced in 5.11.

[virtual] bool QAbstractItemModel::clearItemData(const QModelIndex &index)

Removes the data of all roles of the item at index and returns true on success. The default returns false.

This function was introduced in 6.0.

[virtual] int QAbstractItemModel::columnCount(const QModelIndex &parent = QModelIndex()) const

Returns the number of columns under parent.

[signal] void QAbstractItemModel::columnsAboutToBeInserted(const QModelIndex &parent, int first, int last)

This signal is emitted before columns first to last are inserted under parent.

[signal] void QAbstractItemModel::columnsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn)

This signal is emitted before columns sourceStart to sourceEnd under sourceParent move to before column destinationColumn under destinationParent.

[signal] void QAbstractItemModel::columnsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

This signal is emitted before columns first to last are removed from under parent.

[signal] void QAbstractItemModel::columnsInserted(const QModelIndex &parent, int first, int last)

This signal is emitted after columns first to last were inserted under parent.

[signal] void QAbstractItemModel::columnsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int column)

This signal is emitted after columns start to end under parent moved to before column column under destination.

[signal] void QAbstractItemModel::columnsRemoved(const QModelIndex &parent, int first, int last)

This signal is emitted after columns first to last were removed from under parent.

[protected] QModelIndex QAbstractItemModel::createIndex(int row, int column, const void *ptr = nullptr) const

Creates an index of this model for row and column that stores the pointer ptr.

[protected] QModelIndex QAbstractItemModel::createIndex(int row, int column, quintptr id) const

This is an overloaded function.

Creates an index of this model for row and column that stores the integer id.

[virtual] QVariant QAbstractItemModel::data(const QModelIndex &index, int role = Qt::DisplayRole) const

Returns the data of the item at index for role, or an invalid QVariant.

See also setData() and Qt::ItemDataRole.

[signal] void QAbstractItemModel::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

This signal is emitted when the data of the items from topLeft to bottomRight changes. roles lists the roles that changed; an empty list means all of them.

[virtual] bool QAbstractItemModel::dropMimeData(const QMimeData *data, Qt::DropAction action, int row, int column, const QModelIndex &parent)

Inserts the items in data, dropped with action, at row and column under parent and returns true on success. The default understands the format of mimeData(): it inserts rows and sets the item data.

[protected] void QAbstractItemModel::endInsertColumns()

Ends inserting columns: updates persistent indexes and emits columnsInserted().

[protected] void QAbstractItemModel::endInsertRows()

Ends inserting rows: updates persistent indexes and emits rowsInserted().

[protected] void QAbstractItemModel::endMoveColumns()

Ends moving columns: updates persistent indexes and emits columnsMoved().

[protected] void QAbstractItemModel::endMoveRows()

Ends moving rows: updates persistent indexes and emits rowsMoved().

[protected] void QAbstractItemModel::endRemoveColumns()

Ends removing columns: invalidates or updates persistent indexes and emits columnsRemoved().

[protected] void QAbstractItemModel::endRemoveRows()

Ends removing rows: invalidates the persistent indexes of removed items, updates the others and emits rowsRemoved().

[protected] void QAbstractItemModel::endResetModel()

Ends resetting the model: invalidates all persistent indexes, calls resetInternalData() and emits modelReset().

[virtual] void QAbstractItemModel::fetchMore(const QModelIndex &parent)

Fetches more items under parent, for models that load data incrementally. The default does nothing.

[virtual] Qt::ItemFlags QAbstractItemModel::flags(const QModelIndex &index) const

Returns the flags of the item at index: Qt::ItemIsSelectable and Qt::ItemIsEnabled for a valid index, and none for an invalid one.

[virtual] bool QAbstractItemModel::hasChildren(const QModelIndex &parent = QModelIndex()) const

Returns true if parent has child items; otherwise returns false. The default asks rowCount() and columnCount().

bool QAbstractItemModel::hasIndex(int row, int column, const QModelIndex &parent = QModelIndex()) const

Returns true if row and column are inside the table under parent; otherwise returns false.

[virtual] QVariant QAbstractItemModel::headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const

Returns the header data of section in orientation for role. The default returns the section number counted from 1 for Qt::DisplayRole.

[signal] void QAbstractItemModel::headerDataChanged(Qt::Orientation orientation, int first, int last)

This signal is emitted when the header sections first to last of orientation change.

[virtual] QModelIndex QAbstractItemModel::index(int row, int column, const QModelIndex &parent = QModelIndex()) const

Returns the index of the item at row and column under parent. Subclasses implement it with createIndex().

See also parent() and createIndex().

bool QAbstractItemModel::insertColumn(int column, const QModelIndex &parent = QModelIndex())

Inserts one column before column under parent.

[virtual] bool QAbstractItemModel::insertColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Inserts count columns before column under parent and returns true on success. The default returns false.

bool QAbstractItemModel::insertRow(int row, const QModelIndex &parent = QModelIndex())

Inserts one row before row under parent.

[virtual] bool QAbstractItemModel::insertRows(int row, int count, const QModelIndex &parent = QModelIndex())

Inserts count rows before row under parent and returns true on success. The default returns false; resizable models implement it with beginInsertRows() and endInsertRows().

[virtual] QMap<int, QVariant> QAbstractItemModel::itemData(const QModelIndex &index) const

Returns the data of the item at index for all predefined roles that have data.

[signal] void QAbstractItemModel::layoutAboutToBeChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

This signal is emitted before the items under parents (all items if empty) are rearranged; hint describes how.

[signal] void QAbstractItemModel::layoutChanged(const QList<QPersistentModelIndex> &parents = QList<QPersistentModelIndex>(), QAbstractItemModel::LayoutChangeHint hint = QAbstractItemModel::NoLayoutChangeHint)

This signal is emitted after the items under parents (all items if empty) were rearranged; hint describes how.

See also layoutAboutToBeChanged().

[virtual] QModelIndexList QAbstractItemModel::match(const QModelIndex &start, int role, const QVariant &value, int hits = 1, Qt::MatchFlags flags = Qt::MatchFlags(Qt::MatchStartsWith | Qt::MatchWrap)) const

Returns up to hits indexes of items in the column of start, under its parent and starting at its row, whose data for role matches value according to flags. A hits of -1 returns all matches. With Qt::MatchWrap the search wraps to the first row, and with Qt::MatchRecursive child items are searched too.

[virtual] QMimeData * QAbstractItemModel::mimeData(const QModelIndexList &indexes) const

Returns a new QMimeData object with the data of the items at indexes, or nullptr if indexes is empty. The caller owns the object.

[virtual] QStringList QAbstractItemModel::mimeTypes() const

Returns the MIME types that mimeData() produces; the default is the Qt item list type application/x-qabstractitemmodeldatalist.

[signal] void QAbstractItemModel::modelAboutToBeReset()

This signal is emitted when the model is about to be reset.

[signal] void QAbstractItemModel::modelReset()

This signal is emitted after the model was reset.

bool QAbstractItemModel::moveColumn(const QModelIndex &sourceParent, int sourceColumn, const QModelIndex &destinationParent, int destinationChild)

Moves the column sourceColumn under sourceParent to before destinationChild under destinationParent.

This function was introduced in 5.11.

[virtual] bool QAbstractItemModel::moveColumns(const QModelIndex &sourceParent, int sourceColumn, int count, const QModelIndex &destinationParent, int destinationChild)

Moves count columns from sourceColumn under sourceParent to before destinationChild under destinationParent and returns true on success. The default returns false.

This function was introduced in 5.11.

bool QAbstractItemModel::moveRow(const QModelIndex &sourceParent, int sourceRow, const QModelIndex &destinationParent, int destinationChild)

Moves the row sourceRow under sourceParent to before destinationChild under destinationParent.

This function was introduced in 5.11.

[virtual] bool QAbstractItemModel::moveRows(const QModelIndex &sourceParent, int sourceRow, int count, const QModelIndex &destinationParent, int destinationChild)

Moves count rows from sourceRow under sourceParent to before destinationChild under destinationParent and returns true on success. The default returns false.

This function was introduced in 5.11.

[virtual] QModelIndex QAbstractItemModel::parent(const QModelIndex &child) const

Returns the parent of the item at child, or an invalid index for a top-level item.

[protected] QModelIndexList QAbstractItemModel::persistentIndexList() const

Returns the indexes currently held by persistent indexes of the model.

This function was introduced in 4.2.

bool QAbstractItemModel::removeColumn(int column, const QModelIndex &parent = QModelIndex())

Removes the column column under parent.

[virtual] bool QAbstractItemModel::removeColumns(int column, int count, const QModelIndex &parent = QModelIndex())

Removes count columns from column under parent and returns true on success. The default returns false.

bool QAbstractItemModel::removeRow(int row, const QModelIndex &parent = QModelIndex())

Removes the row row under parent.

[virtual] bool QAbstractItemModel::removeRows(int row, int count, const QModelIndex &parent = QModelIndex())

Removes count rows from row under parent and returns true on success. The default returns false.

[slot, virtual, protected] void QAbstractItemModel::resetInternalData()

Called when the model is reset, after modelAboutToBeReset() and before modelReset(), so that subclasses can clear their internal data. The default does nothing.

This function was introduced in 5.0.

[slot, virtual] void QAbstractItemModel::revert()

Lets the model discard cached changes. The default does nothing.

[virtual] QHash<int, QByteArray> QAbstractItemModel::roleNames() const

Returns the names of the roles, as used by declarative frontends. The defaults are "display", "decoration", "edit", "toolTip", "statusTip" and "whatsThis".

This function was introduced in 4.6.

[virtual] int QAbstractItemModel::rowCount(const QModelIndex &parent = QModelIndex()) const

Returns the number of rows under parent.

[signal] void QAbstractItemModel::rowsAboutToBeInserted(const QModelIndex &parent, int first, int last)

This signal is emitted before rows first to last are inserted under parent.

[signal] void QAbstractItemModel::rowsAboutToBeMoved(const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow)

This signal is emitted before rows sourceStart to sourceEnd under sourceParent move to before row destinationRow under destinationParent.

[signal] void QAbstractItemModel::rowsAboutToBeRemoved(const QModelIndex &parent, int first, int last)

This signal is emitted before rows first to last are removed from under parent.

[signal] void QAbstractItemModel::rowsInserted(const QModelIndex &parent, int first, int last)

This signal is emitted after rows first to last were inserted under parent.

[signal] void QAbstractItemModel::rowsMoved(const QModelIndex &parent, int start, int end, const QModelIndex &destination, int row)

This signal is emitted after rows start to end under parent moved to before row row under destination.

[signal] void QAbstractItemModel::rowsRemoved(const QModelIndex &parent, int first, int last)

This signal is emitted after rows first to last were removed from under parent.

[virtual] bool QAbstractItemModel::setData(const QModelIndex &index, const QVariant &value, int role = Qt::EditRole)

Sets the data of the item at index for role to value and returns true on success. The default does nothing and returns false; editable models emit dataChanged() when they change data.

[virtual] bool QAbstractItemModel::setHeaderData(int section, Qt::Orientation orientation, const QVariant &value, int role = Qt::EditRole)

Sets the header data of section in orientation for role to value and returns true on success. The default returns false.

[virtual] bool QAbstractItemModel::setItemData(const QModelIndex &index, const QMap<int, QVariant> &roles)

Sets the data of the item at index for each role in roles and returns true if all of them succeeded.

[virtual] QModelIndex QAbstractItemModel::sibling(int row, int column, const QModelIndex &idx) const

Returns the index at row and column under the parent of idx.

[virtual] void QAbstractItemModel::sort(int column, Qt::SortOrder order = Qt::AscendingOrder)

Sorts the model by column in order. The default does nothing.

[virtual] QSize QAbstractItemModel::span(const QModelIndex &index) const

Returns the number of rows and columns the item at index spans; the default is one of each.

[slot, virtual] bool QAbstractItemModel::submit()

Lets the model write cached changes to its storage and returns true on success. The default returns true.

[virtual] Qt::DropActions QAbstractItemModel::supportedDragActions() const

Returns the drag actions the model supports; the default is supportedDropActions().

[virtual] Qt::DropActions QAbstractItemModel::supportedDropActions() const

Returns the drop actions the model supports; the default is Qt::CopyAction.