|
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 \group plugins |
|
44 \title Plugin Classes |
|
45 \ingroup groups |
|
46 |
|
47 \brief Plugin related classes. |
|
48 |
|
49 These classes deal with shared libraries, (e.g. .so and DLL files), |
|
50 and with Qt plugins. |
|
51 |
|
52 See the \link plugins-howto.html plugins documentation\endlink. |
|
53 |
|
54 See also the \l{ActiveQt framework} for Windows. |
|
55 */ |
|
56 |
|
57 /*! |
|
58 \page plugins-howto.html |
|
59 \title How to Create Qt Plugins |
|
60 \brief A guide to creating plugins to extend Qt applications and |
|
61 functionality provided by Qt. |
|
62 |
|
63 \ingroup frameworks-technologies |
|
64 |
|
65 \keyword QT_DEBUG_PLUGINS |
|
66 \keyword QT_NO_PLUGIN_CHECK |
|
67 |
|
68 Qt provides two APIs for creating plugins: |
|
69 |
|
70 \list |
|
71 \o A higher-level API for writing extensions to Qt itself: custom database |
|
72 drivers, image formats, text codecs, custom styles, etc. |
|
73 \o A lower-level API for extending Qt applications. |
|
74 \endlist |
|
75 |
|
76 For example, if you want to write a custom QStyle subclass and |
|
77 have Qt applications load it dynamically, you would use the |
|
78 higher-level API. |
|
79 |
|
80 Since the higher-level API is built on top of the lower-level API, |
|
81 some issues are common to both. |
|
82 |
|
83 If you want to provide plugins for use with \QD, see the QtDesigner |
|
84 module documentation. |
|
85 |
|
86 Topics: |
|
87 |
|
88 \tableofcontents |
|
89 |
|
90 \section1 The Higher-Level API: Writing Qt Extensions |
|
91 |
|
92 Writing a plugin that extends Qt itself is achieved by |
|
93 subclassing the appropriate plugin base class, implementing a few |
|
94 functions, and adding a macro. |
|
95 |
|
96 There are several plugin base classes. Derived plugins are stored |
|
97 by default in sub-directories of the standard plugin directory. Qt |
|
98 will not find plugins if they are not stored in the right |
|
99 directory. |
|
100 |
|
101 \table |
|
102 \header \o Base Class \o Directory Name \o Key Case Sensitivity |
|
103 \row \o QAccessibleBridgePlugin \o \c accessiblebridge \o Case Sensitive |
|
104 \row \o QAccessiblePlugin \o \c accessible \o Case Sensitive |
|
105 \row \o QDecorationPlugin \o \c decorations \o Case Insensitive |
|
106 \row \o QFontEnginePlugin \o \c fontengines \o Case Insensitive |
|
107 \row \o QIconEnginePlugin \o \c iconengines \o Case Insensitive |
|
108 \row \o QImageIOPlugin \o \c imageformats \o Case Sensitive |
|
109 \row \o QInputContextPlugin \o \c inputmethods \o Case Sensitive |
|
110 \row \o QKbdDriverPlugin \o \c kbddrivers \o Case Insensitive |
|
111 \row \o QMouseDriverPlugin \o \c mousedrivers \o Case Insensitive |
|
112 \row \o QScreenDriverPlugin \o \c gfxdrivers \o Case Insensitive |
|
113 \row \o QScriptExtensionPlugin \o \c script \o Case Sensitive |
|
114 \row \o QSqlDriverPlugin \o \c sqldrivers \o Case Sensitive |
|
115 \row \o QStylePlugin \o \c styles \o Case Insensitive |
|
116 \row \o QTextCodecPlugin \o \c codecs \o Case Sensitive |
|
117 \endtable |
|
118 |
|
119 Suppose that you have a new style class called \c MyStyle that you |
|
120 want to make available as a plugin. The required code is |
|
121 straightforward, here is the class definition (\c |
|
122 mystyleplugin.h): |
|
123 |
|
124 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 0 |
|
125 |
|
126 Ensure that the class implementation is located in a \c .cpp file |
|
127 (including the class definition): |
|
128 |
|
129 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 1 |
|
130 |
|
131 (Note that QStylePlugin is case insensitive, and the lower-case |
|
132 version of the key is used in our |
|
133 \l{QStylePlugin::create()}{create()} implementation; most other |
|
134 plugins are case sensitive.) |
|
135 |
|
136 For database drivers, image formats, text codecs, and most other |
|
137 plugin types, no explicit object creation is required. Qt will |
|
138 find and create them as required. Styles are an exception, since |
|
139 you might want to set a style explicitly in code. To apply a |
|
140 style, use code like this: |
|
141 |
|
142 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 2 |
|
143 |
|
144 Some plugin classes require additional functions to be |
|
145 implemented. See the class documentation for details of the |
|
146 virtual functions that must be reimplemented for each type of |
|
147 plugin. |
|
148 |
|
149 The \l{Style Plugin Example} shows how to implement a plugin |
|
150 that extends the QStylePlugin base class. |
|
151 |
|
152 \section1 The Lower-Level API: Extending Qt Applications |
|
153 |
|
154 Not only Qt itself but also Qt application can be extended |
|
155 through plugins. This requires the application to detect and load |
|
156 plugins using QPluginLoader. In that context, plugins may provide |
|
157 arbitrary functionality and are not limited to database drivers, |
|
158 image formats, text codecs, styles, and the other types of plugin |
|
159 that extend Qt's functionality. |
|
160 |
|
161 Making an application extensible through plugins involves the |
|
162 following steps: |
|
163 |
|
164 \list 1 |
|
165 \o Define a set of interfaces (classes with only pure virtual |
|
166 functions) used to talk to the plugins. |
|
167 \o Use the Q_DECLARE_INTERFACE() macro to tell Qt's |
|
168 \l{meta-object system} about the interface. |
|
169 \o Use QPluginLoader in the application to load the plugins. |
|
170 \o Use qobject_cast() to test whether a plugin implements a given |
|
171 interface. |
|
172 \endlist |
|
173 |
|
174 Writing a plugin involves these steps: |
|
175 |
|
176 \list 1 |
|
177 \o Declare a plugin class that inherits from QObject and from the |
|
178 interfaces that the plugin wants to provide. |
|
179 \o Use the Q_INTERFACES() macro to tell Qt's \l{meta-object |
|
180 system} about the interfaces. |
|
181 \o Export the plugin using the Q_EXPORT_PLUGIN2() macro. |
|
182 \o Build the plugin using a suitable \c .pro file. |
|
183 \endlist |
|
184 |
|
185 For example, here's the definition of an interface class: |
|
186 |
|
187 \snippet examples/tools/plugandpaint/interfaces.h 2 |
|
188 |
|
189 Here's the definition of a plugin class that implements that |
|
190 interface: |
|
191 |
|
192 \snippet examples/tools/plugandpaintplugins/extrafilters/extrafiltersplugin.h 0 |
|
193 |
|
194 The \l{tools/plugandpaint}{Plug & Paint} example documentation |
|
195 explains this process in detail. See also \l{Creating Custom |
|
196 Widgets for Qt Designer} for information about issues that are |
|
197 specific to \QD. You can also take a look at the \l{Echo Plugin |
|
198 Example} is a more trivial example on how to implement a plugin |
|
199 that extends Qt applications. Please note that a QCoreApplication |
|
200 must have been initialized before plugins can be loaded. |
|
201 |
|
202 \section1 Locating Plugins |
|
203 |
|
204 Qt applications automatically know which plugins are available, |
|
205 because plugins are stored in the standard plugin subdirectories. |
|
206 Because of this applications don't require any code to find and load |
|
207 plugins, since Qt handles them automatically. |
|
208 |
|
209 During development, the directory for plugins is \c{QTDIR/plugins} |
|
210 (where \c QTDIR is the directory where Qt is installed), with each |
|
211 type of plugin in a subdirectory for that type, e.g. \c styles. If |
|
212 you want your applications to use plugins and you don't want to use |
|
213 the standard plugins path, have your installation process |
|
214 determine the path you want to use for the plugins, and save the |
|
215 path, e.g. using QSettings, for the application to read when it |
|
216 runs. The application can then call |
|
217 QCoreApplication::addLibraryPath() with this path and your |
|
218 plugins will be available to the application. Note that the final |
|
219 part of the path (e.g., \c styles) cannot be changed. |
|
220 |
|
221 If you want the plugin to be loadable then one approach is to |
|
222 create a subdirectory under the application and place the plugin |
|
223 in that directory. If you distribute any of the plugins that come |
|
224 with Qt (the ones located in the \c plugins directory), you must |
|
225 copy the sub-directory under \c plugins where the plugin is |
|
226 located to your applications root folder (i.e., do not include the |
|
227 \c plugins directory). |
|
228 |
|
229 \note In Symbian all binaries must be located in the directory \\sys\\bin, |
|
230 so each Qt plugin has a stub with the same basename as the plugin dll |
|
231 and suffix ".qtplugin" to make Qt extension plugins work similarly to |
|
232 other platforms. |
|
233 When trying to locate the plugin, Qt actually looks for the stub |
|
234 instead of the plugin binary. While plugin stub files have the |
|
235 suffix ".qtplugin", they can still be loaded also by specifying a filename |
|
236 with the normal library suffix ".dll" for QPluginLoader, so normally application |
|
237 developer doesn't need to care about the different suffix of the stub. |
|
238 Because of the way applications can be installed |
|
239 on ROM or various other drives in Symbian, Qt looks for the stub from |
|
240 the same directory on all available drives if it is not located in the given |
|
241 directory when loading a plugin. |
|
242 |
|
243 For more information about deployment, |
|
244 see the \l {Deploying Qt Applications} and \l {Deploying Plugins} |
|
245 documentation. |
|
246 |
|
247 \section1 Static Plugins |
|
248 |
|
249 The normal and most flexible way to include a plugin with an |
|
250 application is to compile it into a dynamic library that is shipped |
|
251 separately, and detected and loaded at runtime. |
|
252 |
|
253 Plugins can be linked statically against your application. If you |
|
254 build the static version of Qt, this is the only option for |
|
255 including Qt's predefined plugins. Using static plugins makes the |
|
256 deployment less error-prone, but has the disadvantage that no |
|
257 functionality from plugins can be added without a complete rebuild |
|
258 and redistribution of the application. |
|
259 |
|
260 When compiled as a static library, Qt provides the following |
|
261 static plugins: |
|
262 |
|
263 \table |
|
264 \header \o Plugin name \o Type \o Description |
|
265 \row \o \c qtaccessiblecompatwidgets \o Accessibility \o Accessibility for Qt 3 support widgets |
|
266 \row \o \c qtaccessiblewidgets \o Accessibility \o Accessibility for Qt widgets |
|
267 \row \o \c qdecorationdefault \o Decorations (Qt Extended) \o Default style |
|
268 \row \o \c qdecorationwindows \o Decorations (Qt Extended) \o Windows style |
|
269 \row \o \c qgif \o Image formats \o GIF |
|
270 \row \o \c qjpeg \o Image formats \o JPEG |
|
271 \row \o \c qmng \o Image formats \o MNG |
|
272 \row \o \c qico \o Image formats \o ICO |
|
273 \row \o \c qsvg \o Image formats \o SVG |
|
274 \row \o \c qtiff \o Image formats \o TIFF |
|
275 \row \o \c qimsw_multi \o Input methods (Qt Extended) \o Input Method Switcher |
|
276 \row \o \c qwstslibmousehandler \o Mouse drivers (Qt Extended) \o \c tslib mouse |
|
277 \row \o \c qgfxtransformed \o Graphic drivers (Qt Extended) \o Transformed screen |
|
278 \row \o \c qgfxvnc \o Graphic drivers (Qt Extended) \o VNC |
|
279 \row \o \c qscreenvfb \o Graphic drivers (Qt Extended) \o Virtual frame buffer |
|
280 \row \o \c qsqldb2 \o SQL driver \o IBM DB2 \row \o \c qsqlibase \o SQL driver \o Borland InterBase |
|
281 \row \o \c qsqlite \o SQL driver \o SQLite version 3 |
|
282 \row \o \c qsqlite2 \o SQL driver \o SQLite version 2 |
|
283 \row \o \c qsqlmysql \o SQL driver \o MySQL |
|
284 \row \o \c qsqloci \o SQL driver \o Oracle (OCI) |
|
285 \row \o \c qsqlodbc \o SQL driver \o Open Database Connectivity (ODBC) |
|
286 \row \o \c qsqlpsql \o SQL driver \o PostgreSQL |
|
287 \row \o \c qsqltds \o SQL driver \o Sybase Adaptive Server (TDS) |
|
288 \row \o \c qcncodecs \o Text codecs \o Simplified Chinese (People's Republic of China) |
|
289 \row \o \c qjpcodecs \o Text codecs \o Japanese |
|
290 \row \o \c qkrcodecs \o Text codecs \o Korean |
|
291 \row \o \c qtwcodecs \o Text codecs \o Traditional Chinese (Taiwan) |
|
292 \endtable |
|
293 |
|
294 To link statically against those plugins, you need to use the |
|
295 Q_IMPORT_PLUGIN() macro in your application and you need to add |
|
296 the required plugins to your build using \c QTPLUGIN. |
|
297 For example, in your \c main.cpp: |
|
298 |
|
299 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 4 |
|
300 |
|
301 In the \c .pro file for your application, you need the following |
|
302 entry: |
|
303 |
|
304 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 5 |
|
305 |
|
306 It is also possible to create your own static plugins, by |
|
307 following these steps: |
|
308 |
|
309 \list 1 |
|
310 \o Add \c{CONFIG += static} to your plugin's \c .pro file. |
|
311 \o Use the Q_IMPORT_PLUGIN() macro in your application. |
|
312 \o Link your application with your plugin library using \c LIBS |
|
313 in the \c .pro file. |
|
314 \endlist |
|
315 |
|
316 See the \l{tools/plugandpaint}{Plug & Paint} example and the |
|
317 associated \l{tools/plugandpaintplugins/basictools}{Basic Tools} |
|
318 plugin for details on how to do this. |
|
319 |
|
320 \note If you are not using qmake to build your application you need |
|
321 to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is |
|
322 defined. |
|
323 |
|
324 \sa QPluginLoader, QLibrary, {Plug & Paint Example} |
|
325 */ |