QStandardItemModel Class Reference
[QtGui module]

Detailed Description

The QStandardItemModel 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 the Model/View Classes and is part of Qt's 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 QDirModel 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 < 4; ++row) {
     for (int column = 0; column < 4; ++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, SIGNAL(clicked(QModelIndex)),
         this, SLOT(clicked(QModelIndex)));

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, Simple Tree Model example, and Item View Convenience Classes.

Property Documentation