CopperSpice API  1.9.1
QStandardItem Class Reference

Used to create an item which is then passed to a QStandardItemModel. More...

Public Types

enum  ItemType
 

Public Methods

 QStandardItem ()
 
 QStandardItem (const QIcon &icon, const QString &text)
 
 QStandardItem (const QString &text)
 
 QStandardItem (int rows, int columns=1)
 
virtual ~QStandardItem ()
 
QString accessibleDescription () const
 
QString accessibleText () const
 
void appendColumn (const QList< QStandardItem * > &items)
 
void appendRow (const QList< QStandardItem * > &items)
 
void appendRow (QStandardItem *item)
 
void appendRows (const QList< QStandardItem * > &items)
 
QBrush background () const
 
Qt::CheckState checkState () const
 
QStandardItem * child (int row, int column=0) const
 
virtual QStandardItem * clone () const
 
int column () const
 
int columnCount () const
 
virtual QVariant data (int role=Qt::UserRole+1) const
 
Qt::ItemFlags flags () const
 
QFont font () const
 
QBrush foreground () const
 
bool hasChildren () const
 
QIcon icon () const
 
QModelIndex index () const
 
void insertColumn (int column, const QList< QStandardItem * > &items)
 
void insertColumns (int column, int count)
 
void insertRow (int row, const QList< QStandardItem * > &items)
 
void insertRow (int row, QStandardItem *item)
 
void insertRows (int row, const QList< QStandardItem * > &items)
 
void insertRows (int row, int count)
 
bool isAutoTristate () const
 
bool isCheckable () const
 
bool isDragEnabled () const
 
bool isDropEnabled () const
 
bool isEditable () const
 
bool isEnabled () const
 
bool isSelectable () const
 
bool isUserTristate () const
 
QStandardItemModelmodel () const
 
virtual bool operator< (const QStandardItem &other) const
 
QStandardItem * parent () const
 
virtual void read (QDataStream &in)
 
void removeColumn (int column)
 
void removeColumns (int column, int count)
 
void removeRow (int row)
 
void removeRows (int row, int count)
 
int row () const
 
int rowCount () const
 
void setAccessibleDescription (const QString &accessibleDescription)
 
void setAccessibleText (const QString &accessibleText)
 
void setAutoTristate (bool tristate)
 
void setBackground (const QBrush &brush)
 
void setCheckable (bool checkable)
 
void setCheckState (Qt::CheckState state)
 
void setChild (int row, int column, QStandardItem *item)
 
void setChild (int row, QStandardItem *item)
 
void setColumnCount (int columns)
 
virtual void setData (const QVariant &value, int role=Qt::UserRole+1)
 
void setDragEnabled (bool dragEnabled)
 
void setDropEnabled (bool dropEnabled)
 
void setEditable (bool editable)
 
void setEnabled (bool enabled)
 
void setFlags (Qt::ItemFlags flags)
 
void setFont (const QFont &font)
 
void setForeground (const QBrush &brush)
 
void setIcon (const QIcon &icon)
 
void setRowCount (int rows)
 
void setSelectable (bool selectable)
 
void setSizeHint (const QSize &size)
 
void setStatusTip (const QString &statusTip)
 
void setText (const QString &text)
 
void setTextAlignment (Qt::Alignment alignment)
 
void setToolTip (const QString &toolTip)
 
void setUserTristate (bool tristate)
 
void setWhatsThis (const QString &whatsThis)
 
QSize sizeHint () const
 
void sortChildren (int column, Qt::SortOrder order=Qt::AscendingOrder)
 
QString statusTip () const
 
QStandardItem * takeChild (int row, int column=0)
 
QList< QStandardItem * > takeColumn (int column)
 
QList< QStandardItem * > takeRow (int row)
 
QString text () const
 
Qt::Alignment textAlignment () const
 
QString toolTip () const
 
virtual int type () const
 
QString whatsThis () const
 
virtual void write (QDataStream &out) const
 

Protected Methods

 QStandardItem (const QStandardItem &other)
 
void emitDataChanged ()
 
QStandardItem & operator= (const QStandardItem &other)
 

Friends

class QStandardItemModel
 

Related Functions

These are not member functions

QDataStreamoperator<< (QDataStream &out, const QStandardItem &item)
 
QDataStreamoperator>> (QDataStream &in, QStandardItem &item)
 

Detailed Description

The QStandardItem class is used to create an item which is then passed to a QStandardItemModel. The properties of an item can be configured by setting flags using the method setFlags(). The default values for a item indicate it is enabled, can be edited, is selectable, and the item can be used as the source of a drag and drop and as a drop target.

If the item is a checkbox then the initial flags are set to checkable. Checkable items can be checked and unchecked with the setCheckState() method. The corresponding checkState() method indicates whether the item is currently checked.

Each item can have its own background brush which is set with the setBackground() method. The current background brush can be found by calling background(). The text label for each item can be rendered with its own font and brush. These are specified with the setFont() and setForeground() methods and read with font() and foreground().

The most common usage of QStandardItem and QStandardItemModel is to display the model data in a tree view.

Storing Data

Data is stored in an item by calling the setData() method.

When a new item is constructed it must be added to an existing QStandardItemModel by attaching it as a child of another QStandardItem. If the new item should appear at the top level it is added as a child of the root item of the model.

Each QStandardItem can have any number of children. When a child item is added to a parent item it is placed in a specific row and column in relation to the parent item. New rows and columns can be added using appendRow(), appendRows(), or appendColumn(). New rows and columns can be inserted with insertRow() or insertColumn().

A child item can be placed in a specific row/column by calling setChild(). The number of rows and columns can be set with setRowCount() and setColumnCount() and the new locations will be set to a nullptr.

Subclassing

When subclassing QStandardItem to provide a custom item you will need to reimplement various methods.

Method Description
type() Reimplement to return a new QStandardItem::ItemType value greater than UserType
data(), setData() Reimplement to perform custom handling of data queries and/or control how an item's data is represented
clone() Reimplement if you want QStandardItemModel to be able to create instances of your custom item class on demand, refer to QStandardItemModel::setItemPrototype()
read(), write() Reimplement to control how items are represented when they are serialized
operator<() Reimplement to control the semantics of item comparison, determines the sorted order when sorting items with sortChildren() or with QStandardItemModel::sort()
See also
QStandardItemModel, Model/View Architecture

Member Enumeration Documentation

This enum can be used when inheriting from QStandardItem to define new user types and ensure custom items are treated appropriately.

ConstantValueDescription
QStandardItem::Type0 Default type for standard items
QStandardItem::UserType1000 Minimum value for custom types. Values below UserType are reserved
See also
type()

Constructor & Destructor Documentation

QStandardItem::QStandardItem ( )

Constructs an item.

QStandardItem::QStandardItem ( const QString text)
explicit

Constructs an item with the given text.

QStandardItem::QStandardItem ( const QIcon icon,
const QString text 
)

Constructs an item with the given icon and text.

QStandardItem::QStandardItem ( int  rows,
int  columns = 1 
)
explicit

Constructs a single QStandardItem and allocates space for the given number of child items based on the values for rows and columns. Each child item is set to a nullptr.

QStandardItem::~QStandardItem ( )
virtual

Destroys the item and any of its children.

QStandardItem::QStandardItem ( const QStandardItem &  other)
protected

Copy constructs a new QStandardItem from other. The model is not copied by this method.

Method Documentation

QString QStandardItem::accessibleDescription ( ) const
inline

Returns the item's accessible description. This is used by assistive technologies such as screen readers.

See also
setAccessibleDescription(), accessibleText()
QString QStandardItem::accessibleText ( ) const
inline

Returns the item's accessible text. This is used by assistive technologies such as screen readers.

See also
setAccessibleText(), accessibleDescription()
void QStandardItem::appendColumn ( const QList< QStandardItem * > &  items)
inline

Appends the given items as a new column. If there are more items than rows, new rows will be added. If there are fewer items than rows the new locations will be set to a nullptr.

See also
insertColumn()
void QStandardItem::appendRow ( const QList< QStandardItem * > &  items)
inline

Appends the given items as a new row. If there are more items than columns, new columns will be added. If there are fewer items than columns the new locations will be set to a nullptr.

See also
insertRow()
void QStandardItem::appendRow ( QStandardItem *  item)
inline

Appends the given item as a new row. If there are multiple columns, the new column locations will be set to a nullptr.

void QStandardItem::appendRows ( const QList< QStandardItem * > &  items)
inline

Appends the given items, placing each one in a new row. If there are multiple columns, the new column locations will be set to a nullptr.

See also
insertRow()
QBrush QStandardItem::background ( ) const
inline

Returns the brush used to render the item's background.

See also
foreground(), setBackground()
Qt::CheckState QStandardItem::checkState ( ) const
inline

Returns the checked state of the item.

See also
setCheckState(), isCheckable()
QStandardItem * QStandardItem::child ( int  row,
int  column = 0 
) const

Returns the child item at the given row, column if one exists, otherwise returns a nullptr.

See also
setChild(), takeChild(), parent()
QStandardItem * QStandardItem::clone ( ) const
virtual

Returns a copy of this item without copying any child items. When inheriting from QStandardItem, the method must be reimplemented.

See also
QStandardItemModel::setItemPrototype(), operator=()
int QStandardItem::column ( ) const

Returns the column number where this item is located relative to its parent item, or -1 if this item has no parent.

See also
row(), parent()
int QStandardItem::columnCount ( ) const

Returns the number of child item columns for this item.

See also
setColumnCount(), rowCount()
QVariant QStandardItem::data ( int  role = Qt::UserRole + 1) const
virtual

Returns the data in this item with the given role, or an invalid QVariant if there is no data for the role. The default implementation treats Qt::EditRole and Qt::DisplayRole as referring to the same data.

See also
setData()
void QStandardItem::emitDataChanged ( )
protected

Causes the model associated with this item to emit a dataChanged() signal for this item. Normally this method is only useful when inheriting from QStandardItem and reimplementing data() or setData().

See also
setData()
Qt::ItemFlags QStandardItem::flags ( ) const

Returns the item flags for this item. The flags determine how the user can interact with the given item. The default values for a item indicate it is enabled, can be edited, is selectable, and the item can be used as the source of a drag and drop and as a drop target.

See also
setFlags()
QFont QStandardItem::font ( ) const
inline

Returns the font used to render the text for this item.

See also
setFont()
QBrush QStandardItem::foreground ( ) const
inline

Returns the brush used to render the foreground color for this item.

See also
setForeground(), background()
bool QStandardItem::hasChildren ( ) const

Returns true if this item has any children, otherwise returns false.

See also
rowCount(), columnCount(), child()
QIcon QStandardItem::icon ( ) const
inline

Returns the icon for this item.

See also
setIcon(), QAbstractItemView::iconSize
QModelIndex QStandardItem::index ( ) const

Returns the QModelIndex which corresponds to the location of this item in the model. If the item is not associated with a model an invalid QModelIndex is returned.

See also
model(), QStandardItemModel::itemFromIndex()
void QStandardItem::insertColumn ( int  column,
const QList< QStandardItem * > &  items 
)

Inserts a column at column containing items. If there are more items than rows, new rows will be added. If there are fewer items than rows the new locations will be set to a nullptr.

See also
insertColumns(), insertRow()
void QStandardItem::insertColumns ( int  column,
int  count 
)

Inserts the number of columns specified by count at the given column location.

See also
insertColumn(), insertRows()
void QStandardItem::insertRow ( int  row,
const QList< QStandardItem * > &  items 
)

Inserts the given items at the location of the given row. If there are more items than columns, new columns will be added. If there are fewer items than columns the new locations will be set to a nullptr.

See also
insertRows(), insertColumn()
void QStandardItem::insertRow ( int  row,
QStandardItem *  item 
)
inline

Inserts the given item at the location of the given row. If there are multiple columns, the new column locations will be set to a nullptr.

void QStandardItem::insertRows ( int  row,
const QList< QStandardItem * > &  items 
)

Inserts the given items placing each one in a separate row starting at the location of the given row. If there are multiple columns, the new column locations will be set to a nullptr.

See also
insertRow(), insertColumn()
void QStandardItem::insertRows ( int  row,
int  count 
)

Inserts the number of rows specified by count at the given row location.

See also
insertRow(), insertColumns()
bool QStandardItem::isAutoTristate ( ) const
inline

Returns whether the item is tristate and is controlled by QTreeWidget. The default value is false.

See also
isCheckable(), checkState(), setAutoTristate()
bool QStandardItem::isCheckable ( ) const
inline

Returns whether this item is checkable. The default value is false.

See also
setCheckable(), checkState(), isUserTristate(), isAutoTristate()
bool QStandardItem::isDragEnabled ( ) const
inline

Returns whether this item has drag enabled. The view must also having dragging enabled. The default value is true.

See also
setDragEnabled(), isDropEnabled(), flags()
bool QStandardItem::isDropEnabled ( ) const
inline

Returns whether the item is drop enabled. When an item is drop enabled it can be used as a drop target. The default value is true.

See also
setDropEnabled(), isDragEnabled(), flags()
bool QStandardItem::isEditable ( ) const
inline

Returns whether this item can be edited by the user. The default value is true.

See also
setEditable(), flags()
bool QStandardItem::isEnabled ( ) const
inline

Returns whether the item is enabled meaning the user can interact with it. Possible types of interaction are specified by the other item flags, such as isEditable() and isSelectable(). The default value is true.

See also
setEnabled(), flags()
bool QStandardItem::isSelectable ( ) const
inline

Returns whether this item is selectable by the user. The default value is true.

See also
setSelectable(), flags()
bool QStandardItem::isUserTristate ( ) const
inline

Returns whether the item is tristate. This is true if it is checkable with three separate states and the user can cycle through all three states. The default value is false.

See also
setUserTristate(), isCheckable(), checkState()
QStandardItemModel * QStandardItem::model ( ) const

Returns the QStandardItemModel which owns this item. If the item is not a child of another item in the model, this method returns a nullptr.

See also
index()
bool QStandardItem::operator< ( const QStandardItem &  other) const
virtual

Returns true if this item compares less than other, otherwise returns false. The default implementation compares the data for this item by retrieving the sort role from the model. If this item does not belong to a model the display role will be used.

The methods sortChildren() and QStandardItemModel::sort() use this method when sorting items.

QStandardItem & QStandardItem::operator= ( const QStandardItem &  other)
protected

Copy assigns from other and returns a reference to this object. The value of type() and model() are not copied.

QStandardItem * QStandardItem::parent ( ) const

Returns the parent item for this item or nullptr if this item has no parent.

See also
child()
void QStandardItem::read ( QDataStream in)
virtual

Reads this item from stream in. Only the data and flags of the item are read, not the child items.

See also
write()
void QStandardItem::removeColumn ( int  column)

Removes the given column. Any child items in the column are deleted.

See also
takeColumn(), removeColumns(), removeRow()
void QStandardItem::removeColumns ( int  column,
int  count 
)

Removes the number of columns specified by count starting from the given column. Any child items in those columns are deleted.

See also
removeColumn(), removeRows()
void QStandardItem::removeRow ( int  row)

Removes the given row. Any child items in the row are deleted.

See also
takeRow(), removeRows(), removeColumn()
void QStandardItem::removeRows ( int  row,
int  count 
)

Removes the number of rows specified by count starting from the given row. Any child items in those rows are deleted.

See also
removeRow(), removeColumn()
int QStandardItem::row ( ) const

Returns the row number where this item is located relative to its parent item, or -1 if this item has no parent.

See also
column(), parent()
int QStandardItem::rowCount ( ) const

Returns the number of child item rows for this item.

See also
setRowCount(), columnCount()
void QStandardItem::setAccessibleDescription ( const QString accessibleDescription)
inline

Sets the item's accessible description to the string specified by accessibleDescription. This is used by assistive technologies such as screen readers.

See also
accessibleDescription(), setAccessibleText()
void QStandardItem::setAccessibleText ( const QString accessibleText)
inline

Sets the item's accessible text to the string specified by accessibleText. This is used by assistive technologies such as screen readers.

See also
accessibleText(), setAccessibleDescription()
void QStandardItem::setAutoTristate ( bool  tristate)

Determines the item is tristate and controlled by QTreeWidget if tristate is true. This enables automatic management of the state of parent items in QTreeWidget (checked if all children are checked, unchecked if all children are unchecked, or partially checked if only some children are checked).

See also
isAutoTristate(), setCheckable(), setCheckState()
void QStandardItem::setBackground ( const QBrush brush)
inline

Sets the item's background brush to the specified brush.

See also
background(), setForeground()
void QStandardItem::setCheckable ( bool  checkable)

Sets whether the item is checkable. If checkable is true the item can be checked by the user otherwise the user can not check the item. The item delegate will display a checkable item with a check box next to the item's text.

See also
isCheckable(), setCheckState()
void QStandardItem::setCheckState ( Qt::CheckState  state)
inline

Sets the check state of the item to be state.

See also
checkState(), setCheckable()
void QStandardItem::setChild ( int  row,
int  column,
QStandardItem *  item 
)

Sets the child at the location (row, column) to the given item. The current item become the parent and takes ownership of the given item. If necessary the number of rows or columns will be increased.

See also
child()
void QStandardItem::setChild ( int  row,
QStandardItem *  item 
)
inline

Sets the child at the given row location in the first column, to the given item.

void QStandardItem::setColumnCount ( int  columns)

Sets the number of child item columns to columns. Any items located past the new number of columns are destroyed.

See also
columnCount(), setRowCount()
void QStandardItem::setData ( const QVariant value,
int  role = Qt::UserRole + 1 
)
virtual

Sets the data for this item for the given role to the specified value. If you inherit from QStandardItem and reimplement this method, your implementation must either call emitDataChanged() or the base implementation of setData().

The default implementation treats Qt::EditRole and Qt::DisplayRole as referring to the same data.

See also
data(), setFlags(), Qt::ItemDataRole
void QStandardItem::setDragEnabled ( bool  dragEnabled)

Sets whether this item is drag enabled. If dragEnabled is true the item can be dragged by the user, otherwise the user can not drag the item. You also need to ensure that item dragging is enabled in the view

See also
isDragEnabled(), setDropEnabled(), setFlags()
void QStandardItem::setDropEnabled ( bool  dropEnabled)

Sets whether this item is drop enabled. If dropEnabled is true the item can be used as a drop target, otherwise it can not. You must ensure drops are enabled in the view.

See also
isDropEnabled(), setDragEnabled(), setFlags()
void QStandardItem::setEditable ( bool  editable)

Sets whether the item is editable. If editable is true the item can be edited by the user, otherwise the user can not edit the item.

See also
isEditable(), setFlags()
void QStandardItem::setEnabled ( bool  enabled)

Sets whether the item is enabled. If enabled is true the item is enabled, meaning the user can interact with the item. If enabled is false, the user can not interact with the item. This flag takes precedence over some flags. For example, if an item is disabled it can not be selected by the user, even if the Qt::ItemIsSelectable flag has been set.

See also
isEnabled(), setFlags(), Qt::ItemFlag
void QStandardItem::setFlags ( Qt::ItemFlags  flags)

Sets this item flag to the given flags. The item flags determine how the user can interact with the item.

See also
flags(), setData()
void QStandardItem::setFont ( const QFont font)
inline

Sets the font used to display the item's text to the given font.

See also
font(), setText(), setForeground()
void QStandardItem::setForeground ( const QBrush brush)
inline

Sets the brush used to display the item's foreground color to the given brush.

See also
foreground(), setBackground(), setFont()
void QStandardItem::setIcon ( const QIcon icon)
inline

Sets the icon for this item to the icon specified.

See also
icon()
void QStandardItem::setRowCount ( int  rows)

Sets the number of child item rows to rows. Any items located past the new number of rows are destroyed.

See also
rowCount(), setColumnCount()
void QStandardItem::setSelectable ( bool  selectable)

Sets whether this item is selectable. If selectable is true, the item can be selected by the user, otherwise the user can not select the item.

See also
isSelectable(), setFlags()
void QStandardItem::setSizeHint ( const QSize size)
inline

Sets the size hint for the item to the given size. If no size hint is set the item delegate will compute the size hint based on the item data.

See also
sizeHint()
void QStandardItem::setStatusTip ( const QString statusTip)
inline

Sets the status tip for this item to the string specified by statusTip.

See also
statusTip(), setToolTip(), setWhatsThis()
void QStandardItem::setText ( const QString text)
inline

Sets the text for this item to the text specified.

See also
text(), setFont(), setForeground()
void QStandardItem::setTextAlignment ( Qt::Alignment  alignment)
inline

Sets the text alignment for this item to the alignment specified.

See also
textAlignment()
void QStandardItem::setToolTip ( const QString toolTip)
inline

Sets the tooltip for this item to the string specified by toolTip.

See also
toolTip(), setStatusTip(), setWhatsThis()
void QStandardItem::setUserTristate ( bool  tristate)

Sets whether the item is tristate and controlled by the user. If tristate is true the user can cycle through three separate states, otherwise, the item is checkable with two states. This also requires that the item is checkable.

See also
isUserTristate(), setCheckable(), setCheckState()
void QStandardItem::setWhatsThis ( const QString whatsThis)
inline

Sets the "What's This" text for this item to the string specified by whatsThis.

See also
whatsThis(), setStatusTip(), setToolTip()
QSize QStandardItem::sizeHint ( ) const
inline

Returns the size hint set for the item or an invalid QSize if no size hint has been set. If no size hint has been set, the item delegate will compute the size hint based on the item data.

See also
setSizeHint()
void QStandardItem::sortChildren ( int  column,
Qt::SortOrder  order = Qt::AscendingOrder 
)

Sorts the children of this item using the given order based on the values in the given column.

See also
operator<()
QString QStandardItem::statusTip ( ) const
inline

Returns the status tip for this item.

See also
setStatusTip(), toolTip(), whatsThis()
QStandardItem * QStandardItem::takeChild ( int  row,
int  column = 0 
)

Removes the child item at the location row, column without deleting it. Returns a pointer to this item. If there was no child at the given location this method returns a nullptr.

See also
child(), takeRow(), takeColumn()
QList< QStandardItem * > QStandardItem::takeColumn ( int  column)

Removes the given column without deleting the items in that column. Returns a list of pointers to the removed items. Any location which does not have an item will be set to a nullptr.

See also
removeColumn(), insertColumn(), takeRow()
QList< QStandardItem * > QStandardItem::takeRow ( int  row)

Removes the given row without deleting the items in that row. Returns a list of pointers to the removed items. Any location which does not have an item will be set to a nullptr.

See also
removeRow(), insertRow(), takeColumn()
QString QStandardItem::text ( ) const
inline

Returns the text for this item.

See also
setText()
Qt::Alignment QStandardItem::textAlignment ( ) const
inline

Returns the text alignment for this item.

See also
setTextAlignment()
QString QStandardItem::toolTip ( ) const
inline

Returns the tooltip for this item.

See also
setToolTip(), statusTip(), whatsThis()
int QStandardItem::type ( ) const
virtual

Returns the type for this item. The type is used to distinguish custom items from the base class. When inheriting QStandardItem reimplement this method and return a new value greater than or equal to UserType.

See also
QStandardItem::ItemType
QString QStandardItem::whatsThis ( ) const
inline

Returns the "What's This?" text for this item.

See also
setWhatsThis(), toolTip(), statusTip()
void QStandardItem::write ( QDataStream out) const
virtual

Writes the item to stream out. Only the data and flags of the item are written, not the child items.

See also
read()

Friends And Related Function Documentation

QDataStream & operator<< ( QDataStream out,
const QStandardItem &  item 
)
related

Writes the QStandardItem item to stream out and returns a reference to the stream. This operator uses QStandardItem::write().

Refer to Serializing Data Types for additional information.

QDataStream & operator>> ( QDataStream in,
QStandardItem &  item 
)
related

Reads a QStandardItem from stream in into item and returns a reference to the stream. This operator uses QStandardItem::read().

Refer to Serializing Data Types for additional information.