|
1 /**************************************************************************** |
|
2 ** |
|
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies). |
|
4 ** All rights reserved. |
|
5 ** Contact: Nokia Corporation (qt-info@nokia.com) |
|
6 ** |
|
7 ** This file is part of the documentation of the Qt Toolkit. |
|
8 ** |
|
9 ** $QT_BEGIN_LICENSE:LGPL$ |
|
10 ** No Commercial Usage |
|
11 ** This file contains pre-release code and may not be distributed. |
|
12 ** You may use this file in accordance with the terms and conditions |
|
13 ** contained in the Technology Preview License Agreement accompanying |
|
14 ** this package. |
|
15 ** |
|
16 ** GNU Lesser General Public License Usage |
|
17 ** Alternatively, this file may be used under the terms of the GNU Lesser |
|
18 ** General Public License version 2.1 as published by the Free Software |
|
19 ** Foundation and appearing in the file LICENSE.LGPL included in the |
|
20 ** packaging of this file. Please review the following information to |
|
21 ** ensure the GNU Lesser General Public License version 2.1 requirements |
|
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. |
|
23 ** |
|
24 ** In addition, as a special exception, Nokia gives you certain additional |
|
25 ** rights. These rights are described in the Nokia Qt LGPL Exception |
|
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. |
|
27 ** |
|
28 ** If you have questions regarding the use of this file, please contact |
|
29 ** Nokia at qt-info@nokia.com. |
|
30 ** |
|
31 ** |
|
32 ** |
|
33 ** |
|
34 ** |
|
35 ** |
|
36 ** |
|
37 ** |
|
38 ** $QT_END_LICENSE$ |
|
39 ** |
|
40 ****************************************************************************/ |
|
41 |
|
42 /*! |
|
43 \example designer/worldtimeclockplugin |
|
44 \title World Time Clock Plugin Example |
|
45 |
|
46 The World Time Clock Plugin example shows how to create a custom |
|
47 widget plugin for \QD that uses signals and slots. |
|
48 |
|
49 \image worldtimeclockplugin-example.png |
|
50 |
|
51 In this example, we simply extend the \l |
|
52 {designer/customwidgetplugin}{Custom Widget Plugin} example and |
|
53 its custom widget (based on the \l{widgets/analogclock}{Analog |
|
54 Clock} example), by introducing the concept of signals and slots. |
|
55 |
|
56 The World Time Clock Plugin example consists of two classes: |
|
57 |
|
58 \list |
|
59 \o \c WorldTimeClock is a custom clock widget with hour and |
|
60 minute hands that is automatically updated every few seconds. |
|
61 \o \c WorldTimeClockPlugin exposes the \c WorldTimeClock class to \QD. |
|
62 \endlist |
|
63 |
|
64 First we will take a look at the \c WorldTimeClock class which |
|
65 extends the \l {designer/customwidgetplugin}{Custom Widget Plugin} |
|
66 example's \c AnalogClock class by providing a signal and a |
|
67 slot. Then we will take a quick look at the \c |
|
68 WorldTimeClockPlugin class, but this class is in most parts |
|
69 identical to the \l {designer/customwidgetplugin}{Custom Widget |
|
70 Plugin} example's implementation. |
|
71 |
|
72 Finally we take a look at the plugin's project file. The project |
|
73 file for custom widget plugins needs some additional information |
|
74 to ensure that they will work within \QD. This is also covered in |
|
75 the \l {designer/customwidgetplugin}{Custom Widget Plugin} example, |
|
76 but due to its importance (custom widget plugins rely on |
|
77 components supplied with \QD which must be specified in the |
|
78 project file that we use) we will repeat it here. |
|
79 |
|
80 \section1 WorldTimeClock Class |
|
81 |
|
82 The \c WorldTimeClock class inherits QWidget, and is a custom |
|
83 clock widget with hour and minute hands that is automatically |
|
84 updated every few seconds. What makes this example different from |
|
85 the \l {designer/customwidgetplugin}{Custom Widget Plugin} |
|
86 example, is the introduction of the signal and slot in the custom |
|
87 widget class: |
|
88 |
|
89 \snippet examples/designer/worldtimeclockplugin/worldtimeclock.h 1 |
|
90 |
|
91 Note the use of the QDESIGNER_WIDGET_EXPORT macro. This is needed |
|
92 to ensure that \QD can create instances of the widget on some |
|
93 platforms, but it is a good idea to use it on all platforms. |
|
94 |
|
95 We declare the \c setTimeZone() slot with an associated \c |
|
96 timeZoneOffset variable, and we declare an \c updated() signal |
|
97 which takes the current time as argument and is emitted whenever |
|
98 the widget is repainted. |
|
99 |
|
100 \image worldtimeclock-connection.png |
|
101 |
|
102 In \QD's workspace we can then, for example, connect the \c |
|
103 WorldTimeClock widget's \c updated() signal to a QTimeEdit's \l |
|
104 {QDateTimeEdit::setTime()}{setTime()} slot using \QD's mode |
|
105 for editing signal and slots. |
|
106 |
|
107 \image worldtimeclock-signalandslot.png |
|
108 |
|
109 We can also connect a QSpinBox's \l |
|
110 {QSpinBox::valueChanged()}{valueChanged()} signal to the \c |
|
111 WorldTimeClock's \c setTimeZone() slot. |
|
112 |
|
113 \section1 WorldTimeClockPlugin Class |
|
114 |
|
115 The \c WorldTimeClockPlugin class exposes the \c WorldTimeClock |
|
116 class to \QD. Its definition is equivalent to the \l |
|
117 {designer/customwidgetplugin}{Custom Widget Plugin} example's |
|
118 plugin class which is explained in detail. The only part of the |
|
119 class definition that is specific to this particular custom widget |
|
120 is the class name: |
|
121 |
|
122 \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.h 0 |
|
123 |
|
124 The plugin class provides \QD with basic information about our |
|
125 plugin, such as its class name and its include file. Furthermore |
|
126 it knows how to create instances of the \c WorldTimeClockPlugin |
|
127 widget. \c WorldTimeClockPlugin also defines the \l |
|
128 {QDesignerCustomWidgetInterface::initialize()}{initialize()} |
|
129 function which is called after the plugin is loaded into \QD. The |
|
130 function's QDesignerFormEditorInterface parameter provides the |
|
131 plugin with a gateway to all of \QD's API's. |
|
132 |
|
133 The \c WorldTimeClockPlugin class inherits from both QObject and |
|
134 QDesignerCustomWidgetInterface. It is important to remember, when |
|
135 using multiple inheritance, to ensure that all the interfaces |
|
136 (i.e. the classes that doesn't inherit Q_OBJECT) are made known to |
|
137 the meta object system using the Q_INTERFACES() macro. This |
|
138 enables \QD to use \l qobject_cast() to query for supported |
|
139 interfaces using nothing but a QObject pointer. |
|
140 |
|
141 The implementation of the \c WorldTimeClockPlugin is also |
|
142 equivalent to the plugin interface implementation in the \l |
|
143 {designer/customwidgetplugin}{Custom Widget Plugin} example (only |
|
144 the class name and the implementation of |
|
145 QDesignerCustomWidgetInterface::domXml() differ). The main thing |
|
146 to remember is to use the Q_EXPORT_PLUGIN2() macro to export the \c |
|
147 WorldTimeClockPlugin class for use with \QD: |
|
148 |
|
149 \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.cpp 0 |
|
150 |
|
151 Without this macro, there is no way for Qt Designer to use the |
|
152 widget. |
|
153 |
|
154 \section1 The Project File: worldtimeclockplugin.pro |
|
155 |
|
156 The project file for custom widget plugins needs some additional |
|
157 information to ensure that they will work as expected within \QD: |
|
158 |
|
159 \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 0 |
|
160 \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 1 |
|
161 |
|
162 The \c TEMPLATE variable's value make \c qmake create the custom |
|
163 widget as a library. The \c CONFIG variable contains two values, |
|
164 \c designer and \c plugin: |
|
165 |
|
166 \list |
|
167 \o \c designer: Since custom widgets plugins rely on components |
|
168 supplied with \QD, this value ensures that our plugin links against |
|
169 \QD's library (\c libQtDesigner.so). |
|
170 |
|
171 \o \c plugin: We also need to ensure that \c qmake considers the |
|
172 custom widget a \e plugin library. |
|
173 \endlist |
|
174 |
|
175 When Qt is configured to build in both debug and release modes, |
|
176 \QD will be built in release mode. When this occurs, it is |
|
177 necessary to ensure that plugins are also built in release |
|
178 mode. For that reason you might have to add a \c release value to |
|
179 your \c CONFIG variable. Otherwise, if a plugin is built in a mode |
|
180 that is incompatible with \QD, it won't be loaded and |
|
181 installed. |
|
182 |
|
183 The header and source files for the widget are declared in the |
|
184 usual way, and in addition we provide an implementation of the |
|
185 plugin interface so that \QD can use the custom widget. |
|
186 |
|
187 \snippet examples/designer/worldtimeclockplugin/worldtimeclockplugin.pro 2 |
|
188 |
|
189 It is important to ensure that the plugin is installed in a location that |
|
190 is searched by \QD. We do this by specifying a target path for the project |
|
191 and adding it to the list of items to install: |
|
192 |
|
193 \snippet doc/src/snippets/code/doc_src_examples_worldtimeclockplugin.qdoc 0 |
|
194 |
|
195 The custom widget is created as a library, and will be installed |
|
196 alongside the other \QD plugins when the project is installed |
|
197 (using \c{make install} or an equivalent installation procedure). |
|
198 Later, we will ensure that it is recognized as a plugin by \QD by |
|
199 using the Q_EXPORT_PLUGIN2() macro to export the relevant widget |
|
200 information. |
|
201 |
|
202 Note that if you want the plugins to appear in a Visual Studio |
|
203 integration, the plugins must be built in release mode and their |
|
204 libraries must be copied into the plugin directory in the install |
|
205 path of the integration (for an example, see \c {C:/program |
|
206 files/trolltech as/visual studio integration/plugins}). |
|
207 |
|
208 For more information about plugins, see the \l {How to Create Qt |
|
209 Plugins} document. |
|
210 */ |