|  | Home · Overviews · Examples

# QStandardItemModel Class Reference
[com.trolltech.qt.gui module]

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

Inherits `QAbstractItemModel`.

## 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, and does not actually store file information internally.

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.