1 | /****************************************************************************
|
---|
2 | **
|
---|
3 | ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
|
---|
4 | ** All rights reserved.
|
---|
5 | ** Contact: Nokia Corporation ([email protected])
|
---|
6 | **
|
---|
7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
8 | **
|
---|
9 | ** $QT_BEGIN_LICENSE:LGPL$
|
---|
10 | ** Commercial Usage
|
---|
11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
13 | ** Software or, alternatively, in accordance with the terms contained in
|
---|
14 | ** a written agreement between you and Nokia.
|
---|
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 | ** GNU General Public License Usage
|
---|
29 | ** Alternatively, this file may be used under the terms of the GNU
|
---|
30 | ** General Public License version 3.0 as published by the Free Software
|
---|
31 | ** Foundation and appearing in the file LICENSE.GPL included in the
|
---|
32 | ** packaging of this file. Please review the following information to
|
---|
33 | ** ensure the GNU General Public License version 3.0 requirements will be
|
---|
34 | ** met: http://www.gnu.org/copyleft/gpl.html.
|
---|
35 | **
|
---|
36 | ** If you have questions regarding the use of this file, please contact
|
---|
37 | ** Nokia at [email protected].
|
---|
38 | ** $QT_END_LICENSE$
|
---|
39 | **
|
---|
40 | ****************************************************************************/
|
---|
41 |
|
---|
42 | /*!
|
---|
43 | \example designer/customwidgetplugin
|
---|
44 | \title Custom Widget Plugin Example
|
---|
45 |
|
---|
46 | The Custom Widget example shows how to create a custom widget plugin for \QD.
|
---|
47 |
|
---|
48 | \image customwidgetplugin-example.png
|
---|
49 |
|
---|
50 | In this example, the custom widget used is based on the
|
---|
51 | \l{widgets/analogclock}{Analog Clock example}, and does not provide any custom
|
---|
52 | signals or slots.
|
---|
53 |
|
---|
54 | \section1 Preparation
|
---|
55 |
|
---|
56 | To provide a custom widget that can be used with \QD, we need to supply a
|
---|
57 | self-contained implementation and provide a plugin interface. In this
|
---|
58 | example, we reuse the \l{widgets/analogclock}{Analog Clock example} for
|
---|
59 | convenience.
|
---|
60 |
|
---|
61 | Since custom widgets plugins rely on components supplied with \QD, the
|
---|
62 | project file that we use needs to contain information about \QD's
|
---|
63 | library components:
|
---|
64 |
|
---|
65 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 2
|
---|
66 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 0
|
---|
67 |
|
---|
68 | The \c TEMPLATE variable's value makes \c qmake create the custom
|
---|
69 | widget as a library. Later, we will ensure that the widget will be
|
---|
70 | recognized as a plugin by Qt by using the Q_EXPORT_PLUGIN2() macro
|
---|
71 | to export the relevant widget information.
|
---|
72 |
|
---|
73 | The \c CONFIG variable contains two values, \c designer and \c
|
---|
74 | plugin:
|
---|
75 |
|
---|
76 | \list
|
---|
77 |
|
---|
78 | \o \c designer: Since custom widgets plugins rely on components
|
---|
79 | supplied with \QD, this value ensures that our plugin links
|
---|
80 | against \QD's library (\c libQtDesigner.so).
|
---|
81 |
|
---|
82 | \o \c plugin: We also need to ensure that \c qmake considers the
|
---|
83 | custom widget a plugin library.
|
---|
84 |
|
---|
85 | \endlist
|
---|
86 |
|
---|
87 | When Qt is configured to build in both debug and release modes,
|
---|
88 | \QD will be built in release mode. When this occurs, it is
|
---|
89 | necessary to ensure that plugins are also built in release
|
---|
90 | mode. For that reason we add the \c debug_and_release value to the
|
---|
91 | \c CONFIG variable. Otherwise, if a plugin is built in a mode that
|
---|
92 | is incompatible with \QD, it won't be loaded and
|
---|
93 | installed.
|
---|
94 |
|
---|
95 | The header and source files for the widget are declared in the usual way,
|
---|
96 | and we provide an implementation of the plugin interface so that \QD can
|
---|
97 | use the custom widget:
|
---|
98 |
|
---|
99 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.pro 3
|
---|
100 |
|
---|
101 | It is also important to ensure that the plugin is installed in a
|
---|
102 | location that is searched by \QD. We do this by specifying a
|
---|
103 | target path for the project and adding it to the list of items to
|
---|
104 | install:
|
---|
105 |
|
---|
106 | \snippet doc/src/snippets/code/doc_src_examples_customwidgetplugin.qdoc 0
|
---|
107 |
|
---|
108 | The custom widget is created as a library, and will be installed
|
---|
109 | alongside the other \QD plugins when the project is installed
|
---|
110 | (using \c{make install} or an equivalent installation procedure).
|
---|
111 | Later, we will ensure that it is recognized as a plugin by \QD by
|
---|
112 | using the Q_EXPORT_PLUGIN2() macro to export the relevant widget
|
---|
113 | information.
|
---|
114 |
|
---|
115 | Note that if you want the plugins to appear in a Visual Studio
|
---|
116 | integration, the plugins must be built in release mode and their
|
---|
117 | libraries must be copied into the plugin directory in the install
|
---|
118 | path of the integration (for an example, see \c {C:/program
|
---|
119 | files/trolltech as/visual studio integration/plugins}).
|
---|
120 |
|
---|
121 | For more information about plugins, see the \l {How to
|
---|
122 | Create Qt Plugins} documentation.
|
---|
123 |
|
---|
124 | \section1 AnalogClock Class Definition and Implementation
|
---|
125 |
|
---|
126 | The \c AnalogClock class is defined and implemented in exactly the same
|
---|
127 | way as described in the \l{widgets/analogclock}{Analog Clock example}.
|
---|
128 | Since the class is self-contained, and does not require any external
|
---|
129 | configuration, it can be used without modification as a custom widget in
|
---|
130 | \QD.
|
---|
131 |
|
---|
132 | \section1 AnalogClockPlugin Class Definition
|
---|
133 |
|
---|
134 | The \c AnalogClock class is exposed to \QD through the \c
|
---|
135 | AnalogClockPlugin class. This class inherits from both QObject and
|
---|
136 | the QDesignerCustomWidgetInterface class, and implements an
|
---|
137 | interface defined by QDesignerCustomWidgetInterface:
|
---|
138 |
|
---|
139 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.h 0
|
---|
140 |
|
---|
141 | The functions provide information about the widget that \QD can use in
|
---|
142 | the \l{Getting to Know Qt Designer#WidgetBox}{widget box}.
|
---|
143 | The \c initialized private member variable is used to record whether
|
---|
144 | the plugin has been initialized by \QD.
|
---|
145 |
|
---|
146 | Note that the only part of the class definition that is specific to
|
---|
147 | this particular custom widget is the class name.
|
---|
148 |
|
---|
149 | \section1 AnalogClockPlugin Implementation
|
---|
150 |
|
---|
151 | The class constructor simply calls the QObject base class constructor
|
---|
152 | and sets the \c initialized variable to \c false.
|
---|
153 |
|
---|
154 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 0
|
---|
155 |
|
---|
156 | \QD will initialize the plugin when it is required by calling the
|
---|
157 | \c initialize() function:
|
---|
158 |
|
---|
159 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 1
|
---|
160 |
|
---|
161 | In this example, the \c initialized private variable is tested, and only
|
---|
162 | set to \c true if the plugin is not already initialized. Although, this
|
---|
163 | plugin does not require any special code to be executed when it is
|
---|
164 | initialized, we could include such code after the test for initialization.
|
---|
165 |
|
---|
166 | The \c isInitialized() function lets \QD know whether the plugin is
|
---|
167 | ready for use:
|
---|
168 |
|
---|
169 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 2
|
---|
170 |
|
---|
171 | Instances of the custom widget are supplied by the \c createWidget()
|
---|
172 | function. The implementation for the analog clock is straightforward:
|
---|
173 |
|
---|
174 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 3
|
---|
175 |
|
---|
176 | In this case, the custom widget only requires a \c parent to be specified.
|
---|
177 | If other arguments need to be supplied to the widget, they can be
|
---|
178 | introduced here.
|
---|
179 |
|
---|
180 | The following functions provide information for \QD to use to represent
|
---|
181 | the widget in the widget box.
|
---|
182 | The \c name() function returns the name of class that provides the
|
---|
183 | custom widget:
|
---|
184 |
|
---|
185 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 4
|
---|
186 |
|
---|
187 | The \c group() function is used to describe the type of widget that the
|
---|
188 | custom widget belongs to:
|
---|
189 |
|
---|
190 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 5
|
---|
191 |
|
---|
192 | The widget plugin will be placed in a section identified by its
|
---|
193 | group name in \QD's widget box. The icon used to represent the
|
---|
194 | widget in the widget box is returned by the \c icon() function:
|
---|
195 |
|
---|
196 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 6
|
---|
197 |
|
---|
198 | In this case, we return a null icon to indicate that we have no icon
|
---|
199 | that can be used to represent the widget.
|
---|
200 |
|
---|
201 | A tool tip and "What's This?" help can be supplied for the custom widget's
|
---|
202 | entry in the widget box. The \c toolTip() function should return a short
|
---|
203 | message describing the widget:
|
---|
204 |
|
---|
205 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 7
|
---|
206 |
|
---|
207 | The \c whatsThis() function can return a longer description:
|
---|
208 |
|
---|
209 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 8
|
---|
210 |
|
---|
211 | The \c isContainer() function tells \QD whether the widget is supposed to
|
---|
212 | be used as a container for other widgets. If not, \QD will not allow the
|
---|
213 | user to place widgets inside it.
|
---|
214 |
|
---|
215 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 9
|
---|
216 |
|
---|
217 | Most widgets in Qt can contain child widgets, but it only makes sense
|
---|
218 | to use dedicated container widgets for this purpose in \QD. By returning
|
---|
219 | \c false, we indicate that the custom widget cannot hold other widgets;
|
---|
220 | if we returned true, \QD would allow other widgets to be placed inside
|
---|
221 | the analog clock and a layout to be defined.
|
---|
222 |
|
---|
223 | The \c domXml() function provides a way to include default settings for
|
---|
224 | the widget in the standard XML format used by \QD. In this case, we only
|
---|
225 | specify the widget's geometry:
|
---|
226 |
|
---|
227 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 10
|
---|
228 |
|
---|
229 | If the widget provides a reasonable size hint, it is not necessary to
|
---|
230 | define it here. In addition, returning an empty string instead of a
|
---|
231 | \c{<widget>} element will tell \QD not to install the widget in the
|
---|
232 | widget box.
|
---|
233 |
|
---|
234 | To make the analog clock widget usable by applications, we implement
|
---|
235 | the \c includeFile() function to return the name of the header file
|
---|
236 | containing the custom widget class definition:
|
---|
237 |
|
---|
238 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 12
|
---|
239 |
|
---|
240 | Finally, we use the Q_EXPORT_PLUGIN2() macro to export the \c
|
---|
241 | AnalogClockPlugin class for use with \QD:
|
---|
242 |
|
---|
243 | \snippet examples/designer/customwidgetplugin/customwidgetplugin.cpp 13
|
---|
244 |
|
---|
245 | This macro ensures that \QD can access and construct the custom widget.
|
---|
246 | Without this macro, there is no way for \QD to use the widget.
|
---|
247 |
|
---|
248 | It is important to note that you can only use the Q_EXPORT_PLUGIN2()
|
---|
249 | macro once in any implementation. If you have several custom widgets in
|
---|
250 | an implementation that you wish to make available to \QD, you will need
|
---|
251 | to implement \l{QDesignerCustomWidgetCollectionInterface}.
|
---|
252 | */
|
---|