Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
customwidget.qdoc
Go to the documentation of this file.
1
// Copyright (C) 2016 The Qt Company Ltd.
2
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4
/*!
5
\class QDesignerCustomWidgetInterface
6
7
\brief The QDesignerCustomWidgetInterface class enables \QD
8
to access and construct custom widgets.
9
10
\inmodule QtDesigner
11
12
QDesignerCustomWidgetInterface provides a custom widget with an
13
interface. The class contains a set of functions that must be subclassed
14
to return basic information about the widget, such as its class name and
15
the name of its header file. Other functions must be implemented to
16
initialize the plugin when it is loaded, and to construct instances of
17
the custom widget for \QD to use.
18
19
When implementing a custom widget you must subclass
20
QDesignerCustomWidgetInterface to expose your widget to \QD. For
21
example, this is the declaration for the plugin used in the
22
\l{Custom Widget Plugin} example that
23
enables an analog clock custom widget to be used by \QD:
24
25
\snippet customwidgetplugin/customwidgetplugin.h 0
26
27
Note that the only part of the class definition that is specific
28
to this particular custom widget is the class name. In addition,
29
since we are implementing an interface, we must ensure that it's
30
made known to the meta object system using the Q_INTERFACES()
31
macro. This enables \QD to use the qobject_cast() function to
32
query for supported interfaces using nothing but a QObject
33
pointer.
34
35
After \QD loads a custom widget plugin, it calls the interface's
36
initialize() function to enable it to set up any resources that it
37
may need. This function is called with a QDesignerFormEditorInterface
38
parameter that provides the plugin with a gateway to all of \QD's API.
39
40
\QD constructs instances of the custom widget by calling the plugin's
41
createWidget() function with a suitable parent widget. Plugins must
42
construct and return an instance of a custom widget with the specified
43
parent widget.
44
45
Exporting your custom widget plugin to \QD using the Q_PLUGIN_METADATA()
46
macro. For example, if a library called \c libcustomwidgetplugin.so
47
(on Unix) or \c libcustomwidget.dll (on Windows) contains a widget
48
class called \c MyCustomWidget, we can export it by adding the
49
following line to the file containing the plugin header:
50
51
\snippet plugins/doc_src_qtdesigner.cpp 14
52
53
This macro ensures that \QD can access and construct the custom widget.
54
Without this macro, there is no way for \QD to use it.
55
56
When implementing a custom widget plugin, you build it as a
57
separate library. If you want to include several custom widget
58
plugins in the same library, you must in addition subclass
59
QDesignerCustomWidgetCollectionInterface.
60
61
\warning If your custom widget plugin contains QVariant
62
properties, be aware that only the following \l
63
{QVariant::Type}{types} are supported:
64
65
\list
66
\li QVariant::ByteArray
67
\li QVariant::Bool
68
\li QVariant::Color
69
\li QVariant::Cursor
70
\li QVariant::Date
71
\li QVariant::DateTime
72
\li QVariant::Double
73
\li QVariant::Int
74
\li QVariant::Point
75
\li QVariant::Rect
76
\li QVariant::Size
77
\li QVariant::SizePolicy
78
\li QVariant::String
79
\li QVariant::Time
80
\li QVariant::UInt
81
\endlist
82
83
For a complete example using the QDesignerCustomWidgetInterface
84
class, see the \l {customwidgetplugin}{Custom Widget
85
Example}. The example shows how to create a custom widget plugin
86
for \QD.
87
88
\sa QDesignerCustomWidgetCollectionInterface, {Creating Custom Widgets for Qt Widgets Designer}
89
*/
90
91
/*!
92
\fn QDesignerCustomWidgetInterface::~QDesignerCustomWidgetInterface()
93
94
Destroys the custom widget interface.
95
*/
96
97
/*!
98
\fn QString QDesignerCustomWidgetInterface::name() const
99
100
Returns the class name of the custom widget supplied by the interface.
101
102
The name returned \e must be identical to the class name used for the
103
custom widget.
104
*/
105
106
/*!
107
\fn QString QDesignerCustomWidgetInterface::group() const
108
109
Returns the name of the group to which the custom widget belongs.
110
*/
111
112
/*!
113
\fn QString QDesignerCustomWidgetInterface::toolTip() const
114
115
Returns a short description of the widget that can be used by \QD
116
in a tool tip.
117
*/
118
119
/*!
120
\fn QString QDesignerCustomWidgetInterface::whatsThis() const
121
122
Returns a description of the widget that can be used by \QD in
123
"What's This?" help for the widget.
124
*/
125
126
/*!
127
\fn QString QDesignerCustomWidgetInterface::includeFile() const
128
129
Returns the path to the include file that \l uic uses when
130
creating code for the custom widget.
131
*/
132
133
/*!
134
\fn QIcon QDesignerCustomWidgetInterface::icon() const
135
136
Returns the icon used to represent the custom widget in \QD's
137
widget box.
138
*/
139
140
/*!
141
\fn bool QDesignerCustomWidgetInterface::isContainer() const
142
143
Returns true if the custom widget is intended to be used as a
144
container; otherwise returns false.
145
146
Most custom widgets are not used to hold other widgets, so their
147
implementations of this function will return false, but custom
148
containers will return true to ensure that they behave correctly
149
in \QD.
150
*/
151
152
/*!
153
\fn QWidget *QDesignerCustomWidgetInterface::createWidget(QWidget *parent)
154
155
Returns a new instance of the custom widget, with the given \a
156
parent.
157
*/
158
159
/*!
160
\fn bool QDesignerCustomWidgetInterface::isInitialized() const
161
162
Returns true if the widget has been initialized; otherwise returns
163
false.
164
165
\sa initialize()
166
*/
167
168
/*!
169
\fn void QDesignerCustomWidgetInterface::initialize(QDesignerFormEditorInterface *formEditor)
170
171
Initializes the widget for use with the specified \a formEditor
172
interface.
173
174
\sa isInitialized()
175
*/
176
177
/*!
178
\fn QString QDesignerCustomWidgetInterface::domXml() const
179
180
Returns the XML that is used to describe the custom widget's
181
properties to \QD.
182
*/
183
184
/*!
185
\fn QString QDesignerCustomWidgetInterface::codeTemplate() const
186
187
This function is reserved for future use by \QD.
188
189
\omit
190
Returns the code template that \QD includes in forms that contain
191
the custom widget when they are saved.
192
\endomit
193
*/
194
195
/*!
196
\macro QDESIGNER_WIDGET_EXPORT
197
\relates QDesignerCustomWidgetInterface
198
\since 4.1
199
200
This macro is used when defining custom widgets to ensure that they are
201
correctly exported from plugins for use with \QD.
202
203
On some platforms, the symbols required by \QD to create new widgets
204
are removed from plugins by the build system, making them unusable.
205
Using this macro ensures that the symbols are retained on those platforms,
206
and has no side effects on other platforms.
207
208
For example, the \l{customwidgetplugin}{Custom Widget Plugin}
209
example exports a custom widget class with the following declaration:
210
211
\snippet customwidgetplugin/analogclock.h 0
212
\dots
213
\snippet customwidgetplugin/analogclock.h 1
214
215
\sa {Creating Custom Widgets for Qt Widgets Designer}
216
*/
217
218
219
220
221
222
/*!
223
\class QDesignerCustomWidgetCollectionInterface
224
225
\brief The QDesignerCustomWidgetCollectionInterface class allows
226
you to include several custom widgets in one single library.
227
228
\inmodule QtDesigner
229
230
When implementing a custom widget plugin, you build it as a
231
separate library. If you want to include several custom widget
232
plugins in the same library, you must in addition subclass
233
QDesignerCustomWidgetCollectionInterface.
234
235
QDesignerCustomWidgetCollectionInterface contains one single
236
function returning a list of the collection's
237
QDesignerCustomWidgetInterface objects. For example, if you have
238
several custom widgets \c CustomWidgetOne, \c CustomWidgetTwo and
239
\c CustomWidgetThree, the class definition may look like this:
240
241
\snippet plugins/doc_src_qtdesigner.cpp 12
242
243
In the class constructor you add the interfaces to your custom
244
widgets to the list which you return in the customWidgets()
245
function:
246
247
\snippet plugins/doc_src_qtdesigner.cpp 13
248
249
Note that instead of exporting each custom widget plugin using the
250
Q_PLUGIN_METADATA() macro, you export the entire collection. The
251
Q_PLUGIN_METADATA() macro ensures that \QD can access and construct
252
the custom widgets. Without this macro, there is no way for \QD to
253
use them.
254
255
\sa QDesignerCustomWidgetInterface, {Creating Custom Widgets for
256
Qt Widgets Designer}
257
*/
258
259
/*!
260
\fn QDesignerCustomWidgetCollectionInterface::~QDesignerCustomWidgetCollectionInterface() {
261
262
Destroys the custom widget collection interface.
263
*/
264
265
/*!
266
\fn QList<QDesignerCustomWidgetInterface*> QDesignerCustomWidgetCollectionInterface::customWidgets() const
267
268
Returns a list of interfaces to the collection's custom widgets.
269
*/
qttools
src
uiplugin
customwidget.qdoc
Generated on Sat Sep 21 2024 01:06:19 for Qt by
1.12.0