Contents

• Public Types
• Public Functions
• Protected Functions
• Related Non-Members
• Detailed Description
• Subclassing

Detailed Description

TheQStandardItem class provides an item for use with theQStandardItemModel class.

Items usually contain text, icons, or checkboxes.

Each item can have its own background brush which is set with thesetBackground() function. The current background brush can be found withbackground(). The text label for each item can be rendered with its own font and brush. These are specified with thesetFont() andsetForeground() functions, and read withfont() andforeground().

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 callingsetFlags(). Checkable items can be checked and unchecked with thesetCheckState() function. The correspondingcheckState() function indicates whether the item is currently checked.

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

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 withsetRowCount() andsetColumnCount(). Items can be positioned in the child table withsetChild(). Get a pointer to a child item withchild(). New rows and columns of children can also be inserted withinsertRow() andinsertColumn(), or appended withappendRow() andappendColumn(). 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 withremoveRow() ortakeRow(); correspondingly, a column can be removed withremoveColumn() ortakeColumn().

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

Subclassing

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

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

Reimplementclone() if you wantQStandardItemModel to be able to create instances of your custom item class on demand (seeQStandardItemModel::setItemPrototype()).

Reimplementread() andwrite() if you want to control how items are represented in their serialized form.

Reimplementoperator<() if you want to control the semantics of item comparison.operator<() determines the sorted order when sorting items withsortChildren() or withQStandardItemModel::sort().

Member Type Documentation

enum QStandardItem::ItemType

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

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

See alsotype().

Member Function Documentation

QStandardItem::QStandardItem()

Constructs an item.

QStandardItem::QStandardItem(constQString & text)

Constructs an item with the giventext.

QStandardItem::QStandardItem(constQIcon & icon, constQString & text)

Constructs an item with the givenicon andtext.

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

Constructs an item withrows rows andcolumns columns of child items.

[protected]QStandardItem::QStandardItem(constQStandardItem & other)

Constructs a copy ofother. Note thatmodel() is not copied.

This function is useful when reimplementingclone().

[virtual]QStandardItem::~QStandardItem()

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

QString QStandardItem::accessibleDescription() const

Returns the item's accessible description.

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

See alsosetAccessibleDescription() andaccessibleText().

QString QStandardItem::accessibleText() const

Returns the item's accessible text.

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

See alsosetAccessibleText() andaccessibleDescription().

void QStandardItem::appendColumn(constQList<QStandardItem *> & items)

Appends a column containingitems. If necessary, the row count is increased to the size ofitems.

See alsoinsertColumn().

void QStandardItem::appendRow(constQList<QStandardItem *> & items)

Appends a row containingitems. If necessary, the column count is increased to the size ofitems.

See alsoinsertRow().

void QStandardItem::appendRow(QStandardItem * item)

This is an overloaded function.

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

void QStandardItem::appendRows(constQList<QStandardItem *> & items)

Appends rows containingitems. The column count will not change.

See alsoinsertRow().

QBrush QStandardItem::background() const

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

See alsoforeground() andsetBackground().

Qt::CheckState QStandardItem::checkState() const

Returns the checked state of the item.

See alsosetCheckState() andisCheckable().

QStandardItem * QStandardItem::child(int row,int column = 0) const

Returns the child item at (row,column) if one has been set; otherwise returns 0.

See alsosetChild(),takeChild(), andparent().

[virtual]QStandardItem * QStandardItem::clone() const

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

When subclassingQStandardItem, you can reimplement this function to provideQStandardItemModel with a factory that it can use to create new items on demand.

See alsoQStandardItemModel::setItemPrototype() andoperator=().

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

int QStandardItem::columnCount() const

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

See alsosetColumnCount() androwCount().

[virtual]QVariant QStandardItem::data(int role = Qt::UserRole + 1) const

Returns the item's data for the givenrole, or an invalidQVariant if there is no data for the role.

Note:The default implementation treatsQt::EditRole andQt::DisplayRole as referring to the same data.

See alsosetData().

[protected]void QStandardItem::emitDataChanged()

Causes the model associated with this item to emit adataChanged() signal for this item.

You normally only need to call this function if you have subclassedQStandardItem and reimplementeddata() and/orsetData().

This function was introduced in Qt 4.4.

See alsosetData().

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

QFont QStandardItem::font() const

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

See alsosetFont().

QBrush QStandardItem::foreground() const

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

See alsosetForeground() andbackground().

bool QStandardItem::hasChildren() const

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

See alsorowCount(),columnCount(), andchild().

QIcon QStandardItem::icon() const

Returns the item's icon.

See alsosetIcon() andiconSize.

QModelIndex QStandardItem::index() const

Returns theQModelIndex associated with this item.

When you need to invoke item functionality in aQModelIndex-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 invalidQModelIndex is returned.

See alsomodel() andQStandardItemModel::itemFromIndex().

void QStandardItem::insertColumn(int column, constQList<QStandardItem *> & items)

Inserts a column atcolumn containingitems. If necessary, the row count is increased to the size ofitems.

See alsoinsertColumns() andinsertRow().

void QStandardItem::insertColumns(int column,int count)

Insertscount columns of child items at columncolumn.

See alsoinsertColumn() andinsertRows().

void QStandardItem::insertRow(int row, constQList<QStandardItem *> & items)

Inserts a row atrow containingitems. If necessary, the column count is increased to the size ofitems.

See alsoinsertRows() andinsertColumn().

void QStandardItem::insertRow(int row,QStandardItem * item)

This is an overloaded function.

Inserts a row atrow containingitem.

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, constQList<QStandardItem *> & items)

Insertsitems atrow. The column count wont be changed.

See alsoinsertRow() andinsertColumn().

void QStandardItem::insertRows(int row,int count)

Insertscount rows of child items at rowrow.

See alsoinsertRow() andinsertColumns().

bool QStandardItem::isCheckable() const

Returns whether the item is user-checkable.

The default value is false.

See alsosetCheckable(),checkState(), andisTristate().

bool QStandardItem::isDragEnabled() const

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; seeQAbstractItemView::dragEnabled.

See alsosetDragEnabled(),isDropEnabled(), andflags().

bool QStandardItem::isDropEnabled() const

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 alsosetDropEnabled(),isDragEnabled(), andflags().

bool QStandardItem::isEditable() const

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; seeQAbstractItemView::editTriggers.

The default value is true.

See alsosetEditable() andflags().

bool QStandardItem::isEnabled() const

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

The default value is true.

See alsosetEnabled() andflags().

bool QStandardItem::isSelectable() const

Returns whether the item is selectable by the user.

The default value is true.

See alsosetSelectable() andflags().

bool QStandardItem::isTristate() const

Returns whether the item is tristate; that is, if it's checkable with three separate states.

The default value is false.

See alsosetTristate(),isCheckable(), andcheckState().

QStandardItemModel * QStandardItem::model() const

Returns theQStandardItemModel that this item belongs to.

If the item is not a child of another item that belongs to the model, this function returns 0.

See alsoindex().

QStandardItem * QStandardItem::parent() const

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

See alsochild().

[virtual]void QStandardItem::read(QDataStream & in)

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

See alsowrite().

void QStandardItem::removeColumn(int column)

Removes the givencolumn. The items that were in the column are deleted.

See alsotakeColumn(),removeColumns(), andremoveRow().

void QStandardItem::removeColumns(int column,int count)

Removescount columns at columncolumn. The items that were in those columns are deleted.

See alsoremoveColumn() andremoveRows().

void QStandardItem::removeRow(int row)

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

See alsotakeRow(),removeRows(), andremoveColumn().

void QStandardItem::removeRows(int row,int count)

Removescount rows at rowrow. The items that were in those rows are deleted.

See alsoremoveRow() andremoveColumn().

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

int QStandardItem::rowCount() const

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

See alsosetRowCount() andcolumnCount().

void QStandardItem::setAccessibleDescription(constQString & accessibleDescription)

Sets the item's accessible description to the string specified byaccessibleDescription.

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

See alsoaccessibleDescription() andsetAccessibleText().

void QStandardItem::setAccessibleText(constQString & accessibleText)

Sets the item's accessible text to the string specified byaccessibleText.

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

See alsoaccessibleText() andsetAccessibleDescription().

void QStandardItem::setBackground(constQBrush & brush)

Sets the item's background brush to the specifiedbrush.

See alsobackground() andsetForeground().

void QStandardItem::setCheckState(Qt::CheckState state)

Sets the check state of the item to bestate.

See alsocheckState() andsetCheckable().

void QStandardItem::setCheckable(bool checkable)

Sets whether the item is user-checkable. Ifcheckable is true, the item can be checked by the user; otherwise, the user cannot check the item.

The item delegate will render a checkable item with a check box next to the item's text.

See alsoisCheckable(),setCheckState(), andsetTristate().

void QStandardItem::setChild(int row,int column,QStandardItem * item)

Sets the child item at (row,column) toitem. This item (the parent item) takes ownership ofitem. If necessary, the row count and column count are increased to fit the item.

See alsochild().

void QStandardItem::setChild(int row,QStandardItem * item)

This is an overloaded function.

Sets the child atrow toitem.

void QStandardItem::setColumnCount(int columns)

Sets the number of child item columns tocolumns. If this is less thancolumnCount(), the data in the unwanted columns is discarded.

See alsocolumnCount() andsetRowCount().

[virtual]void QStandardItem::setData(constQVariant & value,int role = Qt::UserRole + 1)

Sets the item's data for the givenrole to the specifiedvalue.

If you subclassQStandardItem and reimplement this function, your reimplementation should callemitDataChanged() 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 treatsQt::EditRole andQt::DisplayRole as referring to the same data.

See alsoQt::ItemDataRole,data(), andsetFlags().

void QStandardItem::setDragEnabled(bool dragEnabled)

Sets whether the item is drag enabled. IfdragEnabled is true, the item can be dragged by the user; otherwise, the user cannot drag the item.

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

See alsoisDragEnabled(),setDropEnabled(), andsetFlags().

void QStandardItem::setDropEnabled(bool dropEnabled)

Sets whether the item is drop enabled. IfdropEnabled is true, the item can be used as a drop target; otherwise, it cannot.

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

See alsoisDropEnabled(),setDragEnabled(), andsetFlags().

void QStandardItem::setEditable(bool editable)

Sets whether the item is editable. Ifeditable is true, the item can be edited by the user; otherwise, the user cannot edit the item.

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

See alsoisEditable() andsetFlags().

void QStandardItem::setEnabled(bool enabled)

Sets whether the item is enabled. Ifenabled is true, the item is enabled, meaning that the user can interact with the item; ifenabled is false, the user cannot interact with the item.

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

See alsoisEnabled(),Qt::ItemIsEnabled, andsetFlags().

void QStandardItem::setFlags(Qt::ItemFlags flags)

Sets the item flags for the item toflags.

The item flags determine how the user can interact with the item. This is often used to disable an item.

See alsoflags() andsetData().

void QStandardItem::setFont(constQFont & font)

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

See alsofont(),setText(), andsetForeground().

void QStandardItem::setForeground(constQBrush & brush)

Sets the brush used to display the item's foreground (e.g. text) to the givenbrush.

See alsoforeground(),setBackground(), andsetFont().

void QStandardItem::setIcon(constQIcon & icon)

Sets the item's icon to theicon specified.

See alsoicon().

void QStandardItem::setRowCount(int rows)

Sets the number of child item rows torows. If this is less thanrowCount(), the data in the unwanted rows is discarded.

See alsorowCount() andsetColumnCount().

void QStandardItem::setSelectable(bool selectable)

Sets whether the item is selectable. Ifselectable is true, the item can be selected by the user; otherwise, the user cannot select the item.

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

See alsoisSelectable() andsetFlags().

void QStandardItem::setSizeHint(constQSize & size)

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

See alsosizeHint().

void QStandardItem::setStatusTip(constQString & statusTip)

Sets the item's status tip to the string specified bystatusTip.

See alsostatusTip(),setToolTip(), andsetWhatsThis().

void QStandardItem::setText(constQString & text)

Sets the item's text to thetext specified.

See alsotext(),setFont(), andsetForeground().

void QStandardItem::setTextAlignment(Qt::Alignment alignment)

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

See alsotextAlignment().

void QStandardItem::setToolTip(constQString & toolTip)

Sets the item's tooltip to the string specified bytoolTip.

See alsotoolTip(),setStatusTip(), andsetWhatsThis().

void QStandardItem::setTristate(bool tristate)

Sets whether the item is tristate. Iftristate is true, the item is checkable with three separate states; otherwise, the item is checkable with two states. (Note that this also requires that the item is checkable; seeisCheckable().)

See alsoisTristate(),setCheckable(), andsetCheckState().

void QStandardItem::setWhatsThis(constQString & whatsThis)

Sets the item's "What's This?" help to the string specified bywhatsThis.

See alsowhatsThis(),setStatusTip(), andsetToolTip().

QSize QStandardItem::sizeHint() const

Returns the size hint set for the item, or an invalidQSize 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 alsosetSizeHint().

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

Sorts the children of the item using the givenorder, by the values in the givencolumn.

Note:This function is recursive, therefore it sorts the children of the item, its grandchildren, etc.

See alsooperator<().

QString QStandardItem::statusTip() const

Returns the item's status tip.

See alsosetStatusTip(),toolTip(), andwhatsThis().

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, then this function returns 0.

Note that this function, unliketakeRow() andtakeColumn(), does not affect the dimensions of the child table.

See alsochild(),takeRow(), andtakeColumn().

QList<QStandardItem *> QStandardItem::takeColumn(int column)

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

See alsoremoveColumn(),insertColumn(), andtakeRow().

QList<QStandardItem *> QStandardItem::takeRow(int row)

Removesrow 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 alsoremoveRow(),insertRow(), andtakeColumn().

QString QStandardItem::text() const

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

See alsosetText().

Qt::Alignment QStandardItem::textAlignment() const

Returns the text alignment for the item's text.

See alsosetTextAlignment().

QString QStandardItem::toolTip() const

Returns the item's tooltip.

See alsosetToolTip(),statusTip(), andwhatsThis().

[virtual]int QStandardItem::type() const

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

See alsoQStandardItem::Type.

QString QStandardItem::whatsThis() const

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

See alsosetWhatsThis(),toolTip(), andstatusTip().

[virtual]void QStandardItem::write(QDataStream & out) const

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

See alsoread().

[virtual]bool QStandardItem::operator<(constQStandardItem & other) const

Returns true if this item is less thanother; otherwise returns false.

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

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

[protected]QStandardItem & QStandardItem::operator=(constQStandardItem & other)

Assignsother's data and flags to this item. Note thattype() andmodel() are not copied.

This function is useful when reimplementingclone().

Related Non-Members

QDataStream &operator<<(QDataStream & out, constQStandardItem & item)

Writes theQStandardItemitem to streamout.

This operator usesQStandardItem::write().

This function was introduced in Qt 4.2.

See alsoSerializing Qt Data Types.

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

Reads aQStandardItem from streamin intoitem.

This operator usesQStandardItem::read().

This function was introduced in Qt 4.2.

See alsoSerializing Qt Data Types.