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