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.


Copyright © 2007 Trolltech Trademarks
Qt Jambi 4.3.2_01