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
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in a
** written agreement between you and Nokia.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example designer/worldtimeclockplugin
\title World Time Clock Plugin Example
The World Time Clock Plugin example shows how to create a custom
widget plugin for \QD that uses signals and slots.
\image worldtimeclockplugin-example.png
In this example, we simply extend the \l
{designer/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
\o \c WorldTimeClock is a custom clock widget with hour and
minute hands that is automatically updated every few seconds.
\o \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 {designer/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 {designer/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 {designer/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 {designer/customwidgetplugin}{Custom Widget Plugin}
example, is the introduction of the signal and slot in the custom
widget class:
\snippet examples/designer/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
{designer/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:
\snippet examples/designer/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 \l 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
{designer/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_EXPORT_PLUGIN2() macro to export the \c
WorldTimeClockPlugin class for use with \QD:
\snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0
Without this macro, there is no way for Qt Designer to use the
widget.
\section1 The Project File: worldtimeclockplugin.pro
The project file for custom widget plugins needs some additional
information to ensure that they will work as expected within \QD:
\snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0
\snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 1
The \c TEMPLATE variable's value make \c qmake create the custom
widget as a library. The \c CONFIG variable contains two values,
\c designer and \c plugin:
\list
\o \c designer: Since custom widgets plugins rely on components
supplied with \QD, this value ensures that our plugin links against
\QD's library (\c libQtDesigner.so).
\o \c plugin: We also need to ensure that \c qmake considers the
custom widget a \e plugin library.
\endlist
When Qt is configured to build in both debug and release modes,
\QD will be built in release mode. When this occurs, it is
necessary to ensure that plugins are also built in release
mode. For that reason you might have to add a \c release value to
your \c CONFIG variable. Otherwise, if a plugin is built in a mode
that is incompatible with \QD, it won't be loaded and
installed.
The header and source files for the widget are declared in the
usual way, and in addition we provide an implementation of the
plugin interface so that \QD can use the custom widget.
\snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 2
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 doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc 0
The custom widget is created as a library, and will be installed
alongside the other \QD plugins when the project is installed
(using \c{make install} or an equivalent installation procedure).
Later, we will ensure that it is recognized as a plugin by \QD by
using the Q_EXPORT_PLUGIN2() macro to export the relevant widget
information.
Note that if you want the plugins to appear in a Visual Studio
integration, the plugins must be built in release mode and their
libraries must be copied into the plugin directory in the install
path of the integration (for an example, see \c {C:/program
files/trolltech as/visual studio integration/plugins}).
For more information about plugins, see the \l {How to Create Qt
Plugins} document.
*/
|
