Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Signals
• Detailed Description

Detailed Description

TheQStandardItemModel class provides a generic model for storing custom data.

QStandardItemModel can be used as a repository for standard Qt data types. It is one of theModel/View Classes and is part of Qt'smodel/view framework.

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

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

When you want a list or tree, you typically create an emptyQStandardItemModel and useappendRow() to add items to the model, anditem() to access an item. If your model represents a table, you typically pass the dimensions of the table to theQStandardItemModel constructor and usesetItem() to position items into the table. You can also usesetRowCount() andsetColumnCount() to alter the dimensions of the model. To insert items, useinsertRow() orinsertColumn(), and to remove items, useremoveRow() orremoveColumn().

You can set the header labels of your model withsetHorizontalHeaderLabels() andsetVerticalHeaderLabels().

You can search for items in the model withfindItems(), and sort the model by callingsort().

Callclear() to remove all items from the model.

An example usage ofQStandardItemModel to create a table:

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

An example usage ofQStandardItemModel to create a tree:

QStandardItemModel model;QStandardItem*parentItem= model.invisibleRootItem();for (int i=0; i<4;++i) {QStandardItem*item=newQStandardItem(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 aQAbstractItemView providesQModelIndex-based signals and functions, you need a way to obtain theQStandardItem that corresponds to a givenQModelIndex, and vice versa.itemFromIndex() andindexFromItem() provide this mapping. Typical usage ofitemFromIndex() includes obtaining the item at the current index in a view, and obtaining the item that corresponds to an index carried by aQAbstractItemView signal, such asQAbstractItemView::clicked(). First you connect the view's signal to a slot in your class:

QTreeView*treeView=newQTreeView(this);treeView->setModel(myStandardItemModel);connect(treeView, SIGNAL(clicked(QModelIndex)),this, SLOT(clicked(QModelIndex)));

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

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

Conversely, you must obtain theQModelIndex 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'sindexFromItem() function, or, equivalently, by callingQStandardItem::index():

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

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

Property Documentation

sortRole :int

This property holds the item role that is used to query the model's data when sorting items.

The default value isQt::DisplayRole.

This property was introduced in Qt 4.2.

Access functions:

See alsosort() andQStandardItem::sortChildren().

Member Function Documentation

QStandardItemModel::QStandardItemModel(QObject * parent = 0)

Constructs a new item model with the givenparent.

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

Constructs a new item model that initially hasrows rows andcolumns columns, and that has the givenparent.

QStandardItemModel::~QStandardItemModel()

Destructs the model. The model destroys all its items.

void QStandardItemModel::appendColumn(constQList<QStandardItem *> & items)

Appends a column containingitems. If necessary, the row count is increased to the size ofitems.

This function was introduced in Qt 4.2.

See alsoinsertColumn() andappendRow().

void QStandardItemModel::appendRow(constQList<QStandardItem *> & items)

Appends a row containingitems. If necessary, the column count is increased to the size ofitems.

This function was introduced in Qt 4.2.

See alsoinsertRow() andappendColumn().

void QStandardItemModel::appendRow(QStandardItem * item)

This is an overloaded function.

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

This function was introduced in Qt 4.2.

void QStandardItemModel::clear()

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

See alsoremoveColumns() andremoveRows().

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

Reimplemented fromQAbstractItemModel::columnCount().

See alsosetColumnCount().

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

Reimplemented fromQAbstractItemModel::data().

See alsosetData().

[virtual]bool QStandardItemModel::dropMimeData(constQMimeData * data,Qt::DropAction action,int row,int column, constQModelIndex & parent)

Reimplemented fromQAbstractItemModel::dropMimeData().

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

Returns a list of items that match the giventext, using the givenflags, in the givencolumn.

This function was introduced in Qt 4.2.

[virtual]Qt::ItemFlags QStandardItemModel::flags(constQModelIndex & index) const

Reimplemented fromQAbstractItemModel::flags().

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

Reimplemented fromQAbstractItemModel::hasChildren().

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

Reimplemented fromQAbstractItemModel::headerData().

See alsosetHeaderData().

QStandardItem * QStandardItemModel::horizontalHeaderItem(int column) const

Returns the horizontal header item forcolumn if one has been set; otherwise returns 0.

This function was introduced in Qt 4.2.

See alsosetHorizontalHeaderItem() andverticalHeaderItem().

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

Reimplemented fromQAbstractItemModel::index().

QModelIndex QStandardItemModel::indexFromItem(constQStandardItem * item) const

Returns theQModelIndex associated with the givenitem.

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

This function was introduced in Qt 4.2.

See alsoitemFromIndex() andQStandardItem::index().

void QStandardItemModel::insertColumn(int column, constQList<QStandardItem *> & items)

Inserts a column atcolumn containingitems. If necessary, the row count is increased to the size ofitems.

This function was introduced in Qt 4.2.

See alsotakeColumn(),appendColumn(), andinsertRow().

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

Inserts a single column before the givencolumn in the child items of theparent specified. Returns true if the column is inserted; otherwise returns false.

See alsoinsertColumns(),insertRow(), andremoveColumn().

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

Reimplemented fromQAbstractItemModel::insertColumns().

void QStandardItemModel::insertRow(int row, constQList<QStandardItem *> & items)

Inserts a row atrow containingitems. If necessary, the column count is increased to the size ofitems.

This function was introduced in Qt 4.2.

See alsotakeRow(),appendRow(), andinsertColumn().

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

Inserts a single row before the givenrow in the child items of theparent specified. Returns true if the row is inserted; otherwise returns false.

See alsoinsertRows(),insertColumn(), andremoveRow().

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

This is an overloaded function.

Inserts a row atrow containingitem.

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

This function was introduced in Qt 4.2.

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

Reimplemented fromQAbstractItemModel::insertRows().

QStandardItem * QStandardItemModel::invisibleRootItem() const

Returns the model's invisible root item.

The invisible root item provides access to the model's top-level items through theQStandardItem 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:Callingindex() on theQStandardItem object retrieved from this function is not valid.

This function was introduced in Qt 4.2.

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

Returns the item for the givenrow andcolumn if one has been set; otherwise returns 0.

This function was introduced in Qt 4.2.

See alsosetItem(),takeItem(), anditemFromIndex().

[signal]void QStandardItemModel::itemChanged(QStandardItem * item)

This signal is emitted whenever the data ofitem has changed.

This function was introduced in Qt 4.2.

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

Reimplemented fromQAbstractItemModel::itemData().

See alsosetItemData().

QStandardItem * QStandardItemModel::itemFromIndex(constQModelIndex & index) const

Returns a pointer to theQStandardItem associated with the givenindex.

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

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

Ifindex is an invalid index, this function returns 0.

This function was introduced in Qt 4.2.

See alsoindexFromItem().

constQStandardItem * QStandardItemModel::itemPrototype() const

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 callssetData()).

This function was introduced in Qt 4.2.

See alsosetItemPrototype().

[virtual]QMimeData * QStandardItemModel::mimeData(constQModelIndexList & indexes) const

Reimplemented fromQAbstractItemModel::mimeData().

[virtual]QStringList QStandardItemModel::mimeTypes() const

Reimplemented fromQAbstractItemModel::mimeTypes().

[virtual]QModelIndex QStandardItemModel::parent(constQModelIndex & child) const

Reimplemented fromQAbstractItemModel::parent().

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

Reimplemented fromQAbstractItemModel::removeColumns().

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

Reimplemented fromQAbstractItemModel::removeRows().

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

Reimplemented fromQAbstractItemModel::rowCount().

See alsosetRowCount().

void QStandardItemModel::setColumnCount(int columns)

Sets the number of columns in this model tocolumns. If this is less thancolumnCount(), the data in the unwanted columns is discarded.

This function was introduced in Qt 4.2.

See alsocolumnCount() andsetRowCount().

[virtual]bool QStandardItemModel::setData(constQModelIndex & index, constQVariant & value,int role = Qt::EditRole)

Reimplemented fromQAbstractItemModel::setData().

See alsodata().

[virtual]bool QStandardItemModel::setHeaderData(int section,Qt::Orientation orientation, constQVariant & value,int role = Qt::EditRole)

Reimplemented fromQAbstractItemModel::setHeaderData().

See alsoheaderData().

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

Sets the horizontal header item forcolumn toitem. 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.

This function was introduced in Qt 4.2.

See alsohorizontalHeaderItem(),setHorizontalHeaderLabels(), andsetVerticalHeaderItem().

void QStandardItemModel::setHorizontalHeaderLabels(constQStringList & labels)

Sets the horizontal header labels usinglabels. If necessary, the column count is increased to the size oflabels.

This function was introduced in Qt 4.2.

See alsosetHorizontalHeaderItem().

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

Sets the item for the givenrow andcolumn toitem. 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.

This function was introduced in Qt 4.2.

See alsoitem().

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

This is an overloaded function.

[virtual]bool QStandardItemModel::setItemData(constQModelIndex & index, constQMap<int,QVariant> & roles)

Reimplemented fromQAbstractItemModel::setItemData().

See alsoitemData().

void QStandardItemModel::setItemPrototype(constQStandardItem * item)

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

The item prototype acts as aQStandardItem factory, by relying on theQStandardItem::clone() function. To provide your own prototype, subclassQStandardItem, reimplementQStandardItem::clone() and set the prototype to be an instance of your custom class. WheneverQStandardItemModel needs to create an item on demand (for instance, when a view or item delegate callssetData())), the new items will be instances of your custom class.

This function was introduced in Qt 4.2.

See alsoitemPrototype() andQStandardItem::clone().

void QStandardItemModel::setRowCount(int rows)

Sets the number of rows in this model torows. If this is less thanrowCount(), the data in the unwanted rows is discarded.

This function was introduced in Qt 4.2.

See alsorowCount() andsetColumnCount().

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

Sets the vertical header item forrow toitem. 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.

This function was introduced in Qt 4.2.

See alsoverticalHeaderItem(),setVerticalHeaderLabels(), andsetHorizontalHeaderItem().

void QStandardItemModel::setVerticalHeaderLabels(constQStringList & labels)

Sets the vertical header labels usinglabels. If necessary, the row count is increased to the size oflabels.

This function was introduced in Qt 4.2.

See alsosetVerticalHeaderItem().

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

Reimplemented fromQAbstractItemModel::sort().

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

Reimplemented fromQAbstractItemModel::supportedDropActions().

QStandardItemModel supports both copy and move.

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

Removes the givencolumn 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 0.

This function was introduced in Qt 4.2.

See alsotakeRow().

QStandardItem * QStandardItemModel::takeHorizontalHeaderItem(int column)

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

This function was introduced in Qt 4.2.

See alsohorizontalHeaderItem() andtakeVerticalHeaderItem().

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

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

This function was introduced in Qt 4.2.

See alsoitem(),takeRow(), andtakeColumn().

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

Removes the givenrow 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 0.

This function was introduced in Qt 4.2.

See alsotakeColumn().

QStandardItem * QStandardItemModel::takeVerticalHeaderItem(int row)

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

This function was introduced in Qt 4.2.

See alsoverticalHeaderItem() andtakeHorizontalHeaderItem().

QStandardItem * QStandardItemModel::verticalHeaderItem(int row) const

Returns the vertical header item for rowrow if one has been set; otherwise returns 0.

This function was introduced in Qt 4.2.

See alsosetVerticalHeaderItem() andhorizontalHeaderItem().