|  | Home · All Classes · Modules

# QStandardItemModel Class Reference
[QtGui module]

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

Inherits QAbstractItemModel.

### Methods

- __init__ (self, QObject parent = None)
- __init__ (self, int rows, int columns, QObject parent = None)
- appendColumn (self, QStandardItem-list items)
- appendRow (self, QStandardItem-list items)
- appendRow (self, QStandardItem aitem)
- clear (self)
- int columnCount (self, QModelIndex parent = QModelIndex())
- QVariant data (self, QModelIndex index, int role = Qt.DisplayRole)
- QStandardItem-list findItems (self, QString text, Qt.MatchFlags flags = Qt.MatchExactly, int column = 0)
- Qt.ItemFlags flags (self, QModelIndex index)
- bool hasChildren (self, QModelIndex parent = QModelIndex())
- QVariant headerData (self, int section, Qt.Orientation orientation, int role = Qt.DisplayRole)
- QStandardItem horizontalHeaderItem (self, int column)
- QModelIndex index (self, int row, int column, QModelIndex parent = QModelIndex())
- QModelIndex indexFromItem (self, QStandardItem item)
- insertColumn (self, int column, QStandardItem-list items)
- bool insertColumn (self, int acolumn, QModelIndex aparent = QModelIndex())
- bool insertColumns (self, int column, int count, QModelIndex parent = QModelIndex())
- insertRow (self, int row, QStandardItem-list items)
- insertRow (self, int arow, QStandardItem aitem)
- bool insertRow (self, int arow, QModelIndex aparent = QModelIndex())
- bool insertRows (self, int row, int count, QModelIndex parent = QModelIndex())
- QStandardItem invisibleRootItem (self)
- QStandardItem item (self, int row, int column = 0)
- int-QVariant-dict itemData (self, QModelIndex index)
- QStandardItem itemFromIndex (self, QModelIndex index)
- QStandardItem itemPrototype (self)
- QModelIndex parent (self, QModelIndex child)
- QObject parent (self)
- bool removeColumns (self, int column, int count, QModelIndex parent = QModelIndex())
- bool removeRows (self, int row, int count, QModelIndex parent = QModelIndex())
- int rowCount (self, QModelIndex parent = QModelIndex())
- setColumnCount (self, int columns)
- bool setData (self, QModelIndex index, QVariant value, int role = Qt.EditRole)
- bool setHeaderData (self, int section, Qt.Orientation orientation, QVariant value, int role = Qt.EditRole)
- setHorizontalHeaderItem (self, int column, QStandardItem item)
- setHorizontalHeaderLabels (self, QStringList labels)
- setItem (self, int row, int column, QStandardItem item)
- setItem (self, int arow, QStandardItem aitem)
- bool setItemData (self, QModelIndex index, int-QVariant-dict roles)
- setItemPrototype (self, QStandardItem item)
- setRowCount (self, int rows)
- setSortRole (self, int role)
- setVerticalHeaderItem (self, int row, QStandardItem item)
- setVerticalHeaderLabels (self, QStringList labels)
- sort (self, int column, Qt.SortOrder order = Qt.AscendingOrder)
- int sortRole (self)
- Qt.DropActions supportedDropActions (self)
- QStandardItem-list takeColumn (self, int column)
- QStandardItem takeHorizontalHeaderItem (self, int column)
- QStandardItem takeItem (self, int row, int column = 0)
- QStandardItem-list takeRow (self, int row)
- QStandardItem takeVerticalHeaderItem (self, int row)
- QStandardItem verticalHeaderItem (self, int row)

### Qt Signals

- void itemChanged (QStandardItem *)

## 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.

## Method Documentation

### QStandardItemModel.__init__ (self, QObject parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

Constructs a new item model with the given parent.

### QStandardItemModel.__init__ (self, int rows, int columns, QObject parent = None)

The parent argument, if not None, causes self to be owned by Qt instead of PyQt.

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

### QStandardItemModel.appendColumn (self, QStandardItem-list items)

The items argument has it's ownership transferred to Qt.

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

This function was introduced in Qt 4.2.

See also insertColumn() and appendRow().

### QStandardItemModel.appendRow (self, QStandardItem-list items)

The items argument has it's ownership transferred to Qt.

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

This function was introduced in Qt 4.2.

See also insertRow() and appendColumn().

### QStandardItemModel.appendRow (self, QStandardItem aitem)

The aitem argument has it's ownership transferred to Qt.

This is an overloaded member function, provided for convenience.

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.

### QStandardItemModel.clear (self)

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

See also removeColumns() and removeRows().

### int QStandardItemModel.columnCount (self, QModelIndex parent = QModelIndex())

### QVariant QStandardItemModel.data (self, QModelIndex index, int role = Qt.DisplayRole)

### QStandardItem-list QStandardItemModel.findItems (self, QString text, Qt.MatchFlags flags = Qt.MatchExactly, int column = 0)

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

This function was introduced in Qt 4.2.

### Qt.ItemFlags QStandardItemModel.flags (self, QModelIndex index)

### bool QStandardItemModel.hasChildren (self, QModelIndex parent = QModelIndex())

### QVariant QStandardItemModel.headerData (self, int section, Qt.Orientation orientation, int role = Qt.DisplayRole)

### QStandardItem QStandardItemModel.horizontalHeaderItem (self, int column)

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

This function was introduced in Qt 4.2.

See also setHorizontalHeaderItem() and verticalHeaderItem().

### QModelIndex QStandardItemModel.index (self, int row, int column, QModelIndex parent = QModelIndex())

### QModelIndex QStandardItemModel.indexFromItem (self, QStandardItem item)

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.

This function was introduced in Qt 4.2.

See also itemFromIndex() and QStandardItem.index().

### QStandardItemModel.insertColumn (self, int column, QStandardItem-list items)

The items argument has it's ownership transferred to Qt.

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

This function was introduced in Qt 4.2.

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

### bool QStandardItemModel.insertColumn (self, int acolumn, QModelIndex aparent = QModelIndex())

This is an overloaded member function, provided for convenience.

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(), and removeColumn().

### bool QStandardItemModel.insertColumns (self, int column, int count, QModelIndex parent = QModelIndex())

### QStandardItemModel.insertRow (self, int row, QStandardItem-list items)

The items argument has it's ownership transferred to Qt.

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

This function was introduced in Qt 4.2.

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

### QStandardItemModel.insertRow (self, int arow, QStandardItem aitem)

The aitem argument has it's ownership transferred to Qt.

This is an overloaded member function, provided for convenience.

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(), and removeRow().

### bool QStandardItemModel.insertRow (self, int arow, QModelIndex aparent = QModelIndex())

This is an overloaded member function, provided for convenience.

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.

This function was introduced in Qt 4.2.

### bool QStandardItemModel.insertRows (self, int row, int count, QModelIndex parent = QModelIndex())

### QStandardItem QStandardItemModel.invisibleRootItem (self)

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.

This function was introduced in Qt 4.2.

### QStandardItem QStandardItemModel.item (self, int row, int column = 0)

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

This function was introduced in Qt 4.2.

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

### int-QVariant-dict QStandardItemModel.itemData (self, QModelIndex index)

### QStandardItem QStandardItemModel.itemFromIndex (self, QModelIndex index)

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 0.

This function was introduced in Qt 4.2.

See also indexFromItem().

### QStandardItem QStandardItemModel.itemPrototype (self)

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

This function was introduced in Qt 4.2.

See also setItemPrototype().

### QModelIndex QStandardItemModel.parent (self, QModelIndex child)

### QObject QStandardItemModel.parent (self)

### bool QStandardItemModel.removeColumns (self, int column, int count, QModelIndex parent = QModelIndex())

### bool QStandardItemModel.removeRows (self, int row, int count, QModelIndex parent = QModelIndex())

### int QStandardItemModel.rowCount (self, QModelIndex parent = QModelIndex())

### QStandardItemModel.setColumnCount (self, int columns)

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

This function was introduced in Qt 4.2.

See also setRowCount().

### bool QStandardItemModel.setData (self, QModelIndex index, QVariant value, int role = Qt.EditRole)

### bool QStandardItemModel.setHeaderData (self, int section, Qt.Orientation orientation, QVariant value, int role = Qt.EditRole)

### QStandardItemModel.setHorizontalHeaderItem (self, int column, QStandardItem item)

The item argument has it's ownership transferred to Qt.

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.

This function was introduced in Qt 4.2.

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

### QStandardItemModel.setHorizontalHeaderLabels (self, QStringList labels)

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

This function was introduced in Qt 4.2.

See also setHorizontalHeaderItem().

### QStandardItemModel.setItem (self, int row, int column, QStandardItem item)

The item argument has it's ownership transferred to Qt.

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.

This function was introduced in Qt 4.2.

See also item().

### QStandardItemModel.setItem (self, int arow, QStandardItem aitem)

The aitem argument has it's ownership transferred to Qt.

This is an overloaded member function, provided for convenience.

### bool QStandardItemModel.setItemData (self, QModelIndex index, int-QVariant-dict roles)

### QStandardItemModel.setItemPrototype (self, QStandardItem item)

The item argument has it's ownership transferred to Qt.

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.

This function was introduced in Qt 4.2.

See also itemPrototype() and QStandardItem.clone().

### QStandardItemModel.setRowCount (self, int rows)

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

This function was introduced in Qt 4.2.

See also setColumnCount().

### QStandardItemModel.setSortRole (self, int role)

### QStandardItemModel.setVerticalHeaderItem (self, int row, QStandardItem item)

The item argument has it's ownership transferred to Qt.

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.

This function was introduced in Qt 4.2.

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

### QStandardItemModel.setVerticalHeaderLabels (self, QStringList labels)

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

This function was introduced in Qt 4.2.

See also setVerticalHeaderItem().

### QStandardItemModel.sort (self, int column, Qt.SortOrder order = Qt.AscendingOrder)

### int QStandardItemModel.sortRole (self)

### Qt.DropActions QStandardItemModel.supportedDropActions (self)

### QStandardItem-list QStandardItemModel.takeColumn (self, int column)

The QList<QStandardItem *> result

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 0.

This function was introduced in Qt 4.2.

See also takeRow().

### QStandardItem QStandardItemModel.takeHorizontalHeaderItem (self, int column)

The QStandardItem result

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.

This function was introduced in Qt 4.2.

See also horizontalHeaderItem() and takeVerticalHeaderItem().

### QStandardItem QStandardItemModel.takeItem (self, int row, int column = 0)

The QStandardItem result

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 also item(), takeRow(), and takeColumn().

### QStandardItem-list QStandardItemModel.takeRow (self, int row)

The QList<QStandardItem *> result

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 0.

This function was introduced in Qt 4.2.

See also takeColumn().

### QStandardItem QStandardItemModel.takeVerticalHeaderItem (self, int row)

The QStandardItem result

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.

This function was introduced in Qt 4.2.

See also verticalHeaderItem() and takeHorizontalHeaderItem().

### QStandardItem QStandardItemModel.verticalHeaderItem (self, int row)

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

This function was introduced in Qt 4.2.

See also setVerticalHeaderItem() and horizontalHeaderItem().

## Qt Signal Documentation

### void itemChanged (QStandardItem *)

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

This function was introduced in Qt 4.2.