1 /****************************************************************************
3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the documentation of the Qt Toolkit.
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
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.
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.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
43 \page plugins-howto.html
44 \title How to Create Qt Plugins
45 \brief A guide to creating plugins to extend Qt applications and functionality provided by Qt.
48 \keyword QT_DEBUG_PLUGINS
49 \keyword QT_NO_PLUGIN_CHECK
51 Qt provides two APIs for creating plugins:
54 \o A higher-level API for writing extensions to Qt itself: custom database
55 drivers, image formats, text codecs, custom styles, etc.
56 \o A lower-level API for extending Qt applications.
59 For example, if you want to write a custom QStyle subclass and
60 have Qt applications load it dynamically, you would use the
63 Since the higher-level API is built on top of the lower-level API,
64 some issues are common to both.
66 If you want to provide plugins for use with \QD, see the QtDesigner
73 \section1 The Higher-Level API: Writing Qt Extensions
75 Writing a plugin that extends Qt itself is achieved by
76 subclassing the appropriate plugin base class, implementing a few
77 functions, and adding a macro.
79 There are several plugin base classes. Derived plugins are stored
80 by default in sub-directories of the standard plugin directory. Qt
81 will not find plugins if they are not stored in the right
85 \header \o Base Class \o Directory Name \o Key Case Sensitivity
86 \row \o QAccessibleBridgePlugin \o \c accessiblebridge \o Case Sensitive
87 \row \o QAccessiblePlugin \o \c accessible \o Case Sensitive
88 \row \o QDecorationPlugin \o \c decorations \o Case Insensitive
89 \row \o QFontEnginePlugin \o \c fontengines \o Case Insensitive
90 \row \o QIconEnginePlugin \o \c iconengines \o Case Insensitive
91 \row \o QImageIOPlugin \o \c imageformats \o Case Sensitive
92 \row \o QInputContextPlugin \o \c inputmethods \o Case Sensitive
93 \row \o QKbdDriverPlugin \o \c kbddrivers \o Case Insensitive
94 \row \o QMouseDriverPlugin \o \c mousedrivers \o Case Insensitive
95 \row \o QPictureFormatPlugin \o \c pictureformats \o Case Sensitive
96 \row \o QScreenDriverPlugin \o \c gfxdrivers \o Case Insensitive
97 \row \o QScriptExtensionPlugin \o \c script \o Case Sensitive
98 \row \o QSqlDriverPlugin \o \c sqldrivers \o Case Sensitive
99 \row \o QStylePlugin \o \c styles \o Case Insensitive
100 \row \o QTextCodecPlugin \o \c codecs \o Case Sensitive
103 But where is the \c{plugins} directory? When the application
104 is run, Qt will first treat the application's executable directory
105 as the \c{pluginsbase}. For example if the application is in
106 \c{C:\Program Files\MyApp} and has a style plugin, Qt will look in
107 \c{C:\Program Files\MyApp\styles}. (See
108 QCoreApplication::applicationDirPath() for how to find out where
109 the application's executable is.) Qt will also look in the
110 directory specified by
111 QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically
112 is located in \c QTDIR/plugins (where \c QTDIR is the directory
113 where Qt is installed). If you want Qt to look in additional
114 places you can add as many paths as you need with calls to
115 QCoreApplication::addLibraryPath(). And if you want to set your
116 own path or paths you can use QCoreApplication::setLibraryPaths().
117 You can also use a \c qt.conf file to override the hard-coded
118 paths that are compiled into the Qt library. For more information,
119 see the \l {Using qt.conf} documentation. Yet another possibility
120 is to set the \c QT_PLUGIN_PATH environment variable before running
121 the application. If set, Qt will look for plugins in the
122 paths (separated by the system path separator) specified in the variable.
124 Suppose that you have a new style class called \c MyStyle that you
125 want to make available as a plugin. The required code is
126 straightforward, here is the class definition (\c
129 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 0
131 Ensure that the class implementation is located in a \c .cpp file
132 (including the class definition):
134 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 1
136 (Note that QStylePlugin is case insensitive, and the lower-case
137 version of the key is used in our
138 \l{QStylePlugin::create()}{create()} implementation; most other
139 plugins are case sensitive.)
141 For database drivers, image formats, text codecs, and most other
142 plugin types, no explicit object creation is required. Qt will
143 find and create them as required. Styles are an exception, since
144 you might want to set a style explicitly in code. To apply a
145 style, use code like this:
147 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 2
149 Some plugin classes require additional functions to be
150 implemented. See the class documentation for details of the
151 virtual functions that must be reimplemented for each type of
154 Qt applications automatically know which plugins are available,
155 because plugins are stored in the standard plugin subdirectories.
156 Because of this applications don't require any code to find and load
157 plugins, since Qt handles them automatically.
159 The default directory for plugins is \c{QTDIR/plugins} (where \c
160 QTDIR is the directory where Qt is installed), with each type of
161 plugin in a subdirectory for that type, e.g. \c styles. If you
162 want your applications to use plugins and you don't want to use
163 the standard plugins path, have your installation process
164 determine the path you want to use for the plugins, and save the
165 path, e.g. using QSettings, for the application to read when it
166 runs. The application can then call
167 QCoreApplication::addLibraryPath() with this path and your
168 plugins will be available to the application. Note that the final
169 part of the path (e.g., \c styles) cannot be changed.
171 The normal way to include a plugin with an application is either
172 to \l{Static Plugins}{compile it in with the application} or to
173 compile it into a dynamic library and use it like any other
176 If you want the plugin to be loadable then one approach is to
177 create a subdirectory under the application and place the plugin
178 in that directory. If you distribute any of the plugins that come
179 with Qt (the ones located in the \c plugins directory), you must
180 copy the sub-directory under \c plugins where the plugin is
181 located to your applications root folder (i.e., do not include the
182 \c plugins directory).
184 For more information about deployment,
185 see the \l {Deploying Qt Applications} documentation.
187 The \l{Style Plugin Example} shows how to implement a plugin
188 that extends the QStylePlugin base class.
190 \section1 The Lower-Level API: Extending Qt Applications
192 Not only Qt itself but also Qt application can be extended
193 through plugins. This requires the application to detect and load
194 plugins using QPluginLoader. In that context, plugins may provide
195 arbitrary functionality and are not limited to database drivers,
196 image formats, text codecs, styles, and the other types of plugin
197 that extend Qt's functionality.
199 Making an application extensible through plugins involves the
203 \o Define a set of interfaces (classes with only pure virtual
204 functions) used to talk to the plugins.
205 \o Use the Q_DECLARE_INTERFACE() macro to tell Qt's
206 \l{meta-object system} about the interface.
207 \o Use QPluginLoader in the application to load the plugins.
208 \o Use qobject_cast() to test whether a plugin implements a given
212 Writing a plugin involves these steps:
215 \o Declare a plugin class that inherits from QObject and from the
216 interfaces that the plugin wants to provide.
217 \o Use the Q_INTERFACES() macro to tell Qt's \l{meta-object
218 system} about the interfaces.
219 \o Export the plugin using the Q_EXPORT_PLUGIN2() macro.
220 \o Build the plugin using a suitable \c .pro file.
223 For example, here's the definition of an interface class:
225 \snippet examples/tools/plugandpaint/interfaces.h 2
227 Here's the definition of a plugin class that implements that
230 \snippet examples/tools/plugandpaintplugins/extrafilters/extrafiltersplugin.h 0
232 The \l{tools/plugandpaint}{Plug & Paint} example documentation
233 explains this process in detail. See also \l{Creating Custom
234 Widgets for Qt Designer} for information about issues that are
235 specific to \QD. You can also take a look at the \l{Echo Plugin
236 Example} is a more trivial example on how to implement a plugin
237 that extends Qt applications. Please note that a QCoreApplication
238 must have been initialized before plugins can be loaded.
240 \section1 Loading and Verifying Plugins Dynamically
242 When loading plugins, the Qt library does some sanity checking to
243 determine whether or not the plugin can be loaded and used. This
244 provides the ability to have multiple versions and configurations of
245 the Qt library installed side by side.
248 \o Plugins linked with a Qt library that has a higher version number
249 will not be loaded by a library with a lower version number.
252 \bold{Example:} Qt 4.3.0 will \e{not} load a plugin built with Qt 4.3.1.
254 \o Plugins linked with a Qt library that has a lower major version
255 number will not be loaded by a library with a higher major version
259 \bold{Example:} Qt 4.3.1 will \e{not} load a plugin built with Qt 3.3.1.
261 \bold{Example:} Qt 4.3.1 will load plugins built with Qt 4.3.0 and Qt 4.2.3.
263 \o The Qt library and all plugins are built using a \e {build
264 key}. The build key in the Qt library is examined against the build
265 key in the plugin, and if they match, the plugin is loaded. If the
266 build keys do not match, then the Qt library refuses to load the
269 \br \bold{Rationale:} See the \l{#The Build Key}{The Build Key} section below.
272 When building plugins to extend an application, it is important to ensure
273 that the plugin is configured in the same way as the application. This means
274 that if the application was built in release mode, plugins should be built
275 in release mode, too.
277 If you configure Qt to be built in both debug and release modes,
278 but only build applications in release mode, you need to ensure that your
279 plugins are also built in release mode. By default, if a debug build of Qt is
280 available, plugins will \e only be built in debug mode. To force the
281 plugins to be built in release mode, add the following line to the plugin's
284 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 3
286 This will ensure that the plugin is compatible with the version of the library
287 used in the application.
289 \section2 The Build Key
291 When loading plugins, Qt checks the build key of each plugin against its
292 own configuration to ensure that only compatible plugins are loaded; any
293 plugins that are configured differently are not loaded.
295 The build key contains the following information:
297 \o Architecture, operating system and compiler.
300 In cases where different versions of the same compiler do not
301 produce binary compatible code, the version of the compiler is
302 also present in the build key.
304 \o Configuration of the Qt library. The configuration is a list
305 of the missing features that affect the available API in the
309 Two different configurations of the same version of
310 the Qt library are not binary compatible. The Qt library that
311 loads the plugin uses the list of (missing) features to
312 determine if the plugin is binary compatible.
314 \e {Note:} There are cases where a plugin can use features that are
315 available in two different configurations. However, the
316 developer writing plugins would need to know which features are
317 in use, both in their plugin and internally by the utility
318 classes in Qt. The Qt library would require complex feature
319 and dependency queries and verification when loading plugins.
320 Requiring this would place an unnecessary burden on the developer, and
321 increase the overhead of loading a plugin. To reduce both
322 development time and application runtime costs, a simple string
323 comparision of the build keys is used.
325 \o Optionally, an extra string may be specified on the configure
329 When distributing binaries of the Qt library with an
330 application, this provides a way for developers to write
331 plugins that can only be loaded by the library with which the
335 For debugging purposes, it is possible to override the run-time build key
336 checks by configuring Qt with the \c QT_NO_PLUGIN_CHECK preprocessor macro
339 \section1 Static Plugins
341 Plugins can be linked statically against your application. If you
342 build the static version of Qt, this is the only option for
343 including Qt's predefined plugins.
345 When compiled as a static library, Qt provides the following
349 \header \o Plugin name \o Type \o Description
350 \row \o \c qtaccessiblecompatwidgets \o Accessibility \o Accessibility for Qt 3 support widgets
351 \row \o \c qtaccessiblewidgets \o Accessibility \o Accessibility for Qt widgets
352 \row \o \c qdecorationdefault \o Decorations (Qt Extended) \o Default style
353 \row \o \c qdecorationwindows \o Decorations (Qt Extended) \o Windows style
354 \row \o \c qgif \o Image formats \o GIF
355 \row \o \c qjpeg \o Image formats \o JPEG
356 \row \o \c qmng \o Image formats \o MNG
357 \row \o \c qico \o Image formats \o ICO
358 \row \o \c qsvg \o Image formats \o SVG
359 \row \o \c qtiff \o Image formats \o TIFF
360 \row \o \c qimsw_multi \o Input methods (Qt Extended) \o Input Method Switcher
361 \row \o \c qwstslibmousehandler \o Mouse drivers (Qt Extended) \o \c tslib mouse
362 \row \o \c qgfxtransformed \o Graphic drivers (Qt Extended) \o Transformed screen
363 \row \o \c qgfxvnc \o Graphic drivers (Qt Extended) \o VNC
364 \row \o \c qscreenvfb \o Graphic drivers (Qt Extended) \o Virtual frame buffer
365 \row \o \c qsqldb2 \o SQL driver \o IBM DB2 \row \o \c qsqlibase \o SQL driver \o Borland InterBase
366 \row \o \c qsqlite \o SQL driver \o SQLite version 3
367 \row \o \c qsqlite2 \o SQL driver \o SQLite version 2
368 \row \o \c qsqlmysql \o SQL driver \o MySQL
369 \row \o \c qsqloci \o SQL driver \o Oracle (OCI)
370 \row \o \c qsqlodbc \o SQL driver \o Open Database Connectivity (ODBC)
371 \row \o \c qsqlpsql \o SQL driver \o PostgreSQL
372 \row \o \c qsqltds \o SQL driver \o Sybase Adaptive Server (TDS)
373 \row \o \c qcncodecs \o Text codecs \o Simplified Chinese (People's Republic of China)
374 \row \o \c qjpcodecs \o Text codecs \o Japanese
375 \row \o \c qkrcodecs \o Text codecs \o Korean
376 \row \o \c qtwcodecs \o Text codecs \o Traditional Chinese (Taiwan)
379 To link statically against those plugins, you need to use the
380 Q_IMPORT_PLUGIN() macro in your application and you need to add
381 the required plugins to your build using \c QTPLUGIN.
382 For example, in your \c main.cpp:
384 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 4
386 In the \c .pro file for your application, you need the following
389 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 5
391 It is also possible to create your own static plugins, by
392 following these steps:
395 \o Add \c{CONFIG += static} to your plugin's \c .pro file.
396 \o Use the Q_IMPORT_PLUGIN() macro in your application.
397 \o Link your application with your plugin library using \c LIBS
401 See the \l{tools/plugandpaint}{Plug & Paint} example and the
402 associated \l{tools/plugandpaintplugins/basictools}{Basic Tools}
403 plugin for details on how to do this.
405 \note If you are not using qmake to build your application you need
406 to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is
409 \sa QPluginLoader, QLibrary, {Plug & Paint Example}
411 \section1 The Plugin Cache
413 In order to speed up loading and validation of plugins, some of
414 the information that is collected when plugins are loaded is cached
415 through QSettings. This includes information about whether or not
416 a plugin was successfully loaded, so that subsequent load operations
417 don't try to load an invalid plugin. However, if the "last modified"
418 timestamp of a plugin has changed, the plugin's cache entry is
419 invalidated and the plugin is reloaded regardless of the values in
420 the cache entry, and the cache entry itself is updated with the new
423 This also means that the timestamp must be updated each time the
424 plugin or any dependent resources (such as a shared library) is
425 updated, since the dependent resources might influence the result
428 Sometimes, when developing plugins, it is necessary to remove entries
429 from the plugin cache. Since Qt uses QSettings to manage the plugin
430 cache, the locations of plugins are platform-dependent; see
431 \l{QSettings#Platform-Specific Notes}{the QSettings documentation}
432 for more information about each platform.
434 For example, on Windows the entries are stored in the registry, and the
435 paths for each plugin will typically begin with either of these two strings:
437 \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 6
439 \section1 Debugging Plugins
441 There are a number of issues that may prevent correctly-written plugins from
442 working with the applications that are designed to use them. Many of these
443 are related to differences in the way that plugins and applications have been
444 built, often arising from separate build systems and processes.
446 The following table contains descriptions of the common causes of problems
447 developers experience when creating plugins:
450 \header \o Problem \o Cause \o Solution
451 \row \o Plugins sliently fail to load even when opened directly by the
452 application. \QD shows the plugin libraries in its
453 \gui{Help|About Plugins} dialog, but no plugins are listed under each
455 \o The application and its plugins are built in different modes.
456 \o Either share the same build information or build the plugins in both
457 debug and release modes by appending the \c debug_and_release to
458 the \l{qmake Variable Reference#CONFIG}{CONFIG} variable in each of
460 \row \o A valid plugin that replaces an invalid (or broken) plugin fails to load.
461 \o The entry for the plugin in the plugin cache indicates that the original
462 plugin could not be loaded, causing Qt to ignore the replacement.
463 \o Either ensure that the plugin's timestamp is updated, or delete the
464 entry in the \l{#The Plugin Cache}{plugin cache}.
467 You can also use the \c QT_DEBUG_PLUGINS environment variable to obtain
468 diagnostic information from Qt about each plugin it tries to load. Set this
469 variable to a non-zero value in the environment from which your application is