1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example itemviews/coloreditorfactory
\title Color Editor Factory Example
\ingroup examples-itemviews
\brief This example shows how to create an editor that can be used by
a QItemDelegate.
\image coloreditorfactoryimage.png
When editing data in a QListView, QTableView, or QTreeView,
editors are created and displayed by a \l{Delegate
Classes}{delegate}. QItemDelegate, which is the default delegate
used by Qt's \l{View Classes}{item views}, uses a
QItemEditorFactory to create editors for it. A unique instance
provided by QItemEditorFactory is by default installed on all
item delegates.
An item editor factory contains a collection of
QItemEditorCreatorBase instances, which are specialized factories
that produce editors for one particular QVariant data type (all
models in Qt store their data in \l{QVariant}s). An editor can be any
Qt or custom widget.
In this example, we will create an editor (implemented in the \c
ColorListEditor class) that can edit the QColor data type and be
used by \l{QItemDelegate}s. We do this by creating a new
QItemEditorCreatorBase that produces \c ColorListEditors and
register it with a new factory, which we set as the default editor
item factory (the unique factory instance). To test our editor, we
have implemented the \c Window class, which displays a
QTableWidget in which \l{QColor}s can be edited.
\section1 Window Class Implementation
In the Window class, we create the item editor creator
base for our color editor and add it to the default factory.
We also create a QTableWidget in which our editor can be
tested. It is filled with some data and displayed in a window.
We take a closer look at the constructor:
\snippet itemviews/coloreditorfactory/window.cpp 0
The QStandardItemEditorCreator is a convenience class that
inherits QItemEditorCreatorBase. Its constructor takes a template
class, of which instances are returned from
\l{QItemEditorCreatorBase::}{createWidget()}. The creator uses a
constructor that takes a QWidget as its only parameter; the
template class must provide this. This way, there is no need to
subclass QStandardItemEditorCreator.
After the new factory has been set, all standard item delegates
will use it (i.e, also delegates that were created before the new
default factory was set).
The \c createGUI() function sets up the table and fills it
with data.
\section1 ColorListEditor Definition
The ColorListEditor inherits QComboBox and lets the user
select a QColor from its popup list.
\snippet itemviews/coloreditorfactory/colorlisteditor.h 0
QItemDelegate manages the interaction between the editor and
the model, i.e., it retrieves data to edit from the model and
store data from the editor in the model. The data that is edited
by an editor is stored in the editor's user data property, and the
delegate uses Qt's \l{Qt's Property System}{property system} to
access it by name. We declare our user data property with the
Q_PROPERTY macro. The property is set to be the user type with the
USER keyword.
\section1 ColorListEditor Implementation
The constructor of \c ColorListEditor simply calls \c
populateList(), which we will look at later. We move on to the
\c color() function:
\snippet itemviews/coloreditorfactory/colorlisteditor.cpp 0
We return the data that is selected in the combobox. The data
is stored in the Qt::DecorationRole as the color is then also
displayed in the popup list (as shown in the image above).
\snippet itemviews/coloreditorfactory/colorlisteditor.cpp 1
The \c findData() function searches the items in the combobox
and returns the index of the item that has \c color in the
Qt::Decoration role.
\snippet itemviews/coloreditorfactory/colorlisteditor.cpp 2
Qt knows some predefined colors by name. We simply loop
through these to fill our editor with items.
\section1 Further Customization of Item View Editors
You can customize Qt's \l{Model/View Programming}{model view
framework} in many ways. The procedure shown in this example is
usually sufficient to provide custom editors. Further
customization is achieved by subclassing QItemEditorFactory
and QItemEditorCreatorBase. It is also possible to subclass
QItemDelegate if you don't wish to use a factory at all.
Possible suggestions are:
\list
\li If the editor widget has no user property defined, the delegate
asks the factory for the property name, which it in turn
asks the item editor creator for. In this case, you can use
the QItemEditorCreator class, which takes the property
name to use for editing as a constructor argument.
\li If the editor requires other constructors or other
initialization than provided by QItemEditorCreatorBase, you
must reimplement
QItemEditorCreatorBase::createWidget().
\li You could also subclass QItemEditorFactory if you only want
to provide editors for certain kinds of data or use another
method of creating the editors than using creator bases.
\endlist
In this example, we use a standard QVariant data type. You can
also use custom types. In the \l{Star Delegate Example}, we
show how to store a custom data type in a QVariant and paint
and edit it in a class that inherits QItemDelegate.
*/
|
