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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
|
/****************************************************************************
**
** Copyright (C) 2013 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$
**
****************************************************************************/
/*!
\class QDesignerCustomWidgetInterface
\brief The QDesignerCustomWidgetInterface class enables Qt Designer
to access and construct custom widgets.
\inmodule QtDesigner
QDesignerCustomWidgetInterface provides a custom widget with an
interface. The class contains a set of functions that must be subclassed
to return basic information about the widget, such as its class name and
the name of its header file. Other functions must be implemented to
initialize the plugin when it is loaded, and to construct instances of
the custom widget for \QD to use.
When implementing a custom widget you must subclass
QDesignerCustomWidgetInterface to expose your widget to \QD. For
example, this is the declaration for the plugin used in the
\l{Custom Widget Plugin Example}{Custom Widget Plugin example} that
enables an analog clock custom widget to be used by \QD:
\snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0
Note that the only part of the class definition that is specific
to this particular custom widget is the class name. In addition,
since we are implementing an interface, we must ensure that it's
made known to the meta object system using the Q_INTERFACES()
macro. This enables \QD to use the qobject_cast() function to
query for supported interfaces using nothing but a QObject
pointer.
After \QD loads a custom widget plugin, it calls the interface's
initialize() function to enable it to set up any resources that it
may need. This function is called with a QDesignerFormEditorInterface
parameter that provides the plugin with a gateway to all of \QD's API.
\QD constructs instances of the custom widget by calling the plugin's
createWidget() function with a suitable parent widget. Plugins must
construct and return an instance of a custom widget with the specified
parent widget.
In the implementation of the class you must remember to export
your custom widget plugin to \QD using the Q_EXPORT_PLUGIN2()
macro. For example, if a library called \c libcustomwidgetplugin.so
(on Unix) or \c libcustomwidget.dll (on Windows) contains a widget
class called \c MyCustomWidget, we can export it by adding the
following line to the file containing the plugin implementation:
\snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 14
This macro ensures that \QD can access and construct the custom widget.
Without this macro, there is no way for \QD to use it.
When implementing a custom widget plugin, you build it as a
separate library. If you want to include several custom widget
plugins in the same library, you must in addition subclass
QDesignerCustomWidgetCollectionInterface.
\warning If your custom widget plugin contains QVariant
properties, be aware that only the following \l
{QVariant::Type}{types} are supported:
\list
\o QVariant::ByteArray
\o QVariant::Bool
\o QVariant::Color
\o QVariant::Cursor
\o QVariant::Date
\o QVariant::DateTime
\o QVariant::Double
\o QVariant::Int
\o QVariant::Point
\o QVariant::Rect
\o QVariant::Size
\o QVariant::SizePolicy
\o QVariant::String
\o QVariant::Time
\o QVariant::UInt
\endlist
For a complete example using the QDesignerCustomWidgetInterface
class, see the \l {designer/customwidgetplugin}{Custom Widget
Example}. The example shows how to create a custom widget plugin
for \QD.
\sa QDesignerCustomWidgetCollectionInterface {Creating Custom
Widgets for Qt Designer}
*/
/*!
\fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()
Destroys the custom widget interface.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::name() const
Returns the class name of the custom widget supplied by the interface.
The name returned \e must be identical to the class name used for the
custom widget.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::group() const
Returns the name of the group to which the custom widget belongs.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::toolTip() const
Returns a short description of the widget that can be used by \QD
in a tool tip.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::whatsThis() const
Returns a description of the widget that can be used by \QD in
"What's This?" help for the widget.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::includeFile() const
Returns the path to the include file that \l uic uses when
creating code for the custom widget.
*/
/*!
\fn QIcon QDesignerCustomWidgetInterface::icon() const
Returns the icon used to represent the custom widget in \QD's
widget box.
*/
/*!
\fn bool QDesignerCustomWidgetInterface::isContainer() const
Returns true if the custom widget is intended to be used as a
container; otherwise returns false.
Most custom widgets are not used to hold other widgets, so their
implementations of this function will return false, but custom
containers will return true to ensure that they behave correctly
in \QD.
*/
/*!
\fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)
Returns a new instance of the custom widget, with the given \a
parent.
*/
/*!
\fn bool QDesignerCustomWidgetInterface::isInitialized() const
Returns true if the widget has been initialized; otherwise returns
false.
\sa initialize()
*/
/*!
\fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)
Initializes the widget for use with the specified \a formEditor
interface.
\sa isInitialized()
*/
/*!
\fn QString QDesignerCustomWidgetInterface::domXml() const
Returns the XML that is used to describe the custom widget's
properties to \QD.
*/
/*!
\fn QString QDesignerCustomWidgetInterface::codeTemplate() const
This function is reserved for future use by \QD.
\omit
Returns the code template that \QD includes in forms that contain
the custom widget when they are saved.
\endomit
*/
/*!
\macro QDESIGNER_WIDGET_EXPORT
\relates QDesignerCustomWidgetInterface
\since 4.1
This macro is used when defining custom widgets to ensure that they are
correctly exported from plugins for use with \QD.
On some platforms, the symbols required by \QD to create new widgets
are removed from plugins by the build system, making them unusable.
Using this macro ensures that the symbols are retained on those platforms,
and has no side effects on other platforms.
For example, the \l{designer/worldtimeclockplugin}{World Time Clock Plugin}
example exports a custom widget class with the following declaration:
\snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 0
\dots
\snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 2
\sa {Creating Custom Widgets for Qt Designer}
*/
/*!
\class QDesignerCustomWidgetCollectionInterface
\brief The QDesignerCustomWidgetCollectionInterface class allows
you to include several custom widgets in one single library.
\inmodule QtDesigner
When implementing a custom widget plugin, you build it as a
separate library. If you want to include several custom widget
plugins in the same library, you must in addition subclass
QDesignerCustomWidgetCollectionInterface.
QDesignerCustomWidgetCollectionInterface contains one single
function returning a list of the collection's
QDesignerCustomWidgetInterface objects. For example, if you have
several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and
\c CustomWidgetThree, the class definition may look like this:
\snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 12
In the class constructor you add the interfaces to your custom
widgets to the list which you return in the customWidgets()
function:
\snippet doc/src/snippets/code/doc_src_qtdesigner.cpp 13
Note that instead of exporting each custom widget plugin using the
Q_EXPORT_PLUGIN2() macro, you export the entire collection. The
Q_EXPORT_PLUGIN2() macro ensures that \QD can access and construct
the custom widgets. Without this macro, there is no way for \QD to
use them.
\sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for
Qt Designer}
*/
/*!
\fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() {
Destroys the custom widget collection interface.
*/
/*!
\fn QList<QDesignerCustomWidgetInterface*> QDesignerCustomWidgetCollectionInterface::customWidgets() const
Returns a list of interfaces to the collection's custom widgets.
*/
|
