CopperSpice API  1.7.2
QStandardItem Class Reference

The QStandardItem class provides an item for use with the QStandardItemModel class. 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 checkState)
 
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 &sizeHint)
 
void setStatusTip (const QString &statusTip)
 
void setText (const QString &text)
 
void setTextAlignment (Qt::Alignment textAlignment)
 
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 provides an item for use with the QStandardItemModel class. Items usually contain text, icons, or checkboxes.

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

By default, items are enabled, editable, selectable, checkable, and can be used both as the source of a drag and drop operation and as a drop target. Each item's flags can be changed by calling setFlags(). Checkable items can be checked and unchecked with the setCheckState() function. The corresponding checkState() function indicates whether the item is currently checked.

You can store application-specific data in an item by calling setData().

Each item can have a two-dimensional table of child items. This makes it possible to build hierarchies of items. The typical hierarchy is the tree, in which case the child table is a table with a single column (a list).

The dimensions of the child table can be set with setRowCount() and setColumnCount(). Items can be positioned in the child table with setChild(). Get a pointer to a child item with child(). New rows and columns of children can also be inserted with insertRow() and insertColumn(), or appended with appendRow() and appendColumn(). When using the append and insert functions, the dimensions of the child table will grow as needed.

An existing row of children can be removed with removeRow() or takeRow(); correspondingly, a column can be removed with removeColumn() or takeColumn().

An item's children can be sorted by calling sortChildren().

Subclassing

When subclassing QStandardItem to provide custom items, it is possible to define new types for them so that they can be distinguished from the base class. The type() function should be reimplemented to return a new type value equal to or greater than UserType.

Reimplement data() and setData() if you want to perform custom handling of data queries and/or control how an item's data is represented.

Reimplement clone() if you want QStandardItemModel to be able to create instances of your custom item class on demand (see QStandardItemModel::setItemPrototype()).

Reimplement read() and write() if you want to control how items are represented in their serialized form.

Reimplement operator<() if you want to control the semantics of item comparison. operator<() determines the sorted order when sorting items with sortChildren() or with QStandardItemModel::sort().

See also
QStandardItemModel, Item View Convenience Classes, Model/View Programming

Member Enumeration Documentation

This enum describes the types that are used to describe standard items.

ConstantValueDescription
QStandardItem::Type0The default type for standard items.
QStandardItem::UserType1000The minimum value for custom types. Values below UserType are reserved for CopperSpice.

You can define new user types in QStandardItem subclasses to ensure that custom items are treated specially; for example, when items are sorted.

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 an item with rows rows and columns columns of child items.

QStandardItem::~QStandardItem ( )
virtual

Destructs the item. This causes the item's children to be destructed as well.

QStandardItem::QStandardItem ( const QStandardItem &  other)
protected

Constructs a copy of other. Note that model() is not copied.

This function is useful when reimplementing clone().

Method Documentation

QString QStandardItem::accessibleDescription ( ) const
inline

Returns the item's accessible description.

The accessible description is used by assistive technologies (i.e. for users who can not use conventional means of interaction).

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

Returns the item's accessible text.

The accessible text is used by assistive technologies (i.e. for users who can not use conventional means of interaction).

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

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

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

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

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

Appends a 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.

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

Appends rows containing items. The column count will not change.

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 row, column if one has been set, otherwise returns a nullptr.

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

Returns a copy of this item. The item's children are not copied.

When subclassing QStandardItem, you can reimplement this function to provide QStandardItemModel with a factory that it can use to create new items on demand.

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

Returns the column where the item is located in its parent's child table, or -1 if the item has no parent.

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

Returns the number of child item columns that the item has.

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

Returns the item's data for the given role, or an invalid QVariant if there is no data for the role.

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

You normally only need to call this function if you have subclassed QStandardItem and reimplemented data() and/or setData().

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

Returns the item flags for the item.

The item flags determine how the user can interact with the item.

By default, items are enabled, editable, selectable, checkable, and can be used both as the source of a drag and drop operation and as a drop target.

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

Returns the font used to render the item's text.

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

Returns the brush used to render the item's foreground (e.g. text).

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 item's icon.

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

Returns the QModelIndex associated with this item.

When you need to invoke item functionality in a QModelIndex-based API (e.g. QAbstractItemView), you can call this function to obtain an index that corresponds to the item's location 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 necessary, the row count is increased to the size of items.

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

Inserts count columns of child items at column column.

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

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

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

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 insert a single new item.

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

Inserts items at row. The column count wont be changed.

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

Inserts count rows of child items at row row.

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

Property documentation pending.

bool QStandardItem::isCheckable ( ) const
inline

Returns whether the item is user-checkable.

The default value is false.

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

Returns whether the item is drag enabled. An item that is drag enabled can be dragged by the user.

The default value is true.

Note that item dragging must be enabled in the view for dragging to work; see QAbstractItemView::dragEnabled.

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 the item can be edited by the user.

When an item is editable (and enabled), the user can edit the item by invoking one of the view's edit triggers; see QAbstractItemView::editTriggers.

The default value is true.

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

Returns whether the item is enabled.

When an item is enabled, the user can interact with it. The 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 the item is selectable by the user.

The default value is true.

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

Property documentation pending.

QStandardItemModel * QStandardItem::model ( ) const

Returns the QStandardItemModel that this item belongs to. If the item is not a child of another item that belongs to the model, this method returns a nullptr.

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

Returns true if this item is less than other, otherwise returns false.

The default implementation uses the data for the item's sort role (see QStandardItemModel::sortRole) to perform the comparison if the item belongs to a model, otherwise the data for the item's Qt::DisplayRole(text()) is used to perform the comparison.

sortChildren() and QStandardItemModel::sort() use this function when sorting items. If you want custom sorting, you can subclass QStandardItem and reimplement this function.

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

Assigns other's data and flags to this item. Note that type() and model() are not copied.

This function is useful when reimplementing clone().

QStandardItem * QStandardItem::parent ( ) const

Returns the item's parent item, or 0 if the item has no parent.

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

Reads the 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. The items that were in the column are deleted.

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

Removes count columns at column column. The items that were in those columns are deleted.

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

Removes the given row. The items that were in the row are deleted.

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

Removes count rows at row row. The items that were in those rows are deleted.

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

Returns the row where the item is located in its parent's child table, or -1 if the item has no parent.

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

Returns the number of child item rows that the item has.

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

Sets the item's accessible description to the string specified by accessibleDescription.

The accessible description is used by assistive technologies (i.e. for users who can not use conventional means of interaction).

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

Sets the item's accessible text to the string specified by accessibleText.

The accessible text is used by assistive technologies (i.e. for users who can not use conventional means of interaction).

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

Property documentation pending.

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 user-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 render a checkable item with a check box next to the item's text.

See also
isCheckable(), setCheckState()
void QStandardItem::setCheckState ( Qt::CheckState  checkState)
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 item at (row, column) to item. This item (the parent item) takes ownership of item. If necessary, the row count and column count are increased to fit the item.

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

Sets the child at row to item.

void QStandardItem::setColumnCount ( int  columns)

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

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

Sets the item's data for the given role to the specified value.

If you subclass QStandardItem and reimplement this function, your reimplementation should call emitDataChanged() if you do not call the base implementation of setData(). This will ensure that e.g. views using the model are notified of the changes.

Note
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 the item is drag enabled. If dragEnabled is true, the item can be dragged by the user, otherwise the user can not drag the item.

Note that you also need to ensure that item dragging is enabled in the view; see QAbstractItemView::dragEnabled.

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

Sets whether the item is drop enabled. If dropEnabled is true, the item can be used as a drop target, otherwise it can not.

Note that you also need to ensure that drops are enabled in the view; see QWidget::acceptDrops(); and that the model supports the desired drop actions; see QAbstractItemModel::supportedDropActions().

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.

How the user can edit items in a view is determined by the view's edit triggers; see QAbstractItemView::editTriggers.

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

Sets whether the item is enabled. If enabled is true, the item is enabled, meaning that the user can interact with the item; if enabled is false, the user can not interact with the item.

This flag takes precedence over the other item flags; e.g. if an item is not enabled, it can not be selected by the user, even if the Qt::ItemIsSelectable flag has been set.

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

Sets the item flags for the item to flags.

The item flags determine how the user can interact with the item. This is often used to disable an 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 (e.g. text) to the given brush.

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

Sets the item's icon to the icon specified.

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

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

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

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

You can control the selection behavior and mode by manipulating their view properties; see QAbstractItemView::selectionMode and QAbstractItemView::selectionBehavior.

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

Sets the size hint for the item to be 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 item's status tip to the string specified by statusTip.

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

Sets the item's text to the text specified.

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

Sets the text alignment for the item's text to the alignment specified.

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

Sets the item's tooltip to the string specified by toolTip.

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

Property documentation pending.

void QStandardItem::setWhatsThis ( const QString whatsThis)
inline

Sets the item's "What's This?" help 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 the item using the given order, by the values in the given column.

Note
This function is recursive, therefore it sorts the children of the item, its grandchildren, etc.
See also
operator<()
QString QStandardItem::statusTip ( ) const
inline

Returns the item's status tip.

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

Removes the child item at row, column without deleting it, and returns a pointer to the item. If there was no child at the given location, this methods returns a nullptr. Unlike takeRow() and takeColumn(), this methods does not affect the dimensions of the child table.

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

Removes column without deleting the column items, and returns a list of pointers to the removed items. For items in the column that have not been set, the corresponding pointers in the list will be a nullptr.

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

Removes row without deleting the row items, and returns a list of pointers to the removed items. For items in the row that have not been set, the corresponding pointers in the list will be 0.

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

Returns the item's text. This is the text that's presented to the user in a view.

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

Returns the text alignment for the item's text.

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

Returns the item's tooltip.

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

Returns the type of this item. The type is used to distinguish custom items from the base class. When subclassing QStandardItem, you should reimplement this function and return a new value greater than or equal to UserType.

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

Returns the item's "What's This?" help.

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. This operator uses QStandardItem::write().

See also
Refer to Serializing Data Types for additional information
QDataStream & operator>> ( QDataStream in,
QStandardItem &  item 
)
related

Reads a QStandardItem from stream in into item. This operator uses QStandardItem::read().

See also
Refer to Serializing Data Types for additional information