class QStandardItemModel#

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

Synopsis#

Properties#

sortRoleᅟ - The item role that is used to query the model’s data when sorting items

Methods#

def __init__()
def appendColumn()
def appendRow()
def clear()
def findItems()
def horizontalHeaderItem()
def indexFromItem()
def insertColumn()
def insertRow()
def invisibleRootItem()
def item()
def itemFromIndex()
def itemPrototype()
def setColumnCount()
def setHorizontalHeaderItem()
def setHorizontalHeaderLabels()
def setItem()
def setItemPrototype()
def setItemRoleNames()
def setRowCount()
def setSortRole()
def setVerticalHeaderItem()
def setVerticalHeaderLabels()
def sortRole()
def takeColumn()
def takeHorizontalHeaderItem()
def takeItem()
def takeRow()
def takeVerticalHeaderItem()
def verticalHeaderItem()

Signals#

def itemChanged()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

Warning

This section contains snippets that were automatically translated from C++ to Python and may contain errors.

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 QFileSystemModel 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:

model = QStandardItemModel(4, 4)
for row in range(0, model.rowCount()):
    for column in range(0, model.columnCount()):
        item = QStandardItem(QString("row %0, column %1").arg(row).arg(column))
        model.setItem(row, column, item)

An example usage of QStandardItemModel to create a tree:

model = QStandardItemModel()
parentItem = model.invisibleRootItem()
for i in range(0, 4):
    item = 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:

treeView = QTreeView(self)
treeView.setModel(myStandardItemModel)
treeView.clicked.connect(
        self.clicked)

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

def clicked(self, index):

    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 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 ProgrammingQAbstractItemModelSimple Tree Model exampleItem View Convenience Classes

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property sortRoleᅟ: int#

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

The default value is Qt::DisplayRole.

See also

sort() sortChildren()

Access functions:

sortRole()
setSortRole()

__init__(rows, columns[, parent=None])#

Parameters:

rows – int
columns – int
parent – QObject

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

__init__([parent=None])

Parameters:: parent – QObject

Constructs a new item model with the given parent.

appendColumn(items)#

Parameters:: items – .list of QStandardItem

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

See also

insertColumn() appendRow()

appendRow(item)#

Parameters:: item – QStandardItem

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 new item.

appendRow(items)

Parameters:: items – .list of QStandardItem

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

See also

insertRow() appendColumn()

clear()#

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

See also

removeColumns() removeRows()

findItems(text[, flags=Qt.MatchExactly[, column=0]])#

Parameters:

text – str
flags – Combination of MatchFlag
column – int

Return type:

.list of QStandardItem

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

horizontalHeaderItem(column)#

Parameters:: column – int
Return type:: QStandardItem

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

See also

setHorizontalHeaderItem() verticalHeaderItem()

indexFromItem(item)#

Parameters:: item – QStandardItem
Return type:: QModelIndex

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(). index() is provided as convenience; it is equivalent to calling this function.

See also

itemFromIndex() index()

insertColumn(column, items)#

Parameters:

column – int
items – .list of QStandardItem

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

See also

takeColumn() appendColumn() insertRow()

insertRow(row, item)#

Parameters:

row – int
item – QStandardItem

This is an overloaded function.

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.

insertRow(row, items)

Parameters:

row – int
items – .list of QStandardItem

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

See also

takeRow() appendRow() insertColumn()

invisibleRootItem()#

Return type:: QStandardItem

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.

Note

Calling index() on the QStandardItem object retrieved from this function is not valid.

item(row[, column=0])#

Parameters:

row – int
column – int

Return type:

QStandardItem

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

See also

setItem() takeItem() itemFromIndex()

itemChanged(item)#

Parameters:: item – QStandardItem

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

itemFromIndex(index)#

Parameters:: index – QModelIndex
Return type:: QStandardItem

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

See also

indexFromItem()

itemPrototype()#

Return type:: QStandardItem

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

See also

setItemPrototype()

setColumnCount(columns)#

Parameters:: columns – int

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

See also

columnCount() setRowCount()

setHorizontalHeaderItem(column, item)#

Parameters:

column – int
item – QStandardItem

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.

See also

horizontalHeaderItem() setHorizontalHeaderLabels() setVerticalHeaderItem()

setHorizontalHeaderLabels(labels)#

Parameters:: labels – list of strings

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

See also

setHorizontalHeaderItem()

setItem(row, item)#

Parameters:

row – int
item – QStandardItem

This is an overloaded function.

setItem(row, column, item)

Parameters:

row – int
column – int
item – QStandardItem

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.

See also

item()

setItemPrototype(item)#

Parameters:: item – QStandardItem

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 clone() function. To provide your own prototype, subclass QStandardItem , reimplement 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.

See also

itemPrototype() clone()

setItemRoleNames(roleNames)#

Parameters:: roleNames – Dictionary with keys of type .int and values of type QByteArray.

Sets the item role names to roleNames.

setRowCount(rows)#

Parameters:: rows – int

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

See also

rowCount() setColumnCount()

setSortRole(role)#

Parameters:: role – int