QStandardItem Class Reference
^{[QtGui module]}

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, and Model/View Programming.

Member Type Documentation

enum QStandardItem::ItemType

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

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

Member Function Documentation

QStandardItem::QStandardItem ()

Constructs an item.

QStandardItem::QStandardItem ( const QString & text )

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 )

Constructs an item with rows rows and columns columns of child items.

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

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

This function is useful when reimplementing clone().

QStandardItem::~QStandardItem ()   [virtual]

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 also setAccessibleDescription() and accessibleText().

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 also setAccessibleText() and accessibleDescription().

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

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 )

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 )

This is an overloaded member function, provided for convenience.

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 )

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

See also insertRow().

QBrush QStandardItem::background () const

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

See also foreground() and setBackground().

Qt::CheckState QStandardItem::checkState () const

Returns the checked state of the item.

See also setCheckState() and isCheckable().

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 also setChild(), takeChild(), and 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() and 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() and parent().

int QStandardItem::columnCount () const

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

See also setColumnCount() and 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.

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

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

See also setFont().

QBrush QStandardItem::foreground () const

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

See also setForeground() and background().

bool QStandardItem::hasChildren () const

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

See also rowCount(), columnCount(), and child().

QIcon QStandardItem::icon () const

Returns the item's icon.

See also setIcon() and 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() and 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() and insertRow().

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

Inserts count columns of child items at column column.

See also insertColumn() and 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() and insertColumn().

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

This is an overloaded member function, provided for convenience.

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

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

This is an overloaded member function, provided for convenience.

Inserts count rows of child items at row row.

See also insertRow() and insertColumns().

bool QStandardItem::isCheckable () const

Returns whether the item is user-checkable.

The default value is false.

See also setCheckable(), checkState(), and isTristate().

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

See also setDragEnabled(), isDropEnabled(), and flags().

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 also setDropEnabled(), isDragEnabled(), and flags().

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

The default value is true.

See also setEditable() and flags().

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 as isEditable() and isSelectable().

The default value is true.

See also setEnabled() and flags().

bool QStandardItem::isSelectable () const

Returns whether the item is selectable by the user.

The default value is true.

See also setSelectable() and flags().

bool QStandardItem::isTristate () const

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

The default value is false.

See also setTristate(), isCheckable(), and checkState().

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

See also index().

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(), and 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() and removeRows().

void QStandardItem::removeRow ( int row )

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

See also takeRow(), removeRows(), and 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() and 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() and parent().

int QStandardItem::rowCount () const

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

See also setRowCount() and columnCount().

void QStandardItem::setAccessibleDescription ( const QString & accessibleDescription )

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 cannot use conventional means of interaction).

See also accessibleDescription() and setAccessibleText().

void QStandardItem::setAccessibleText ( const QString & accessibleText )

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 cannot use conventional means of interaction).

See also accessibleText() and setAccessibleDescription().

void QStandardItem::setBackground ( const QBrush & brush )

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

See also background() and setForeground().

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

Sets the check state of the item to be state.

See also checkState() and setCheckable().

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 cannot 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(), and setTristate().

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 )

This is an overloaded member function, provided for convenience.

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

See also Qt::ItemDataRole, data(), and setFlags().

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 cannot 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(), and 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 cannot.

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(), and 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 cannot 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() and 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 cannot interact with the item.

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

See also isEnabled(), Qt::ItemIsEnabled, and 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() and setData().

void QStandardItem::setFont ( const QFont & font )

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

See also font(), setText(), and setForeground().

void QStandardItem::setForeground ( const QBrush & brush )

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

See also foreground(), setBackground(), and setFont().

void QStandardItem::setIcon ( const QIcon & icon )

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() and 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 cannot 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() and setFlags().

void QStandardItem::setSizeHint ( const QSize & size )

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 )

Sets the item's status tip to the string specified by statusTip.

See also statusTip(), setToolTip(), and setWhatsThis().

void QStandardItem::setText ( const QString & text )

Sets the item's text to the text specified.

See also text(), setFont(), and setForeground().

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

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

See also textAlignment().

void QStandardItem::setToolTip ( const QString & toolTip )

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

See also toolTip(), setStatusTip(), and setWhatsThis().

void QStandardItem::setTristate ( bool tristate )

Sets whether the item is tristate. If tristate 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; see isCheckable().)

See also isTristate(), setCheckable(), and setCheckState().

void QStandardItem::setWhatsThis ( const QString & whatsThis )

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

See also whatsThis(), setStatusTip(), and setToolTip().

QSize QStandardItem::sizeHint () const

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.

See also operator<().

QString QStandardItem::statusTip () const

Returns the item's status tip.

See also setStatusTip(), toolTip(), and 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, then this function returns 0.

Note that this function, unlike takeRow() and takeColumn(), does not affect the dimensions of the child table.

See also child(), takeRow(), and 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 0.

See also removeColumn(), insertColumn(), and 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(), and takeColumn().

QString QStandardItem::text () const

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

Returns the text alignment for the item's text.

See also setTextAlignment().

QString QStandardItem::toolTip () const

Returns the item's tooltip.

See also setToolTip(), statusTip(), and 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

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

See also setWhatsThis(), toolTip(), and 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().

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

Related Non-Members

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

This is an overloaded member function, provided for convenience.

Writes the QStandardItem item to stream out.

This operator uses QStandardItem::write().

This function was introduced in Qt 4.2.

See also Format of the QDataStream Operators.

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

This is an overloaded member function, provided for convenience.

Reads a QStandardItem from stream in into item.

This operator uses QStandardItem::read().

This function was introduced in Qt 4.2.

See also Format of the QDataStream Operators.