~oif-team/ubuntu/natty/qt4-x11/xi2.1

<td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="annotated.html"><font color="#004faf">Annotated</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>

[Previous: <a href="model-view-selection.html">Handling Selections in Item Views</a>]

[<a href="model-view-programming.html">Contents</a>]

[Next: <a href="model-view-convenience.html">Item View Convenience Classes</a>]

</p>

<h1 align="center">Delegate Classes</h1>

<ul><li><a href="#concepts">Concepts</a></li>

<li><a href="#using-an-existing-delegate">Using an Existing Delegate</a></li>

<li><a href="#a-simple-delegate">A Simple Delegate</a></li>

<ul><li><a href="#providing-an-editor">Providing an Editor</a></li>

<li><a href="#submitting-data-to-the-model">Submitting Data to the Model</a></li>

<li><a href="#updating-the-editor-s-geometry">Updating the Editor's Geometry</a></li>

<li><a href="#editing-hints">Editing Hints</a></li>

</ul>

<h2>Concepts</h2>

<p>Unlike the Model-View-Controller pattern, the model/view design does not include a completely separate component for managing interaction with the user. Generally, the view is responsible for the presentation of model data to the user, and for processing user input. To allow some flexibility in the way this input is obtained, the interaction is performed by delegates. These components provide input capabilities and are also responsible for rendering individual items in some views. The standard interface for controlling delegates is defined in the <a href="qabstractitemdelegate.html">QAbstractItemDelegate</a> class.</p>

<p>Delegates are expected to be able to render their contents themselves by implementing the <a href="qabstractitemdelegate.html#paint">paint()</a> and <a href="qabstractitemdelegate.html#sizeHint">sizeHint()</a> functions. However, simple widget-based delegates can subclass <a href="qitemdelegate.html">QItemDelegate</a> instead of <a href="qabstractitemdelegate.html">QAbstractItemDelegate</a>, and take advantage of the default implementations of those functions. Editors for delegates can be implemented in two ways, either by using widgets to manage the editing process, or by handling events directly. The first approach is covered later in this section.</p>

<h2>Using an Existing Delegate</h2>

<p>The standard views provided with Qt use instances of <a href="qitemdelegate.html">QItemDelegate</a> to provide editing facilities. This default implementation of the delegate interface renders items in the usual style for each of the standard views: <a href="qlistview.html">QListView</a>, <a href="qtableview.html">QTableView</a>, and <a href="qtreeview.html">QTreeView</a>. The delegate being used for a view is returned by the <a href="qabstractitemview.html#itemDelegate">itemDelegate()</a> function. The <a href="qabstractitemview.html#setItemDelegate">setItemDelegate()</a> function allows you to install a custom delegate for a standard view, and it is necessary to use this function when setting the delegate for a custom view.</p>

<h2>A Simple Delegate</h2>

<p>The delegate implemented here uses a <a href="qspinbox.html">QSpinBox</a> to provide editing facilities, and is mainly intended for use with models that display integers. Although we set up a custom integer-based table model for this purpose, we could easily have used <a href="qstandarditemmodel.html">QStandardItemModel</a> instead since the custom delegate will control data entry. We construct a table view to display the contents of the model, and this will use the custom delegate for editing.</p>

<center><img src="images/spinboxdelegate-example.png" /></center><p>We subclass the delegate from <a href="qitemdelegate.html">QItemDelegate</a> because we do not want to write custom display functions. However, we must still provide functions to manage the editor widget:</p>

<pre>  class SpinBoxDelegate : public QItemDelegate

{

Q_OBJECT

public:

SpinBoxDelegate(QObject *parent = 0);

QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option,

const QModelIndex &index) const;

void setEditorData(QWidget *editor, const QModelIndex &index) const;

void setModelData(QWidget *editor, QAbstractItemModel *model,

const QModelIndex &index) const;

void updateEditorGeometry(QWidget *editor,

const QStyleOptionViewItem &option, const QModelIndex &index) const;

};</pre>

<p>Note that no editor widgets are set up when the delegate is constructed. We only construct an editor widget when it is needed.</p>

<h3>Providing an Editor</h3>

<p>In this example, when the table view needs to provide an editor, it asks the delegate to provide an editor widget that is appropriate for the item being modified. The <a href="qabstractitemdelegate.html#createEditor">createEditor()</a> function is supplied with everything that the delegate needs to be able to set up a suitable widget:</p>

<pre>  QWidget *SpinBoxDelegate::createEditor(QWidget *parent,

const QStyleOptionViewItem &/* option */,

const QModelIndex &/* index */) const

{

QSpinBox *editor = new QSpinBox(parent);

editor->setMinimum(0);

editor->setMaximum(100);

editor->installEventFilter(const_cast<SpinBoxDelegate*>(this));

return editor;

}</pre>

<p>Note that we do not need to keep a pointer to the editor widget because the view takes responsibility for destroying it when it is no longer needed.</p>

<p>We install the delegate's default event filter on the editor to ensure that it provides the standard editing shortcuts that users expect. Additional shortcuts can be added to the editor to allow more sophisticated behavior; these are discussed in the section on <a href="#editinghints">Editing Hints</a>.</p>

<p>The view ensures that the editor's data and geometry are set correctly by calling functions that we define later for these purposes. We can create different editors depending on the model index supplied by the view. For example, if we have a column of integers and a column of strings we could return either a <tt>QSpinBox</tt> or a <tt>QLineEdit</tt>, depending on which column is being edited.</p>

<p>The delegate must provide a function to copy model data into the editor. In this example, we read the data stored in the <a href="qt.html#ItemDataRole-enum">display role</a>, and set the value in the spin box accordingly.</p>

<pre>  void SpinBoxDelegate::setEditorData(QWidget *editor,

const QModelIndex &index) const

{

int value = index.model()->data(index, Qt::DisplayRole).toInt();

QSpinBox *spinBox = static_cast<QSpinBox*>(editor);

spinBox->setValue(value);

}</pre>

<p>In this example, we know that the editor widget is a spin box, but we could have provided different editors for different types of data in the model, in which case we would need to cast the widget to the appropriate type before accessing its member functions.</p>

<h3>Submitting Data to the Model</h3>

<p>When the user has finished editing the value in the spin box, the view asks the delegate to store the edited value in the model by calling the <a href="qabstractitemdelegate.html#setModelData">setModelData()</a> function.</p>

<pre>  void SpinBoxDelegate::setModelData(QWidget *editor, QAbstractItemModel *model,

const QModelIndex &index) const

{

100

QSpinBox *spinBox = static_cast<QSpinBox*>(editor);

101

spinBox->interpretText();

102

int value = spinBox->value();

103

104

model->setData(index, value);

105

}</pre>

106

<p>Since the view manages the editor widgets for the delegate, we only need to update the model with the contents of the editor supplied. In this case, we ensure that the spin box is up-to-date, and update the model with the value it contains using the index specified.</p>

107

<p>The standard <a href="qitemdelegate.html">QItemDelegate</a> class informs the view when it has finished editing by emitting the <a href="qabstractitemdelegate.html#closeEditor">closeEditor()</a> signal. The view ensures that the editor widget is closed and destroyed. In this example, we only provide simple editing facilities, so we need never emit this signal.</p>

108

<p>All the operations on data are performed through the interface provided by <a href="qabstractitemmodel.html">QAbstractItemModel</a>. This makes the delegate mostly independent from the type of data it manipulates, but some assumptions must be made in order to use certain types of editor widgets. In this example, we have assumed that the model always contains integer values, but we can still use this delegate with different kinds of models because <a href="qvariant.html">QVariant</a> provides sensible default values for unexpected data.</p>

109

110

<h3>Updating the Editor's Geometry</h3>

111

<p>It is the responsibility of the delegate to manage the editor's geometry. The geometry must be set when the editor is created, and when the item's size or position in the view is changed. Fortunately, the view provides all the necessary geometry information inside a <a href="qstyleoptionviewitem.html">view option</a> object.</p>

112

<pre>  void SpinBoxDelegate::updateEditorGeometry(QWidget *editor,

113

const QStyleOptionViewItem &option, const QModelIndex &/* index */) const

114

{

115

editor->setGeometry(option.rect);

116

}</pre>

117

<p>In this case, we just use the geometry information provided by the view option in the item rectangle. A delegate that renders items with several elements would not use the item rectangle directly. It would position the editor in relation to the other elements in the item.</p>

118

119

<h3>Editing Hints</h3>

120

<p>After editing, delegates should provide hints to the other components about the result of the editing process, and provide hints that will assist any subsequent editing operations. This is achieved by emitting the <a href="qabstractitemdelegate.html#closeEditor">closeEditor()</a> signal with a suitable hint. This is taken care of by the default <a href="qitemdelegate.html">QItemDelegate</a> event filter which we installed on the spin box when it was constructed.</p>

121

<p>The behavior of the spin box could be adjusted to make it more user friendly. In the default event filter supplied by <a href="qitemdelegate.html">QItemDelegate</a>, if the user hits <b>Return</b> to confirm their choice in the spin box, the delegate commits the value to the model and closes the spin box. We can change this behavior by installing our own event filter on the spin box, and provide editing hints that suit our needs; for example, we might emit <a href="qabstractitemdelegate.html#closeEditor">closeEditor()</a> with the <a href="qabstractitemdelegate.html#EndEditHint-enum">EditNextItem</a> hint to automatically start editing the next item in the view.</p>

122

<p>Another approach that does not require the use of an event filter is to provide our own editor widget, perhaps subclassing <a href="qspinbox.html">QSpinBox</a> for convenience. This alternative approach would give us more control over how the editor widget behaves at the cost of writing additional code. It is usually easier to install an event filter in the delegate if you need to customize the behavior of a standard Qt editor widget.</p>

123

<p>Delegates do not have to emit these hints, but those that do not will be less integrated into applications, and will be less usable than those that emit hints to support common editing actions.</p>

124

<p>

125

[Previous: <a href="model-view-selection.html">Handling Selections in Item Views</a>]

126

[<a href="model-view-programming.html">Contents</a>]

127

[Next: <a href="model-view-convenience.html">Item View Convenience Classes</a>]

128

</p>

129

130

131

132

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

133

134

</tr></table></div></address></body>

135

</html>

Older »