Contents

• Properties
• Public Functions
• Reimplemented Public Functions
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description
• Standard Roles and Data Types
• Subclassing
• QStyledItemDelegate vs. QItemDelegate

Detailed Description

TheQItemDelegate class provides display and editing facilities for data items from a model.

QItemDelegate can be used to provide custom display features and editor widgets for item views based onQAbstractItemView subclasses. Using a delegate for this purpose allows the display and editing mechanisms to be customized and developed independently from the model and view.

TheQItemDelegate class is one of theModel/View Classes and is part of Qt'smodel/view framework. Note thatQStyledItemDelegate has taken over the job of drawing Qt's item views. We recommend the use ofQStyledItemDelegate when creating new delegates.

When displaying items from a custom model in a standard view, it is often sufficient to simply ensure that the model returns appropriate data for each of theroles that determine the appearance of items in views. The default delegate used by Qt's standard views uses this role information to display items in most of the common forms expected by users. However, it is sometimes necessary to have even more control over the appearance of items than the default delegate can provide.

This class provides default implementations of the functions for painting item data in a view and editing data from item models. Default implementations of thepaint() andsizeHint() virtual functions, defined inQAbstractItemDelegate, are provided to ensure that the delegate implements the correct basic behavior expected by views. You can reimplement these functions in subclasses to customize the appearance of items.

When editing data in an item view,QItemDelegate provides an editor widget, which is a widget that is placed on top of the view while editing takes place. Editors are created with aQItemEditorFactory; a default static instance provided byQItemEditorFactory is installed on all item delegates. You can set a custom factory usingsetItemEditorFactory() or set a new default factory withQItemEditorFactory::setDefaultFactory(). It is the data stored in the item model with theQt::EditRole that is edited.

Only the standard editing functions for widget-based delegates are reimplemented here:

• createEditor() returns the widget used to change data from the model and can be reimplemented to customize editing behavior.
• setEditorData() provides the widget with data to manipulate.
• updateEditorGeometry() ensures that the editor is displayed correctly with respect to the item view.
• setModelData() returns updated data to the model.

ThecloseEditor() signal indicates that the user has completed editing the data, and that the editor widget can be destroyed.

Standard Roles and Data Types

The default delegate used by the standard views supplied with Qt associates each standard role (defined byQt::ItemDataRole) with certain data types. Models that return data in these types can influence the appearance of the delegate as described in the following table.

If the default delegate does not allow the level of customization that you need, either for display purposes or for editing data, it is possible to subclassQItemDelegate to implement the desired behavior.

Subclassing

When subclassingQItemDelegate to create a delegate that displays items using a custom renderer, it is important to ensure that the delegate can render items suitably for all the required states; e.g. selected, disabled, checked. The documentation for thepaint() function contains some hints to show how this can be achieved.

You can provide custom editors by using aQItemEditorFactory. TheColor Editor Factory Example shows how a custom editor can be made available to delegates with the default item editor factory. This way, there is no need to subclassQItemDelegate. An alternative is to reimplementcreateEditor(),setEditorData(),setModelData(), andupdateEditorGeometry(). This process is described in theSpin Box Delegate Example.

QStyledItemDelegate vs. QItemDelegate

Since Qt 4.4, there are two delegate classes:QItemDelegate andQStyledItemDelegate. However, the default delegate isQStyledItemDelegate. These two classes are independent alternatives to painting and providing editors for items in views. The difference between them is thatQStyledItemDelegate uses the current style to paint its items. We therefore recommend usingQStyledItemDelegate as the base class when implementing custom delegates or when working with Qt style sheets. The code required for either class should be equal unless the custom delegate needs to use the style for drawing.

Property Documentation

clipping :bool

This property holds if the delegate should clip the paint events.

This property will set the paint clip to the size of the item. The default value is on. It is useful for cases such as when images are larger than the size of the item.

This property was introduced in Qt 4.2.

Access functions:

Member Function Documentation

QItemDelegate::QItemDelegate(QObject * parent = 0)

Constructs an item delegate with the givenparent.

QItemDelegate::~QItemDelegate()

Destroys the item delegate.

[virtual]QWidget * QItemDelegate::createEditor(QWidget * parent, constQStyleOptionViewItem & option, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::createEditor().

Returns the widget used to edit the item specified byindex for editing. Theparent widget and styleoption are used to control how the editor widget appears.

See alsoQAbstractItemDelegate::createEditor().

[protected]void QItemDelegate::drawBackground(QPainter * painter, constQStyleOptionViewItem & option, constQModelIndex & index) const

Renders the item background for the givenindex, using the givenpainter and styleoption.

This function was introduced in Qt 4.2.

[virtual protected]void QItemDelegate::drawCheck(QPainter * painter, constQStyleOptionViewItem & option, constQRect & rect,Qt::CheckState state) const

Renders a check indicator within the rectangle specified byrect, using the givenpainter and styleoption, using the givenstate.

[virtual protected]void QItemDelegate::drawDecoration(QPainter * painter, constQStyleOptionViewItem & option, constQRect & rect, constQPixmap & pixmap) const

Renders the decorationpixmap within the rectangle specified byrect using the givenpainter and styleoption.

[virtual protected]void QItemDelegate::drawDisplay(QPainter * painter, constQStyleOptionViewItem & option, constQRect & rect, constQString & text) const

Renders the item viewtext within the rectangle specified byrect using the givenpainter and styleoption.

[virtual protected]void QItemDelegate::drawFocus(QPainter * painter, constQStyleOptionViewItem & option, constQRect & rect) const

Renders the region within the rectangle specified byrect, indicating that it has the focus, using the givenpainter and styleoption.

[virtual protected]bool QItemDelegate::editorEvent(QEvent * event,QAbstractItemModel * model, constQStyleOptionViewItem & option, constQModelIndex & index)

Reimplemented fromQAbstractItemDelegate::editorEvent().

[virtual protected]bool QItemDelegate::eventFilter(QObject * editor,QEvent * event)

Reimplemented fromQObject::eventFilter().

Returns true if the giveneditor is a validQWidget and the givenevent is handled; otherwise returns false. The following key press events are handled by default:

• Tab
• Backtab
• Enter
• Return
• Esc

In the case ofTab,Backtab,Enter andReturn key press events, theeditor's data is comitted to the model and the editor is closed. If theevent is aTab key press the view will open an editor on the next item in the view. Likewise, if theevent is aBacktab key press the view will open an editor on theprevious item in the view.

If the event is aEsc key press event, theeditor is closedwithout committing its data.

See alsocommitData() andcloseEditor().

QItemEditorFactory * QItemDelegate::itemEditorFactory() const

Returns the editor factory used by the item delegate. If no editor factory is set, the function will return null.

See alsosetItemEditorFactory().

[virtual]void QItemDelegate::paint(QPainter * painter, constQStyleOptionViewItem & option, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::paint().

Renders the delegate using the givenpainter and styleoption for the item specified byindex.

When reimplementing this function in a subclass, you should update the area held by the option'srect variable, using the option'sstate variable to determine the state of the item to be displayed, and adjust the way it is painted accordingly.

For example, a selected item may need to be displayed differently to unselected items, as shown in the following code:

if (option.state&QStyle::State_Selected)        painter->fillRect(option.rect, option.palette.highlight());int size=qMin(option.rect.width(), option.rect.height());int brightness= index.model()->data(index,Qt::DisplayRole).toInt();double radius= (size/2.0)- (brightness/255.0* size/2.0);if (radius==0.0)return;    painter->save();    painter->setRenderHint(QPainter::Antialiasing,true);    painter->setPen(Qt::NoPen);if (option.state&QStyle::State_Selected)        painter->setBrush(option.palette.highlightedText());else    ...

After painting, you should ensure that the painter is returned to its the state it was supplied in when this function was called. For example, it may be useful to callQPainter::save() before painting andQPainter::restore() afterwards.

See alsoQStyle::State.

[virtual]void QItemDelegate::setEditorData(QWidget * editor, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::setEditorData().

Sets the data to be displayed and edited by theeditor from the data model item specified by the modelindex.

The default implementation stores the data in theeditor widget'suser property.

See alsoQMetaProperty::isUser().

void QItemDelegate::setItemEditorFactory(QItemEditorFactory * factory)

Sets the editor factory to be used by the item delegate to be thefactory specified. If no editor factory is set, the item delegate will use the default editor factory.

See alsoitemEditorFactory().

[virtual]void QItemDelegate::setModelData(QWidget * editor,QAbstractItemModel * model, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::setModelData().

Gets data from theeditor widget and stores it in the specifiedmodel at the itemindex.

The default implementation gets the value to be stored in the data model from theeditor widget'suser property.

See alsoQMetaProperty::isUser().

[virtual]QSize QItemDelegate::sizeHint(constQStyleOptionViewItem & option, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::sizeHint().

Returns the size needed by the delegate to display the item specified byindex, taking into account the style information provided byoption.

When reimplementing this function, note that in case of text items,QItemDelegate adds a margin (i.e. 2 *QStyle::PM_FocusFrameHMargin) to the length of the text.

[virtual]void QItemDelegate::updateEditorGeometry(QWidget * editor, constQStyleOptionViewItem & option, constQModelIndex & index) const

Reimplemented fromQAbstractItemDelegate::updateEditorGeometry().

Updates theeditor for the item specified byindex according to the styleoption given.