Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
QStandardItemModel Class Reference

The QStandardItemModel class provides a generic model for storing custom data. More...

#include <qstandarditemmodel.h>

Inheritance diagram for QStandardItemModel:
Collaboration diagram for QStandardItemModel:

Signals

void itemChanged (QStandardItem *item)
void dataChanged (const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList< int > &roles=QList< int >())
 This signal is emitted whenever the data in an existing item changes.
void headerDataChanged (Qt::Orientation orientation, int firstfirst, int last)
 This signal is emitted whenever a header is changed.
void layoutChanged (const QList< QPersistentModelIndex > &parents=QList< QPersistentModelIndex >(), QAbstractItemModel::LayoutChangeHint hint=QAbstractItemModel::NoLayoutChangeHint)
void layoutAboutToBeChanged (const QList< QPersistentModelIndex > &parents=QList< QPersistentModelIndex >(), QAbstractItemModel::LayoutChangeHint hint=QAbstractItemModel::NoLayoutChangeHint)
void rowsAboutToBeInserted (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted just before rows are inserted into the model.
void rowsInserted (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted after rows have been inserted into the model.
void rowsAboutToBeRemoved (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted just before rows are removed from the model.
void rowsRemoved (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted after rows have been removed from the model.
void columnsAboutToBeInserted (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted just before columns are inserted into the model.
void columnsInserted (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted after columns have been inserted into the model.
void columnsAboutToBeRemoved (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted just before columns are removed from the model.
void columnsRemoved (const QModelIndex &parent, int firstfirst, int last, QPrivateSignal)
 This signal is emitted after columns have been removed from the model.
void modelAboutToBeReset (QPrivateSignal)
void modelReset (QPrivateSignal)
void rowsAboutToBeMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow, QPrivateSignal)
void rowsMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationRow, QPrivateSignal)
void columnsAboutToBeMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn, QPrivateSignal)
void columnsMoved (const QModelIndex &sourceParent, int sourceStart, int sourceEnd, const QModelIndex &destinationParent, int destinationColumn, QPrivateSignal)
Signals inherited from QObject
void destroyed (QObject *=nullptr)
 This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.
void objectNameChanged (const QString &objectName, QPrivateSignal)
 This signal is emitted after the object's name has been changed.

Public Member Functions

 QStandardItemModel (QObject *parent=nullptr)
 Constructs a new item model with the given parent.
 QStandardItemModel (int rows, int columns, QObject *parent=nullptr)
 Constructs a new item model that initially has rows rows and columns columns, and that has the given parent.
 ~QStandardItemModel ()
 Destructs the model.
void setItemRoleNames (const QHash< int, QByteArray > &roleNames)
 Sets the item role names to roleNames.
QHash< int, QByteArray > roleNames () const override
 \reimp
QModelIndex index (int rowrow, int columncolumn, const QModelIndex &parent=QModelIndex()) const override
 \reimp
QModelIndex parent (const QModelIndex &child) const override
 \reimp
int rowCount (const QModelIndex &parent=QModelIndex()) const override
 \reimp
int columnCount (const QModelIndex &parent=QModelIndex()) const override
 \reimp
bool hasChildren (const QModelIndex &parent=QModelIndex()) const override
 \reimp
QVariant data (const QModelIndex &indexindex, int role=Qt::DisplayRole) const override
 \reimp
void multiData (const QModelIndex &indexindex, QModelRoleDataSpan roleDataSpan) const override
 \reimp
bool setData (const QModelIndex &indexindex, const QVariant &valuevalue, int role=Qt::EditRole) override
 \reimp
bool clearItemData (const QModelIndex &indexindex) override
 \reimp
QVariant headerData (int section, Qt::Orientation orientation, int role=Qt::DisplayRole) const override
 \reimp
bool setHeaderData (int section, Qt::Orientation orientation, const QVariant &valuevalue, int role=Qt::EditRole) override
 \reimp
bool insertRows (int rowrow, int countcount, const QModelIndex &parent=QModelIndex()) override
 \reimp
bool insertColumns (int columncolumn, int countcount, const QModelIndex &parent=QModelIndex()) override
 \reimp
bool removeRows (int rowrow, int countcount, const QModelIndex &parent=QModelIndex()) override
 \reimp
bool removeColumns (int columncolumn, int countcount, const QModelIndex &parent=QModelIndex()) override
 \reimp
Qt::ItemFlags flags (const QModelIndex &indexindex) const override
 \reimp
Qt::DropActions supportedDropActions () const override
 \reimp
QMap< int, QVariant > itemData (const QModelIndex &indexindex) const override
 \reimp
bool setItemData (const QModelIndex &indexindex, const QMap< int, QVariant > &roles) override
 \reimp
void clear ()
 Removes all items (including header items) from the model and sets the number of rows and columns to zero.
void sort (int columncolumn, Qt::SortOrder orderorder=Qt::AscendingOrder) override
 \reimp
QStandardItem * itemFromIndex (const QModelIndex &indexindex) const
QModelIndex indexFromItem (const QStandardItem *item) const
QStandardItem * item (int rowrow, int columncolumn=0) const
void setItem (int rowrow, int columncolumn, QStandardItem *item)
void setItem (int rowrow, QStandardItem *item)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QStandardItem * invisibleRootItem () const
QStandardItem * horizontalHeaderItem (int columncolumn) const
void setHorizontalHeaderItem (int columncolumn, QStandardItem *item)
QStandardItem * verticalHeaderItem (int rowrow) const
void setVerticalHeaderItem (int rowrow, QStandardItem *item)
void setHorizontalHeaderLabels (const QStringList &labels)
void setVerticalHeaderLabels (const QStringList &labels)
void setRowCount (int rows)
void setColumnCount (int columns)
void appendRow (const QList< QStandardItem * > &items)
void appendColumn (const QList< QStandardItem * > &items)
void appendRow (QStandardItem *item)
void insertRow (int rowrow, const QList< QStandardItem * > &items)
void insertColumn (int columncolumn, const QList< QStandardItem * > &items)
void insertRow (int rowrow, QStandardItem *item)
bool insertRow (int rowrow, const QModelIndex &parent=QModelIndex())
 Inserts a single row before the given row in the child items of the parent specified.
bool insertColumn (int columncolumn, const QModelIndex &parent=QModelIndex())
 Inserts a single column before the given column in the child items of the parent specified.
QStandardItem * takeItem (int rowrow, int columncolumn=0)
QList< QStandardItem * > takeRow (int rowrow)
QList< QStandardItem * > takeColumn (int columncolumn)
QStandardItem * takeHorizontalHeaderItem (int columncolumn)
QStandardItem * takeVerticalHeaderItem (int rowrow)
const QStandardItem * itemPrototype () const
void setItemPrototype (const QStandardItem *item)
QList< QStandardItem * > findItems (const QString &text, Qt::MatchFlags flagsflags=Qt::MatchExactly, int columncolumn=0) const
int sortRole () const
void setSortRole (int role)
QBindable< int > bindableSortRole ()
QStringList mimeTypes () const override
 \reimp
QMimeData * mimeData (const QModelIndexList &indexes) const override
 \reimp
bool dropMimeData (const QMimeData *datadata, Qt::DropAction action, int rowrow, int columncolumn, const QModelIndex &parent) override
 \reimp
QObject * parent () const
 Returns a pointer to the parent object.
Public Member Functions inherited from QAbstractItemModel
Q_INVOKABLE Q_REVISION (6, 4) virtual bool insertRows(int row
Q_INVOKABLE Q_REVISION (6, 4) virtual bool insertColumns(int column
Q_INVOKABLE Q_REVISION (6, 4) virtual bool removeRows(int row
Q_INVOKABLE Q_REVISION (6, 4) virtual bool removeColumns(int column
Q_INVOKABLE Q_REVISION (6, 4) virtual bool moveRows(const QModelIndex &sourceParent
Q_INVOKABLE Q_REVISION (6, 4) virtual bool moveColumns(const QModelIndex &sourceParent
Q_INVOKABLE Q_REVISION (6, 4) inline bool insertRow(int row
Q_INVOKABLE Q_REVISION (6, 4) inline bool insertColumn(int column
Q_INVOKABLE Q_REVISION (6, 4) inline bool removeRow(int row
Q_INVOKABLE Q_REVISION (6, 4) inline bool removeColumn(int column
Q_INVOKABLE Q_REVISION (6, 4) inline bool moveRow(const QModelIndex &sourceParent
Q_INVOKABLE Q_REVISION (6, 4) inline bool moveColumn(const QModelIndex &sourceParent
Q_INVOKABLE Q_REVISION (6, 4) virtual void sort(int column
QObject * parent () const
 Returns a pointer to the parent object.
 QAbstractItemModel (QObject *parent=nullptr)
 Constructs an abstract item model with the given parent.
virtual ~QAbstractItemModel ()
 Destroys the abstract item model.
Q_INVOKABLE bool hasIndex (int rowrow, int columncolumn, const QModelIndex &parent=QModelIndex()) const
 Returns {true} if the model returns a valid QModelIndex for row and column with parent, otherwise returns {false}.
virtual Q_INVOKABLE QModelIndex sibling (int rowrow, int columncolumn, const QModelIndex &idx) const
 Returns the sibling at row and column for the item at index, or an invalid QModelIndex if there is no sibling at that location.
virtual bool canDropMimeData (const QMimeData *datadata, Qt::DropAction action, int rowrow, int columncolumn, const QModelIndex &parent) const
 Returns {true} if a model can accept a drop of the data.
virtual Qt::DropActions supportedDragActions () const
 Returns the actions supported by the data in this model.
virtual Q_INVOKABLE void fetchMore (const QModelIndex &parent)
 Fetches any available data for the items with the parent specified by the parent index.
virtual Q_INVOKABLE bool canFetchMore (const QModelIndex &parent) const
 Returns {true} if there is more data available for parent; otherwise returns {false}.
virtual QModelIndex buddy (const QModelIndex &indexindex) const
 Returns a model index for the buddy of the item represented by index.
virtual Q_INVOKABLE QModelIndexList match (const QModelIndex &startstart, int role, const QVariant &valuevalue, int hits=1, Qt::MatchFlags flagsflags=Qt::MatchFlags(Qt::MatchStartsWith|Qt::MatchWrap)) const
 Returns a list of indexes for the items in the column of the start index where data stored under the given role matches the specified value.
virtual QSize span (const QModelIndex &indexindex) const
 Returns the row and column span of the item represented by index.
bool checkIndex (const QModelIndex &indexindex, CheckIndexOptions options=CheckIndexOption::NoOption) const
Public Member Functions inherited from QObject
Q_INVOKABLE QObject (QObject *parent=nullptr)
 Constructs an object with parent object parent.
virtual ~QObject ()
 Destroys the object, deleting all its child objects.
virtual bool event (QEvent *event)
 This virtual function receives events to an object and should return true if the event e was recognized and processed.
virtual bool eventFilter (QObject *watched, QEvent *eventevent)
 Filters events if this object has been installed as an event filter for the watched object.
QString objectName () const
Q_WEAK_OVERLOAD void setObjectName (const QString &namename)
 Sets the object's name to name.
void setObjectName (QAnyStringView namename)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
QBindable< QString > bindableObjectName ()
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false.
bool isWindowType () const
 Returns true if the object is a window; otherwise returns false.
bool isQuickItemType () const
 Returns true if the object is a QQuickItem; otherwise returns false.
bool isQmlExposed () const noexcept
 Returns whether the object has been created by the QML engine or ownership has been explicitly set via QJSEngine::setObjectOwnership().
bool signalsBlocked () const noexcept
 Returns true if signals are blocked; otherwise returns false.
bool blockSignals (bool b) noexcept
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).
QThread * thread () const
 Returns the thread in which the object lives.
bool moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
 Changes the thread affinity for this object and its children and returns true on success.
int startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
 This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.
int startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)
void killTimer (int idid)
 Kills the timer with timer identifier, id.
void killTimer (Qt::TimerId idid)
template<typename T>
T findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.
template<typename T>
QList< T > findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.
template<typename T>
T findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
template<typename T>
QList< T > findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
const QObjectList & children () const
 Returns a list of child objects.
void setParent (QObject *parent)
 Makes the object a child of parent.
void installEventFilter (QObject *filterObj)
 Installs an event filter filterObj on this object.
void removeEventFilter (QObject *objobj)
 Removes an event filter object obj from this object.
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType typetype=Qt::AutoConnection) const
bool disconnect (const char *signal=nullptr, const QObject *receiver=nullptr, const char *member=nullptr) const
bool disconnect (const QObject *receiver, const char *member=nullptr) const
void dumpObjectTree () const
 Dumps a tree of children to the debug output.
void dumpObjectInfo () const
 Dumps information about signal connections, etc.
bool setProperty (const char *namename, const QVariant &valuevalue)
 Sets the value of the object's name property to value.
bool setProperty (const char *namename, QVariant &&valuevalue)
QVariant property (const char *namename) const
 Returns the value of the object's name property.
QList< QByteArray > dynamicPropertyNames () const
QBindingStorage * bindingStorage ()
const QBindingStorage * bindingStorage () const
QObject * parent () const
 Returns a pointer to the parent object.
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false.

Protected Member Functions

 QStandardItemModel (QStandardItemModelPrivate &dd, QObject *parent=nullptr)
 QAbstractItemModel (QAbstractItemModelPrivate &dd, QObject *parent=nullptr)
QModelIndex createIndex (int rowrow, int columncolumn, const void *data=nullptr) const
 Creates a model index for the given row and column with the internal pointer ptr.
QModelIndex createIndex (int rowrow, int columncolumn, quintptr idid) const
 Creates a model index for the given row and column with the internal identifier, id.
void encodeData (const QModelIndexList &indexes, QDataStream &streamstream) const
bool decodeData (int rowrow, int columncolumn, const QModelIndex &parent, QDataStream &streamstream)
void beginInsertRows (const QModelIndex &parent, int firstfirst, int last)
 Begins a row insertion operation.
void endInsertRows ()
 Ends a row insertion operation.
void beginRemoveRows (const QModelIndex &parent, int firstfirst, int last)
 Begins a row removal operation.
void endRemoveRows ()
 Ends a row removal operation.
bool beginMoveRows (const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationRow)
void endMoveRows ()
 Ends a row move operation.
void beginInsertColumns (const QModelIndex &parent, int firstfirst, int last)
 Begins a column insertion operation.
void endInsertColumns ()
 Ends a column insertion operation.
void beginRemoveColumns (const QModelIndex &parent, int firstfirst, int last)
 Begins a column removal operation.
void endRemoveColumns ()
 Ends a column removal operation.
bool beginMoveColumns (const QModelIndex &sourceParent, int sourceFirst, int sourceLast, const QModelIndex &destinationParent, int destinationColumn)
 Begins a column move operation.
void endMoveColumns ()
 Ends a column move operation.
void beginResetModel ()
 Begins a model reset operation.
void endResetModel ()
 Completes a model reset operation.
void changePersistentIndex (const QModelIndex &from, const QModelIndex &to)
 Changes the QPersistentModelIndex that is equal to the given from model index to the given to model index.
void changePersistentIndexList (const QModelIndexList &from, const QModelIndexList &to)
QModelIndexList persistentIndexList () const
Protected Member Functions inherited from QObject
QObject * sender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.
int senderSignalIndex () const
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal.
bool isSignalConnected (const QMetaMethod &signal) const
virtual void timerEvent (QTimerEvent *eventevent)
 This event handler can be reimplemented in a subclass to receive timer events for the object.
virtual void childEvent (QChildEvent *eventevent)
 This event handler can be reimplemented in a subclass to receive child events.
virtual void customEvent (QEvent *eventevent)
 This event handler can be reimplemented in a subclass to receive custom events.
virtual void connectNotify (const QMetaMethod &signal)
virtual void disconnectNotify (const QMetaMethod &signal)
 QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Properties

int sortRole
 the item role that is used to query the model's data when sorting items
Properties inherited from QObject
QString objectName
 the name of this object

Friends

class QStandardItemPrivate
class QStandardItem

Additional Inherited Members

Public Types inherited from QAbstractItemModel
enum  LayoutChangeHint { NoLayoutChangeHint , VerticalSortHint , HorizontalSortHint }
 This enum describes the way the model changes layout. More...
enum class  CheckIndexOption { NoOption = 0x0000 , IndexIsValid = 0x0001 , DoNotUseParent = 0x0002 , ParentIsInvalid = 0x0004 }
virtual bool submit ()
 Lets the model know that it should submit cached information to permanent storage.
virtual void revert ()
 Lets the model know that it should discard cached information.
Public Slots inherited from QObject
void deleteLater ()
 \threadsafe
Static Public Member Functions inherited from QObject
static QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 \threadsafe
static QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType typetype=Qt::AutoConnection)
template<typename Func1, typename Func2>
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType *context, Func2 &&slot, Qt::ConnectionType typetype=Qt::AutoConnection)
template<typename Func1, typename Func2>
static QMetaObject::Connection connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 \threadsafe
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static bool disconnect (const QMetaObject::Connection &)
 Disconnects connection and resets it to \l{QMetaObject::Connection::operator bool()}{invalid}.
static bool disconnect (QMetaObject::Connection &)
static bool disconnect (QMetaObject::Connection &&conn)
 Disconnect a connection.
template<typename Func1, typename Func2>
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object *receiver, Func2 slot)
template<typename Func1>
static bool disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, const QObject *receiver, void **zero)
Public Attributes inherited from QAbstractItemModel
Q_INVOKABLE int count
Q_INVOKABLE int sourceRow
Q_INVOKABLE int int count
Q_INVOKABLE int int const QModelIndex & destinationParent
Q_INVOKABLE int int const QModelIndex int destinationChild
Q_INVOKABLE int sourceColumn
Q_INVOKABLE const QModelIndex & parent = QModelIndex())
Q_INVOKABLE int const QModelIndex & destinationParent
Q_INVOKABLE int const QModelIndex int destinationChild
Q_INVOKABLE Qt::SortOrder order = Qt::AscendingOrder)
Q_INVOKABLE int const QModelIndex & parent = QModelIndex())
 Returns the parent of the model item with the given index.
virtual void resetInternalData ()
Static Protected Member Functions inherited from QAbstractItemModel
static Qt::weak_ordering compareData (const QVariant &leftleft, const QVariant &rightright)
static Qt::weak_ordering compareData (const QVariant &leftleft, const QVariant &rightright, const QCollator &collator)
Protected Attributes inherited from QObject
QScopedPointer< QObjectData > d_ptr
Related Symbols inherited from QObject
 Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.
 \macro Q_CLASSINFO(Name, Value)

Detailed Description

The QStandardItemModel class provides a generic model for storing custom data.

\inmodule QtGui

QStandardItemModel can be used as a repository for standard Qt data types. It is one of the \l {Model/View Classes} and is part of Qt's \l {Model/View Programming}{model/view} framework.

QStandardItemModel provides a classic item-based approach to working with the model. The items in a QStandardItemModel are provided by QStandardItem.

QStandardItemModel implements the QAbstractItemModel interface, which means that the model can be used to provide data in any view that supports that interface (such as QListView, QTableView and QTreeView, and your own custom views). For performance and flexibility, you may want to subclass QAbstractItemModel to provide support for different kinds of data repositories. For example, the QFileSystemModel provides a model interface to the underlying file system.

When you want a list or tree, you typically create an empty QStandardItemModel and use appendRow() to add items to the model, and item() to access an item. If your model represents a table, you typically pass the dimensions of the table to the QStandardItemModel constructor and use setItem() to position items into the table. You can also use setRowCount() and setColumnCount() to alter the dimensions of the model. To insert items, use insertRow() or insertColumn(), and to remove items, use removeRow() or removeColumn().

You can set the header labels of your model with setHorizontalHeaderLabels() and setVerticalHeaderLabels().

You can search for items in the model with findItems(), and sort the model by calling sort().

Call clear() to remove all items from the model.

An example usage of QStandardItemModel to create a table:

QStandardItemModel model(4, 4);
for (int row = 0; row < model.rowCount(); ++row) {
for (int column = 0; column < model.columnCount(); ++column) {
QStandardItem *item = new QStandardItem(QString("row %0, column %1").arg(row).arg(column));
model.setItem(row, column, item);
}
}

An example usage of QStandardItemModel to create a tree:

QStandardItemModel model;
QStandardItem *parentItem = model.invisibleRootItem();
for (int i = 0; i < 4; ++i) {
QStandardItem *item = new QStandardItem(QString("item %0").arg(i));
parentItem->appendRow(item);
parentItem = item;
}

After setting the model on a view, you typically want to react to user actions, such as an item being clicked. Since a QAbstractItemView provides QModelIndex-based signals and functions, you need a way to obtain the QStandardItem that corresponds to a given QModelIndex, and vice versa. itemFromIndex() and indexFromItem() provide this mapping. Typical usage of itemFromIndex() includes obtaining the item at the current index in a view, and obtaining the item that corresponds to an index carried by a QAbstractItemView signal, such as QAbstractItemView::clicked(). First you connect the view's signal to a slot in your class:

QTreeView *treeView = new QTreeView(this);
treeView->setModel(myStandardItemModel);
connect(treeView, &QTreeView::clicked,
this, &MyWidget::clicked);

When you receive the signal, you call itemFromIndex() on the given model index to get a pointer to the item:

void MyWidget::clicked(const QModelIndex &index)
{
QStandardItem *item = myStandardItemModel->itemFromIndex(index);
// Do stuff with the item ...
}

Conversely, you must obtain the QModelIndex of an item when you want to invoke a model/view function that takes an index as argument. You can obtain the index either by using the model's indexFromItem() function, or, equivalently, by calling QStandardItem::index():

treeView->scrollTo(item->index());

You are, of course, not required to use the item-based approach; you could instead rely entirely on the QAbstractItemModel interface when working with the model, or use a combination of the two as appropriate.

See also
QStandardItem, {Model/View Programming}, QAbstractItemModel, QRangeModel, {itemviews/simpletreemodel}{Simple Tree Model example}, {Item View Convenience Classes}

Definition at line 279 of file qstandarditemmodel.h.

Constructor & Destructor Documentation

◆ QStandardItemModel() [1/3]

QStandardItemModel::QStandardItemModel ( QObject * parent = nullptr)
explicit

Constructs a new item model with the given parent.

Definition at line 2356 of file qstandarditemmodel.cpp.

◆ QStandardItemModel() [2/3]

QStandardItemModel::QStandardItemModel ( int rows,
int columns,
QObject * parent = nullptr )

Constructs a new item model that initially has rows rows and columns columns, and that has the given parent.

Definition at line 2368 of file qstandarditemmodel.cpp.

◆ ~QStandardItemModel()

QStandardItemModel::~QStandardItemModel ( )

Destructs the model.

The model destroys all its items.

Definition at line 2393 of file qstandarditemmodel.cpp.

◆ QStandardItemModel() [3/3]

QStandardItemModel::QStandardItemModel ( QStandardItemModelPrivate & dd,
QObject * parent = nullptr )
protected

Definition at line 2383 of file qstandarditemmodel.cpp.

Member Function Documentation

◆ appendColumn()

void QStandardItemModel::appendColumn ( const QList< QStandardItem * > & items)
Since
4.2

Appends a column containing items. If necessary, the row count is increased to the size of items.

See also
insertColumn(), appendRow()

Definition at line 2818 of file qstandarditemmodel.cpp.

◆ appendRow() [1/2]

void QStandardItemModel::appendRow ( const QList< QStandardItem * > & items)
Since
4.2

Appends a row containing items. If necessary, the column count is increased to the size of items.

See also
insertRow(), appendColumn()

Definition at line 2805 of file qstandarditemmodel.cpp.

◆ appendRow() [2/2]

void QStandardItemModel::appendRow ( QStandardItem * item)
inline
Since
4.2

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

When building a list or a tree that has only one column, this function provides a convenient way to append a single new item.

Definition at line 397 of file qstandarditemmodel.h.

◆ bindableSortRole()

QBindable< int > QStandardItemModel::bindableSortRole ( )

Definition at line 2981 of file qstandarditemmodel.cpp.

◆ clear()

void QStandardItemModel::clear ( )

Removes all items (including header items) from the model and sets the number of rows and columns to zero.

See also
removeColumns(), removeRows()

Definition at line 2426 of file qstandarditemmodel.cpp.

◆ clearItemData()

bool QStandardItemModel::clearItemData ( const QModelIndex & index)
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3195 of file qstandarditemmodel.cpp.

◆ columnCount()

int QStandardItemModel::columnCount ( const QModelIndex & parent = QModelIndex()) const
overridevirtual

\reimp

Implements QAbstractItemModel.

Definition at line 2990 of file qstandarditemmodel.cpp.

◆ data()

QVariant QStandardItemModel::data ( const QModelIndex & index,
int role = Qt::DisplayRole ) const
overridevirtual

\reimp

Implements QAbstractItemModel.

Definition at line 3000 of file qstandarditemmodel.cpp.

◆ dropMimeData()

bool QStandardItemModel::dropMimeData ( const QMimeData * data,
Qt::DropAction action,
int row,
int column,
const QModelIndex & parent )
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3362 of file qstandarditemmodel.cpp.

◆ findItems()

QList< QStandardItem * > QStandardItemModel::findItems ( const QString & text,
Qt::MatchFlags flags = Qt::MatchExactly,
int column = 0 ) const
Since
4.2

Returns a list of items that match the given text, using the given flags, in the given column.

Definition at line 2784 of file qstandarditemmodel.cpp.

◆ flags()

Qt::ItemFlags QStandardItemModel::flags ( const QModelIndex & index) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Reimplemented in QUrlModel.

Definition at line 3022 of file qstandarditemmodel.cpp.

◆ hasChildren()

bool QStandardItemModel::hasChildren ( const QModelIndex & parent = QModelIndex()) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3040 of file qstandarditemmodel.cpp.

◆ headerData()

QVariant QStandardItemModel::headerData ( int section,
Qt::Orientation orientation,
int role = Qt::DisplayRole ) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3050 of file qstandarditemmodel.cpp.

◆ horizontalHeaderItem()

QStandardItem * QStandardItemModel::horizontalHeaderItem ( int column) const
Since
4.2

Returns the horizontal header item for column if one has been set; otherwise returns \nullptr.

See also
setHorizontalHeaderItem(), verticalHeaderItem()

Definition at line 2629 of file qstandarditemmodel.cpp.

◆ index()

QModelIndex QStandardItemModel::index ( int row,
int column,
const QModelIndex & parent = QModelIndex() ) const
overridevirtual

\reimp

Implements QAbstractItemModel.

Definition at line 3080 of file qstandarditemmodel.cpp.

◆ indexFromItem()

QModelIndex QStandardItemModel::indexFromItem ( const QStandardItem * item) const
Since
4.2

Returns the QModelIndex associated with the given item.

Use this function when you want to perform an operation that requires the QModelIndex of the item, such as QAbstractItemView::scrollTo(). QStandardItem::index() is provided as convenience; it is equivalent to calling this function.

See also
itemFromIndex(), QStandardItem::index()

Definition at line 2488 of file qstandarditemmodel.cpp.

◆ insertColumn() [1/2]

void QStandardItemModel::insertColumn ( int column,
const QList< QStandardItem * > & items )
Since
4.2

Inserts a column at column containing items. If necessary, the row count is increased to the size of items.

See also
takeColumn(), appendColumn(), insertRow()

Definition at line 2865 of file qstandarditemmodel.cpp.

◆ insertColumn() [2/2]

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

Inserts a single column before the given column in the child items of the parent specified.

Returns true if the column is inserted; otherwise returns false.

See also
insertColumns(), insertRow(), removeColumn()

Definition at line 405 of file qstandarditemmodel.h.

◆ insertColumns()

bool QStandardItemModel::insertColumns ( int column,
int count,
const QModelIndex & parent = QModelIndex() )
override

\reimp

Definition at line 3097 of file qstandarditemmodel.cpp.

◆ insertRow() [1/3]

void QStandardItemModel::insertRow ( int row,
const QList< QStandardItem * > & items )
Since
4.2

Inserts a row at row containing items. If necessary, the column count is increased to the size of items.

See also
takeRow(), appendRow(), insertColumn()

Definition at line 2840 of file qstandarditemmodel.cpp.

◆ insertRow() [2/3]

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

Inserts a single row before the given row in the child items of the parent specified.

Returns true if the row is inserted; otherwise returns false.

See also
insertRows(), insertColumn(), removeRow()

Definition at line 403 of file qstandarditemmodel.h.

◆ insertRow() [3/3]

void QStandardItemModel::insertRow ( int row,
QStandardItem * item )
inline
Since
4.2

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Inserts a row at row containing item.

When building a list or a tree that has only one column, this function provides a convenient way to append a single new item.

Definition at line 400 of file qstandarditemmodel.h.

◆ insertRows()

bool QStandardItemModel::insertRows ( int row,
int count,
const QModelIndex & parent = QModelIndex() )
override

\reimp

Definition at line 3109 of file qstandarditemmodel.cpp.

◆ invisibleRootItem()

QStandardItem * QStandardItemModel::invisibleRootItem ( ) const
Since
4.2

Returns the model's invisible root item.

The invisible root item provides access to the model's top-level items through the QStandardItem API, making it possible to write functions that can treat top-level items and their children in a uniform way; for example, recursive functions involving a tree model.

Note
Calling \l{QAbstractItemModel::index()}{index()} on the QStandardItem object retrieved from this function is not valid.

Definition at line 2575 of file qstandarditemmodel.cpp.

◆ item()

QStandardItem * QStandardItemModel::item ( int row,
int column = 0 ) const
Since
4.2

Returns the item for the given row and column if one has been set; otherwise returns \nullptr.

See also
setItem(), takeItem(), itemFromIndex()

Definition at line 2556 of file qstandarditemmodel.cpp.

◆ itemChanged

void QStandardItemModel::itemChanged ( QStandardItem * item)
signal
Since
4.2

This signal is emitted whenever the data of item has changed.

◆ itemData()

QMap< int, QVariant > QStandardItemModel::itemData ( const QModelIndex & index) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3121 of file qstandarditemmodel.cpp.

◆ itemFromIndex()

QStandardItem * QStandardItemModel::itemFromIndex ( const QModelIndex & index) const
Since
4.2

Returns a pointer to the QStandardItem associated with the given index.

Calling this function is typically the initial step when processing QModelIndex-based signals from a view, such as QAbstractItemView::activated(). In your slot, you call itemFromIndex(), with the QModelIndex carried by the signal as argument, to obtain a pointer to the corresponding QStandardItem.

Note that this function will lazily create an item for the index (using itemPrototype()), and set it in the parent item's child table, if no item already exists at that index.

If index is an invalid index, this function returns \nullptr.

See also
indexFromItem()

Definition at line 2459 of file qstandarditemmodel.cpp.

◆ itemPrototype()

const QStandardItem * QStandardItemModel::itemPrototype ( ) const
Since
4.2

Returns the item prototype used by the model. The model uses the item prototype as an item factory when it needs to construct new items on demand (for instance, when a view or item delegate calls setData()).

See also
setItemPrototype()

Definition at line 2772 of file qstandarditemmodel.cpp.

◆ mimeData()

QMimeData * QStandardItemModel::mimeData ( const QModelIndexList & indexes) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Reimplemented in QUrlModel.

Definition at line 3273 of file qstandarditemmodel.cpp.

◆ mimeTypes()

QStringList QStandardItemModel::mimeTypes ( ) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Reimplemented in QUrlModel.

Definition at line 3265 of file qstandarditemmodel.cpp.

◆ multiData()

void QStandardItemModel::multiData ( const QModelIndex & index,
QModelRoleDataSpan roleDataSpan ) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3010 of file qstandarditemmodel.cpp.

◆ parent() [1/2]

QObject * QObject::parent ( ) const
inline

Returns a pointer to the parent object.

See also
children()

Definition at line 356 of file qobject.h.

◆ parent() [2/2]

QModelIndex QStandardItemModel::parent ( const QModelIndex & child) const
overridevirtual

\reimp

Implements QAbstractItemModel.

Definition at line 3133 of file qstandarditemmodel.cpp.

◆ removeColumns()

bool QStandardItemModel::removeColumns ( int column,
int count,
const QModelIndex & parent = QModelIndex() )
override

\reimp

Definition at line 3145 of file qstandarditemmodel.cpp.

◆ removeRows()

bool QStandardItemModel::removeRows ( int row,
int count,
const QModelIndex & parent = QModelIndex() )
override

\reimp

Definition at line 3158 of file qstandarditemmodel.cpp.

◆ roleNames()

QHash< int, QByteArray > QStandardItemModel::roleNames ( ) const
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 2414 of file qstandarditemmodel.cpp.

◆ rowCount()

int QStandardItemModel::rowCount ( const QModelIndex & parent = QModelIndex()) const
overridevirtual

\reimp

Implements QAbstractItemModel.

Definition at line 3171 of file qstandarditemmodel.cpp.

◆ setColumnCount()

void QStandardItemModel::setColumnCount ( int columns)
Since
4.2

Sets the number of columns in this model to columns. If this is less than columnCount(), the data in the unwanted columns is discarded.

See also
setRowCount()

Definition at line 2521 of file qstandarditemmodel.cpp.

◆ setData()

bool QStandardItemModel::setData ( const QModelIndex & index,
const QVariant & value,
int role = Qt::EditRole )
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Reimplemented in qdesigner_internal::SignatureModel, and QUrlModel.

Definition at line 3181 of file qstandarditemmodel.cpp.

◆ setHeaderData()

bool QStandardItemModel::setHeaderData ( int section,
Qt::Orientation orientation,
const QVariant & value,
int role = Qt::EditRole )
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3210 of file qstandarditemmodel.cpp.

◆ setHorizontalHeaderItem()

void QStandardItemModel::setHorizontalHeaderItem ( int column,
QStandardItem * item )
Since
4.2

Sets the horizontal header item for column to item. The model takes ownership of the item. If necessary, the column count is increased to fit the item. The previous header item (if there was one) is deleted.

See also
horizontalHeaderItem(), setHorizontalHeaderLabels(), setVerticalHeaderItem()

Definition at line 2591 of file qstandarditemmodel.cpp.

◆ setHorizontalHeaderLabels()

void QStandardItemModel::setHorizontalHeaderLabels ( const QStringList & labels)
Since
4.2

Sets the horizontal header labels using labels. If necessary, the column count is increased to the size of labels.

See also
setHorizontalHeaderItem()

Definition at line 2701 of file qstandarditemmodel.cpp.

◆ setItem() [1/2]

void QStandardItemModel::setItem ( int row,
int column,
QStandardItem * item )
Since
4.2

Sets the item for the given row and column to item. The model takes ownership of the item. If necessary, the row count and column count are increased to fit the item. The previous item at the given location (if there was one) is deleted.

See also
item()

Definition at line 2537 of file qstandarditemmodel.cpp.

◆ setItem() [2/2]

void QStandardItemModel::setItem ( int row,
QStandardItem * item )
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 394 of file qstandarditemmodel.h.

◆ setItemData()

bool QStandardItemModel::setItemData ( const QModelIndex & index,
const QMap< int, QVariant > & roles )
overridevirtual

\reimp

Reimplemented from QAbstractItemModel.

Definition at line 3244 of file qstandarditemmodel.cpp.

◆ setItemPrototype()

void QStandardItemModel::setItemPrototype ( const QStandardItem * item)
Since
4.2

Sets the item prototype for the model to the specified item. The model takes ownership of the prototype.

The item prototype acts as a QStandardItem factory, by relying on the QStandardItem::clone() function. To provide your own prototype, subclass QStandardItem, reimplement QStandardItem::clone() and set the prototype to be an instance of your custom class. Whenever QStandardItemModel needs to create an item on demand (for instance, when a view or item delegate calls setData())), the new items will be instances of your custom class.

See also
itemPrototype(), QStandardItem::clone()

Definition at line 2754 of file qstandarditemmodel.cpp.

◆ setItemRoleNames()

void QStandardItemModel::setItemRoleNames ( const QHash< int, QByteArray > & roleNames)

Sets the item role names to roleNames.

Definition at line 2405 of file qstandarditemmodel.cpp.

◆ setRowCount()

void QStandardItemModel::setRowCount ( int rows)
Since
4.2

Sets the number of rows in this model to rows. If this is less than rowCount(), the data in the unwanted rows is discarded.

See also
setColumnCount()

Definition at line 2506 of file qstandarditemmodel.cpp.

◆ setSortRole()

void QStandardItemModel::setSortRole ( int role)

Definition at line 2975 of file qstandarditemmodel.cpp.

◆ setVerticalHeaderItem()

void QStandardItemModel::setVerticalHeaderItem ( int row,
QStandardItem * item )
Since
4.2

Sets the vertical header item for row to item. The model takes ownership of the item. If necessary, the row count is increased to fit the item. The previous header item (if there was one) is deleted.

See also
verticalHeaderItem(), setVerticalHeaderLabels(), setHorizontalHeaderItem()

Definition at line 2647 of file qstandarditemmodel.cpp.

◆ setVerticalHeaderLabels()

void QStandardItemModel::setVerticalHeaderLabels ( const QStringList & labels)
Since
4.2

Sets the vertical header labels using labels. If necessary, the row count is increased to the size of labels.

See also
setVerticalHeaderItem()

Definition at line 2724 of file qstandarditemmodel.cpp.

◆ sort()

void QStandardItemModel::sort ( int column,
Qt::SortOrder order = Qt::AscendingOrder )
override

\reimp

Definition at line 3256 of file qstandarditemmodel.cpp.

◆ sortRole()

int QStandardItemModel::sortRole ( ) const

Definition at line 2969 of file qstandarditemmodel.cpp.

◆ supportedDropActions()

Qt::DropActions QStandardItemModel::supportedDropActions ( ) const
overridevirtual

\reimp

QStandardItemModel supports both copy and move.

Reimplemented from QAbstractItemModel.

Definition at line 3072 of file qstandarditemmodel.cpp.

◆ takeColumn()

QList< QStandardItem * > QStandardItemModel::takeColumn ( int column)
Since
4.2

Removes the given column without deleting the column items, and returns a list of pointers to the removed items. The model releases ownership of the items. For items in the column that have not been set, the corresponding pointers in the list will be \nullptr.

See also
takeRow()

Definition at line 2910 of file qstandarditemmodel.cpp.

◆ takeHorizontalHeaderItem()

QStandardItem * QStandardItemModel::takeHorizontalHeaderItem ( int column)
Since
4.2

Removes the horizontal header item at column from the header without deleting it, and returns a pointer to the item. The model releases ownership of the item.

See also
horizontalHeaderItem(), takeVerticalHeaderItem()

Definition at line 2925 of file qstandarditemmodel.cpp.

◆ takeItem()

QStandardItem * QStandardItemModel::takeItem ( int row,
int column = 0 )
Since
4.2

Removes the item at (row, column) without deleting it. The model releases ownership of the item.

See also
item(), takeRow(), takeColumn()

Definition at line 2878 of file qstandarditemmodel.cpp.

◆ takeRow()

QList< QStandardItem * > QStandardItemModel::takeRow ( int row)
Since
4.2

Removes the given row without deleting the row items, and returns a list of pointers to the removed items. The model releases ownership of the items. For items in the row that have not been set, the corresponding pointers in the list will be \nullptr.

See also
takeColumn()

Definition at line 2894 of file qstandarditemmodel.cpp.

◆ takeVerticalHeaderItem()

QStandardItem * QStandardItemModel::takeVerticalHeaderItem ( int row)
Since
4.2

Removes the vertical header item at row from the header without deleting it, and returns a pointer to the item. The model releases ownership of the item.

See also
verticalHeaderItem(), takeHorizontalHeaderItem()

Definition at line 2947 of file qstandarditemmodel.cpp.

◆ verticalHeaderItem()

QStandardItem * QStandardItemModel::verticalHeaderItem ( int row) const
Since
4.2

Returns the vertical header item for row row if one has been set; otherwise returns \nullptr.

See also
setVerticalHeaderItem(), horizontalHeaderItem()

Definition at line 2685 of file qstandarditemmodel.cpp.

◆ QStandardItem

friend class QStandardItem
friend

Definition at line 386 of file qstandarditemmodel.h.

◆ QStandardItemPrivate

friend class QStandardItemPrivate
friend

Definition at line 385 of file qstandarditemmodel.h.

Property Documentation

◆ sortRole

int QStandardItemModel::sortRole
readwrite

the item role that is used to query the model's data when sorting items

Since
4.2

The default value is Qt::DisplayRole.

See also
sort(), QStandardItem::sortChildren()

Definition at line 282 of file qstandarditemmodel.h.

The documentation for this class was generated from the following files: