QStandardItemModel¶
The
QStandardItemModel
class provides a generic model for storing custom data. More…
Synopsis¶
Functions¶
def
appendColumn
(items)def
appendRow
(item)def
appendRow
(items)def
clear
()def
clearItemData
(index)def
findItems
(text[, flags=Qt.MatchExactly[, column=0]])def
horizontalHeaderItem
(column)def
indexFromItem
(item)def
insertColumn
(column, items)def
insertRow
(row, item)def
insertRow
(row, items)def
invisibleRootItem
()def
item
(row[, column=0])def
itemFromIndex
(index)def
itemPrototype
()def
setColumnCount
(columns)def
setHorizontalHeaderItem
(column, item)def
setHorizontalHeaderLabels
(labels)def
setItem
(row, column, item)def
setItem
(row, item)def
setItemPrototype
(item)def
setItemRoleNames
(roleNames)def
setRowCount
(rows)def
setSortRole
(role)def
setVerticalHeaderItem
(row, item)def
setVerticalHeaderLabels
(labels)def
sortRole
()def
takeColumn
(column)def
takeHorizontalHeaderItem
(column)def
takeItem
(row[, column=0])def
takeRow
(row)def
takeVerticalHeaderItem
(row)def
verticalHeaderItem
(row)
Signals¶
def
itemChanged
(item)
Detailed Description¶
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 aQStandardItemModel
are provided byQStandardItem
.
QStandardItemModel
implements theQAbstractItemModel
interface, which means that the model can be used to provide data in any view that supports that interface (such asQListView
,QTableView
andQTreeView
, and your own custom views). For performance and flexibility, you may want to subclassQAbstractItemModel
to provide support for different kinds of data repositories. For example, theQDirModel
provides a model interface to the underlying file system.When you want a list or tree, you typically create an empty
QStandardItemModel
and useappendRow()
to add items to the model, anditem()
to access an item. If your model represents a table, you typically pass the dimensions of the table to theQStandardItemModel
constructor and usesetItem()
to position items into the table. You can also usesetRowCount()
andsetColumnCount()
to alter the dimensions of the model. To insert items, useinsertRow()
orinsertColumn()
, and to remove items, useremoveRow()
orremoveColumn()
.You can set the header labels of your model with
setHorizontalHeaderLabels()
andsetVerticalHeaderLabels()
.You can search for items in the model with
findItems()
, and sort the model by callingsort()
.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(4): for column in range(4): item = QStandardItem("row %d, column %d" % (row, column)) model.setItem(row, column, item)An example usage of
QStandardItemModel
to create a tree:model = QStandardItemModel() parentItem = model.invisibleRootItem() for i in range(4): item = QStandardItem("item %d" % i) parentItem.appendRow(item) parentItem = itemAfter setting the model on a view, you typically want to react to user actions, such as an item being clicked. Since a
QAbstractItemView
providesQModelIndex
-based signals and functions, you need a way to obtain theQStandardItem
that corresponds to a givenQModelIndex
, and vice versa.itemFromIndex()
andindexFromItem()
provide this mapping. Typical usage ofitemFromIndex()
includes obtaining the item at the current index in a view, and obtaining the item that corresponds to an index carried by aQAbstractItemView
signal, such asclicked()
. First you connect the view’s signal to a slot in your class:treeView = QTreeView(self) treeView.setModel(myStandardItemModel) treeView.clicked[QModelIndex].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’sindexFromItem()
function, or, equivalently, by callingindex()
: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 ProgrammingQAbstractItemModel
Simple Tree Model example Item View Convenience Classes
- class PySide2.QtGui.QStandardItemModel([parent=None])¶
PySide2.QtGui.QStandardItemModel(rows, columns[, parent=None])
- param parent:
- param columns:
int
- param rows:
int
Constructs a new item model with the given
parent
.Constructs a new item model that initially has
rows
rows andcolumns
columns, and that has the givenparent
.
- PySide2.QtGui.QStandardItemModel.appendColumn(items)¶
- Parameters:
items –
Appends a column containing
items
. If necessary, the row count is increased to the size ofitems
.See also
- PySide2.QtGui.QStandardItemModel.appendRow(item)¶
- Parameters:
item –
PySide2.QtGui.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
.
- PySide2.QtGui.QStandardItemModel.appendRow(items)
- Parameters:
items –
- PySide2.QtGui.QStandardItemModel.clear()¶
Removes all items (including header items) from the model and sets the number of rows and columns to zero.
See also
removeColumns()
removeRows()
- PySide2.QtGui.QStandardItemModel.clearItemData(index)¶
- Parameters:
index –
PySide2.QtCore.QModelIndex
- Return type:
bool
Removes the data stored in all the roles for the given
index
. Returnstrue
ifindex
is valid and data was cleared,false
otherwise.See also
setData()
data()
- PySide2.QtGui.QStandardItemModel.findItems(text[, flags=Qt.MatchExactly[, column=0]])¶
- Parameters:
text – str
flags –
MatchFlags
column – int
- Return type:
Returns a list of items that match the given
text
, using the givenflags
, in the givencolumn
.
- PySide2.QtGui.QStandardItemModel.horizontalHeaderItem(column)¶
- Parameters:
column – int
- Return type:
Returns the horizontal header item for
column
if one has been set; otherwise returnsNone
.
- PySide2.QtGui.QStandardItemModel.indexFromItem(item)¶
- Parameters:
item –
PySide2.QtGui.QStandardItem
- Return type:
Returns the
QModelIndex
associated with the givenitem
.Use this function when you want to perform an operation that requires the
QModelIndex
of the item, such asscrollTo()
.index()
is provided as convenience; it is equivalent to calling this function.See also
- PySide2.QtGui.QStandardItemModel.insertColumn(column, items)¶
- Parameters:
column – int
items –
- PySide2.QtGui.QStandardItemModel.insertRow(row, item)¶
- Parameters:
row – int
item –
PySide2.QtGui.QStandardItem
This is an overloaded function.
Inserts a row at
row
containingitem
.When building a list or a tree that has only one column, this function provides a convenient way to append a single new item.
- PySide2.QtGui.QStandardItemModel.insertRow(row, items)
- Parameters:
row – int
items –
- PySide2.QtGui.QStandardItemModel.invisibleRootItem()¶
- Return type:
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 theQStandardItem
object retrieved from this function is not valid.
- PySide2.QtGui.QStandardItemModel.item(row[, column=0])¶
- Parameters:
row – int
column – int
- Return type:
Returns the item for the given
row
andcolumn
if one has been set; otherwise returnsNone
.See also
- PySide2.QtGui.QStandardItemModel.itemChanged(item)¶
- Parameters:
item –
PySide2.QtGui.QStandardItem
- PySide2.QtGui.QStandardItemModel.itemFromIndex(index)¶
- Parameters:
index –
PySide2.QtCore.QModelIndex
- Return type:
Returns a pointer to the
QStandardItem
associated with the givenindex
.Calling this function is typically the initial step when processing
QModelIndex
-based signals from a view, such asactivated()
. In your slot, you call , with theQModelIndex
carried by the signal as argument, to obtain a pointer to the correspondingQStandardItem
.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 returnsNone
.See also
- PySide2.QtGui.QStandardItemModel.itemPrototype()¶
- Return type:
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
- PySide2.QtGui.QStandardItemModel.setColumnCount(columns)¶
- Parameters:
columns – int
Sets the number of columns in this model to
columns
. If this is less thancolumnCount()
, the data in the unwanted columns is discarded.See also
columnCount()
setRowCount()
- PySide2.QtGui.QStandardItemModel.setHorizontalHeaderItem(column, item)¶
- Parameters:
column – int
item –
PySide2.QtGui.QStandardItem
Sets the horizontal header item for
column
toitem
. 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.
- PySide2.QtGui.QStandardItemModel.setHorizontalHeaderLabels(labels)¶
- Parameters:
labels – list of strings
Sets the horizontal header labels using
labels
. If necessary, the column count is increased to the size oflabels
.See also
- PySide2.QtGui.QStandardItemModel.setItem(row, item)¶
- Parameters:
row – int
item –
PySide2.QtGui.QStandardItem
This is an overloaded function.
- PySide2.QtGui.QStandardItemModel.setItem(row, column, item)
- Parameters:
row – int
column – int
item –
PySide2.QtGui.QStandardItem
Sets the item for the given
row
andcolumn
toitem
. 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
- PySide2.QtGui.QStandardItemModel.setItemPrototype(item)¶
- Parameters:
item –
PySide2.QtGui.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 theclone()
function. To provide your own prototype, subclassQStandardItem
, reimplementclone()
and set the prototype to be an instance of your custom class. WheneverQStandardItemModel
needs to create an item on demand (for instance, when a view or item delegate callssetData()
)), the new items will be instances of your custom class.See also
- PySide2.QtGui.QStandardItemModel.setItemRoleNames(roleNames)¶
- Parameters:
roleNames –
Sets the item role names to
roleNames
.
- PySide2.QtGui.QStandardItemModel.setRowCount(rows)¶
- Parameters:
rows – int
Sets the number of rows in this model to
rows
. If this is less thanrowCount()
, the data in the unwanted rows is discarded.See also
rowCount()
setColumnCount()
- PySide2.QtGui.QStandardItemModel.setSortRole(role)¶
- Parameters:
role – int
This property holds the item role that is used to query the model’s data when sorting items.
The default value is
DisplayRole
.See also
sort()
sortChildren()
- PySide2.QtGui.QStandardItemModel.setVerticalHeaderItem(row, item)¶
- Parameters:
row – int
item –
PySide2.QtGui.QStandardItem
Sets the vertical header item for
row
toitem
. 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.
- PySide2.QtGui.QStandardItemModel.setVerticalHeaderLabels(labels)¶
- Parameters:
labels – list of strings
Sets the vertical header labels using
labels
. If necessary, the row count is increased to the size oflabels
.See also
- PySide2.QtGui.QStandardItemModel.sortRole()¶
- Return type:
int
This property holds the item role that is used to query the model’s data when sorting items.
The default value is
DisplayRole
.See also
sort()
sortChildren()
- PySide2.QtGui.QStandardItemModel.takeColumn(column)¶
- Parameters:
column – int
- Return type:
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 beNone
.See also
- PySide2.QtGui.QStandardItemModel.takeHorizontalHeaderItem(column)¶
- Parameters:
column – int
- Return type:
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.
- PySide2.QtGui.QStandardItemModel.takeItem(row[, column=0])¶
- Parameters:
row – int
column – int
- Return type:
Removes the item at (
row
,column
) without deleting it. The model releases ownership of the item.See also
- PySide2.QtGui.QStandardItemModel.takeRow(row)¶
- Parameters:
row – int
- Return type:
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 beNone
.See also
- PySide2.QtGui.QStandardItemModel.takeVerticalHeaderItem(row)¶
- Parameters:
row – int
- Return type:
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.
- PySide2.QtGui.QStandardItemModel.verticalHeaderItem(row)¶
- Parameters:
row – int
- Return type:
Returns the vertical header item for row
row
if one has been set; otherwise returnsNone
.
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.