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