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
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\example worldtimeclockplugin
\ingroup examples-designer
\title World Time Clock Plugin Example
\brief Creating a custom widget plugin for \QD that uses signals and slots.
\image worldtimeclockplugin-example.png
In this example, we simply extend the \l
{customwidgetplugin}{Custom Widget Plugin} example and
its custom widget (based on the \l{widgets/analogclock}{Analog
Clock} example), by introducing the concept of signals and slots.
The World Time Clock Plugin example consists of two classes:
\list
\li \c WorldTimeClock is a custom clock widget with hour and
minute hands that is automatically updated every few seconds.
\li \c WorldTimeClockPlugin exposes the \c WorldTimeClock class to \QD.
\endlist
First we will take a look at the \c WorldTimeClock class which
extends the \l {customwidgetplugin}{Custom Widget Plugin}
example's \c AnalogClock class by providing a signal and a
slot. Then we will take a quick look at the \c
WorldTimeClockPlugin class, but this class is in most parts
identical to the \l {customwidgetplugin}{Custom Widget
Plugin} example's implementation.
Finally we take a look at the plugin's project file. The project
file for custom widget plugins needs some additional information
to ensure that they will work within \QD. This is also covered in
the \l {customwidgetplugin}{Custom Widget Plugin} example,
but due to its importance (custom widget plugins rely on
components supplied with \QD which must be specified in the
project file that we use) we will repeat it here.
\section1 WorldTimeClock Class
The \c WorldTimeClock class inherits QWidget, and is a custom
clock widget with hour and minute hands that is automatically
updated every few seconds. What makes this example different from
the \l {customwidgetplugin}{Custom Widget Plugin}
example, is the introduction of the signal and slot in the custom
widget class:
\snippet worldtimeclockplugin/worldtimeclock.h 1
Note the use of the QDESIGNER_WIDGET_EXPORT macro. This is needed
to ensure that \QD can create instances of the widget on some
platforms, but it is a good idea to use it on all platforms.
We declare the \c setTimeZone() slot with an associated \c
timeZoneOffset variable, and we declare an \c updated() signal
which takes the current time as argument and is emitted whenever
the widget is repainted.
\image worldtimeclock-connection.png
In \QD's workspace we can then, for example, connect the \c
WorldTimeClock widget's \c updated() signal to a QTimeEdit's \l
{QDateTimeEdit::setTime()}{setTime()} slot using \QD's mode
for editing signal and slots.
\image worldtimeclock-signalandslot.png
We can also connect a QSpinBox's \l
{QSpinBox::valueChanged()}{valueChanged()} signal to the \c
WorldTimeClock's \c setTimeZone() slot.
\section1 WorldTimeClockPlugin Class
The \c WorldTimeClockPlugin class exposes the \c WorldTimeClock
class to \QD. Its definition is equivalent to the \l
{customwidgetplugin}{Custom Widget Plugin} example's
plugin class which is explained in detail. The only part of the
class definition that is specific to this particular custom widget
is the class name.
To ensure that Qt recognizes the widget as a plugin, export relevant
information about the widget by adding the \c Q_PLUGIN_METADATA() macro:
\snippet worldtimeclockplugin/worldtimeclockplugin.h 0
The plugin class provides \QD with basic information about our
plugin, such as its class name and its include file. Furthermore
it knows how to create instances of the \c WorldTimeClockPlugin
widget. \c WorldTimeClockPlugin also defines the \l
{QDesignerCustomWidgetInterface::initialize()}{initialize()}
function which is called after the plugin is loaded into \QD. The
function's QDesignerFormEditorInterface parameter provides the
plugin with a gateway to all of \QD's API's.
The \c WorldTimeClockPlugin class inherits from both QObject and
QDesignerCustomWidgetInterface. It is important to remember, when
using multiple inheritance, to ensure that all the interfaces
(i.e. the classes that doesn't inherit Q_OBJECT) are made known to
the meta object system using the Q_INTERFACES() macro. This
enables \QD to use qobject_cast() to query for supported
interfaces using nothing but a QObject pointer.
The implementation of the \c WorldTimeClockPlugin is also
equivalent to the plugin interface implementation in the \l
{customwidgetplugin}{Custom Widget Plugin} example (only
the class name and the implementation of
QDesignerCustomWidgetInterface::domXml() differ). The main thing
to remember is to use the Q_PLUGIN_METADATA() macro to export the \c
WorldTimeClockPlugin class for use with \QD:
\snippet worldtimeclockplugin/worldtimeclockplugin.h 1
Without this macro, there is no way for Qt Designer to use the
widget.
\section1 Project files
\section2 CMake
The project files need to state that a plugin linking
to the \QD libraries is to be built:
\snippet worldtimeclockplugin/CMakeLists.txt 0
\codeline
\snippet worldtimeclockplugin/CMakeLists.txt 2
The link libraries list specifies \c Qt::UiPlugin. This indicates that
the plugin uses the abstract interfaces QDesignerCustomWidgetInterface
and QDesignerCustomWidgetCollectionInterface only and has no linkage
to the \QD libraries. When accessing other interfaces of \QD that have
linkage, \c Designer should be used instead; this ensures that the plugin
dynamically links to the \QD libraries and has a run-time dependency on
them.
The header and source files for the widget are declared in the
usual way:
\snippet worldtimeclockplugin/CMakeLists.txt 1
We provide an implementation of the plugin interface so that \QD
can use the custom widget. In this particular example we also
provide implementations of the container extension interface and
the extension factory.
It is important to ensure that the plugin is installed in a
location that is searched by \QD. We do this by specifying a
target path for the project and adding it to the list of items to
install:
\snippet worldtimeclockplugin/CMakeLists.txt 3
\snippet worldtimeclockplugin/CMakeLists.txt 4
The custom widget is created as a library. It will be
installed alongside the other \QD plugins when the project is
installed (using \c{ninja install} or an equivalent installation
procedure).
For more information about plugins, see the
\l {How to Create Qt Plugins} documentation.
\section2 qmake
The following example shows how to link a plugin to the \QD libraries:
\snippet worldtimeclockplugin/worldtimeclockplugin.pro 0
\codeline
\snippet worldtimeclockplugin/worldtimeclockplugin.pro 1
The \c QT variable contains the keyword \c uiplugin, which is
the equivalent of the \c Qt::UiPlugin library.
The following example shows how to add the header and source files of the
widget:
\snippet worldtimeclockplugin/worldtimeclockplugin.pro 2
The following example shows how to install a plugin to the \QD's plugin path:
\snippet worldtimeclockplugin/worldtimeclockplugin.pro 3
*/
|
