source: trunk/doc/src/examples/customwidgetplugin.qdoc@ 651

Last change on this file since 651 was 651, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.2 sources.

File size: 10.8 KB
Line 
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*/
Note: See TracBrowser for help on using the repository browser.