source: trunk/doc/src/examples/stardelegate.qdoc

Last change on this file was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 11.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:FDL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in a
14** written agreement between you and Nokia.
15**
16** GNU Free Documentation License
17** Alternatively, this file may be used under the terms of the GNU Free
18** Documentation License version 1.3 as published by the Free Software
19** Foundation and appearing in the file included in the packaging of this
20** file.
21**
22** If you have questions regarding the use of this file, please contact
23** Nokia at [email protected].
24** $QT_END_LICENSE$
25**
26****************************************************************************/
27
28/*!
29 \example itemviews/stardelegate
30 \title Star Delegate Example
31
32 The Star Delegate example shows how to create a delegate that
33 can paint itself and that supports editing.
34
35 \image stardelegate.png The Star Delegate Example
36
37 When displaying data in a QListView, QTableView, or QTreeView,
38 the individual items are drawn by a
39 \l{Delegate Classes}{delegate}. Also, when the user starts
40 editing an item (e.g., by double-clicking the item), the delegate
41 provides an editor widget that is placed on top of the item while
42 editing takes place.
43
44 Delegates are subclasses of QAbstractItemDelegate. Qt provides
45 QItemDelegate, which inherits QAbstractItemDelegate and handles
46 the most common data types (notably \c int and QString). If we
47 need to support custom data types, or want to customize the
48 rendering or the editing for existing data types, we can subclass
49 QAbstractItemDelegate or QItemDelegate. See \l{Delegate Classes}
50 for more information about delegates, and \l{Model/View
51 Programming} if you need a high-level introduction to Qt's
52 model/view architecture (including delegates).
53
54 In this example, we will see how to implement a custom delegate
55 to render and edit a "star rating" data type, which can store
56 values such as "1 out of 5 stars".
57
58 The example consists of the following classes:
59
60 \list
61 \o \c StarRating is the custom data type. It stores a rating
62 expressed as stars, such as "2 out of 5 stars" or "5 out of
63 6 stars".
64
65 \o \c StarDelegate inherits QItemDelegate and provides support
66 for \c StarRating (in addition to the data types already
67 handled by QItemDelegate).
68
69 \o \c StarEditor inherits QWidget and is used by \c StarDelegate
70 to let the user edit a star rating using the mouse.
71 \endlist
72
73 To show the \c StarDelegate in action, we will fill a
74 QTableWidget with some data and install the delegate on it.
75
76 \section1 StarDelegate Class Definition
77
78 Here's the definition of the \c StarDelegate class:
79
80 \snippet examples/itemviews/stardelegate/stardelegate.h 0
81
82 All public functions are reimplemented virtual functions from
83 QItemDelegate to provide custom rendering and editing.
84
85 \section1 StarDelegate Class Implementation
86
87 The \l{QAbstractItemDelegate::}{paint()} function is
88 reimplemented from QItemDelegate and is called whenever the view
89 needs to repaint an item:
90
91 \snippet examples/itemviews/stardelegate/stardelegate.cpp 0
92
93 The function is invoked once for each item, represented by a
94 QModelIndex object from the model. If the data stored in the item
95 is a \c StarRating, we paint it ourselves; otherwise, we let
96 QItemDelegate paint it for us. This ensures that the \c
97 StarDelegate can handle the most common data types.
98
99 In the case where the item is a \c StarRating, we draw the
100 background if the item is selected, and we draw the item using \c
101 StarRating::paint(), which we will review later.
102
103 \c{StartRating}s can be stored in a QVariant thanks to the
104 Q_DECLARE_METATYPE() macro appearing in \c starrating.h. More on
105 this later.
106
107 The \l{QAbstractItemDelegate::}{createEditor()} function is
108 called when the user starts editing an item:
109
110 \snippet examples/itemviews/stardelegate/stardelegate.cpp 2
111
112 If the item is a \c StarRating, we create a \c StarEditor and
113 connect its \c editingFinished() signal to our \c
114 commitAndCloseEditor() slot, so we can update the model when the
115 editor closes.
116
117 Here's the implementation of \c commitAndCloseEditor():
118
119 \snippet examples/itemviews/stardelegate/stardelegate.cpp 5
120
121 When the user is done editing, we emit
122 \l{QAbstractItemDelegate::}{commitData()} and
123 \l{QAbstractItemDelegate::}{closeEditor()} (both declared in
124 QAbstractItemDelegate), to tell the model that there is edited
125 data and to inform the view that the editor is no longer needed.
126
127 The \l{QAbstractItemDelegate::}{setEditorData()} function is
128 called when an editor is created to initialize it with data
129 from the model:
130
131 \snippet examples/itemviews/stardelegate/stardelegate.cpp 3
132
133 We simply call \c setStarRating() on the editor.
134
135 The \l{QAbstractItemDelegate::}{setModelData()} function is
136 called when editing is finished, to commit data from the editor
137 to the model:
138
139 \snippet examples/itemviews/stardelegate/stardelegate.cpp 4
140
141 The \c sizeHint() function returns an item's preferred size:
142
143 \snippet examples/itemviews/stardelegate/stardelegate.cpp 1
144
145 We simply forward the call to \c StarRating.