| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \page plugins-howto.html |
| \title How to Create Qt Plugins |
| \brief A guide to creating plugins to extend Qt's applications and functionalities. |
| |
| \ingroup frameworks-technologies |
| \ingroup qt-basic-concepts |
| \ingroup best-practices |
| |
| |
| \keyword QT_DEBUG_PLUGINS |
| \keyword QT_NO_PLUGIN_CHECK |
| |
| Qt provides two APIs for creating plugins: |
| |
| \list |
| \li A high-level API for writing extensions to Qt itself: custom database |
| drivers, image formats, text codecs, custom styles, etc. |
| \li A low-level API for extending Qt applications. |
| \endlist |
| |
| For example, if you want to write a custom QStyle subclass and |
| have Qt applications load it dynamically, you would use the |
| higher-level API. |
| |
| Since the higher-level API is built on top of the lower-level API, |
| some issues are common to both. |
| |
| If you want to provide plugins for use with Qt Designer, see the Qt Designer |
| module documentation. |
| |
| Topics: |
| |
| \tableofcontents |
| |
| \section1 The High-Level API: Writing Qt Extensions |
| |
| Writing a plugin that extends Qt itself is achieved by |
| subclassing the appropriate plugin base class, implementing a few |
| functions, and adding a macro. |
| |
| There are several plugin base classes. Derived plugins are stored |
| by default in sub-directories of the standard plugin directory. Qt |
| will not find plugins if they are not stored in the appropriate directory. |
| |
| The following table summarizes the plugin base classes. Some of the classes |
| are private, and are therefore not documented. You can use them, but there |
| is no compatibility promise with later Qt versions. |
| |
| \table |
| \header |
| \li Base Class |
| \li Directory Name |
| \li Qt Module |
| \li Key Case Sensitivity |
| \row |
| \li QAccessibleBridgePlugin |
| \li \c accessiblebridge |
| \li \l{Qt GUI} |
| \li Case Sensitive |
| |
| \row |
| \li QImageIOPlugin |
| \li \c imageformats |
| \li \l{Qt GUI} |
| \li Case Sensitive |
| \row |
| \li QPictureFormatPlugin (obsolete) |
| \li \c pictureformats |
| \li \l{Qt GUI} |
| \li Case Sensitive |
| \row |
| \li QAudioSystemPlugin |
| \li \c audio |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QDeclarativeVideoBackendFactoryInterface |
| \li \c video/declarativevideobackend |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QGstBufferPoolPlugin |
| \li \c video/bufferpool |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QMediaPlaylistIOPlugin |
| \li \c playlistformats |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QMediaResourcePolicyPlugin |
| \li \c resourcepolicy |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QMediaServiceProviderPlugin |
| \li \c mediaservice |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QSGVideoNodeFactoryPlugin |
| \li \c video/videonode |
| \li \l{Qt Multimedia} |
| \li Case Insensitive |
| \row |
| \li QBearerEnginePlugin |
| \li \c bearer |
| \li \l{Qt Network} |
| \li Case Sensitive |
| \row |
| \li QPlatformInputContextPlugin |
| \li \c platforminputcontexts |
| \li \l{Qt Platform Abstraction} |
| \li Case Insensitive |
| \row |
| \li QPlatformIntegrationPlugin |
| \li \c platforms |
| \li \l{Qt Platform Abstraction} |
| \li Case Insensitive |
| \row |
| \li QPlatformThemePlugin |
| \li \c platformthemes |
| \li \l{Qt Platform Abstraction} |
| \li Case Insensitive |
| \row |
| \li QGeoPositionInfoSourceFactory |
| \li \c position |
| \li \l{Qt Positioning} |
| \li Case Sensitive |
| \row |
| \li QPlatformPrinterSupportPlugin |
| \li \c printsupport |
| \li \l{Qt Print Support} |
| \li Case Insensitive |
| \row |
| \li QSGContextPlugin |
| \li \c scenegraph |
| \li \l{Qt Quick} |
| \li Case Sensitive |
| \row |
| \li QScriptExtensionPlugin |
| \li \c script |
| \li \l{Qt Script} |
| \li Case Sensitive |
| \row |
| \li QSensorGesturePluginInterface |
| \li \c sensorgestures |
| \li \l{Qt Sensors} |
| \li Case Sensitive |
| \row |
| \li QSensorPluginInterface |
| \li \c sensors |
| \li \l{Qt Sensors} |
| \li Case Sensitive |
| \row |
| \li QSqlDriverPlugin |
| \li \c sqldrivers |
| \li \l{Qt SQL} |
| \li Case Sensitive |
| \row |
| \li QIconEnginePlugin |
| \li \c iconengines |
| \li \l{Qt SVG} |
| \li Case Insensitive |
| \row |
| \li QAccessiblePlugin |
| \li \c accessible |
| \li \l{Qt Widgets} |
| \li Case Sensitive |
| \row |
| \li QStylePlugin |
| \li \c styles |
| \li \l{Qt Widgets} |
| \li Case Insensitive |
| \endtable |
| |
| If you have a new style class called \c MyStyle that you |
| want to make available as a plugin, the class needs to be defined |
| as follows (\c mystyleplugin.h): |
| |
| \snippet plugins/doc_src_plugins-howto.cpp 0 |
| |
| Ensure that the class implementation is located in a \c .cpp file: |
| |
| \snippet plugins/doc_src_plugins-howto.cpp 1 |
| |
| (Note that QStylePlugin is case-insensitive, and the lowercase |
| version of the key is used in our |
| \l{QStylePlugin::create()}{create()} implementation; most other |
| plugins are case sensitive.) |
| |
| In addition, a json file (\c mystyleplugin.json) containing meta data |
| describing the plugin is required for most plugins. For style |
| plugins it simply contains a list of styles that can be created |
| by the plugin: |
| |
| \snippet plugins/doc_src_plugins-howto.qdoc 6 |
| |
| The type of information that needs to be provided in the json file |
| is plugin dependent, please see the class documentation for |
| details on the information that needs to be contained in the |
| file. |
| |
| For database drivers, image formats, text codecs, and most other |
| plugin types, no explicit object creation is required. Qt will |
| find and create them as required. Styles are an exception, since |
| you might want to set a style explicitly in code. To apply a |
| style, use code like this: |
| |
| \snippet plugins/doc_src_plugins-howto.cpp 2 |
| |
| Some plugin classes require additional functions to be |
| implemented. See the class documentation for details of the |
| virtual functions that must be reimplemented for each type of |
| plugin. |
| |
| The \l{Style Plugin Example} shows how to implement a plugin |
| that extends the QStylePlugin base class. |
| |
| \section1 The Low-Level API: Extending Qt Applications |
| |
| Not only Qt itself but also Qt application can be extended |
| through plugins. This requires the application to detect and load |
| plugins using QPluginLoader. In that context, plugins may provide |
| arbitrary functionality and are not limited to database drivers, |
| image formats, text codecs, styles, and the other types of plugin |
| that extend Qt's functionality. |
| |
| Making an application extensible through plugins involves the |
| following steps: |
| |
| \list 1 |
| \li Define a set of interfaces (classes with only pure virtual |
| functions) used to talk to the plugins. |
| \li Use the Q_DECLARE_INTERFACE() macro to tell Qt's |
| \l{meta-object system} about the interface. |
| \li Use QPluginLoader in the application to load the plugins. |
| \li Use qobject_cast() to test whether a plugin implements a given |
| interface. |
| \endlist |
| |
| Writing a plugin involves these steps: |
| |
| \list 1 |
| \li Declare a plugin class that inherits from QObject and from the |
| interfaces that the plugin wants to provide. |
| \li Use the Q_INTERFACES() macro to tell Qt's \l{meta-object |
| system} about the interfaces. |
| \li Export the plugin using the Q_PLUGIN_METADATA() macro. |
| \li Build the plugin using a suitable \c .pro file. |
| \endlist |
| |
| For example, here's the definition of an interface class: |
| |
| \snippet plugins/interfaces.h 2 |
| |
| Here's the definition of a plugin class that implements that |
| interface: |
| |
| \snippet plugins/extrafiltersplugin.h 0 |
| |
| The \l{tools/plugandpaint/app}{Plug & Paint} example documentation |
| explains this process in detail. See also \l{Creating Custom |
| Widgets for Qt Designer} for information about issues that are |
| specific to Qt Designer. You can also take a look at the |
| \l{Echo Plugin Example} which is a more trivial example on |
| how to implement a plugin that extends Qt applications. |
| Please note that a QCoreApplication must have been initialized |
| before plugins can be loaded. |
| |
| \section1 Locating Plugins |
| |
| Qt applications automatically know which plugins are available, |
| because plugins are stored in the standard plugin subdirectories. |
| Because of this applications don't require any code to find and load |
| plugins, since Qt handles them automatically. |
| |
| During development, the directory for plugins is \c{QTDIR/plugins} |
| (where \c QTDIR is the directory where Qt is installed), with each |
| type of plugin in a subdirectory for that type, for example, \c styles. If |
| you want your applications to use plugins and you don't want to use |
| the standard plugins path, have your installation process |
| determine the path you want to use for the plugins, and save the |
| path, for example, by using QSettings, for the application to read when it |
| runs. The application can then call QCoreApplication::addLibraryPath() |
| with this path and your plugins will be available to the application. |
| Note that the final part of the path (for example, \c styles) cannot be changed. |
| |
| If you want the plugin to be loadable then one approach is to |
| create a subdirectory under the application, and place the plugin |
| in that directory. If you distribute any of the plugins that come |
| with Qt (the ones located in the \c plugins directory), you must |
| copy the subdirectory under \c plugins where the plugin is |
| located to your applications root folder (i.e., do not include the |
| \c plugins directory). |
| |
| For more information about deployment, |
| see the \l {Deploying Qt Applications} and \l {Deploying Plugins} |
| documentation. |
| |
| \section1 Static Plugins |
| |
| The normal and most flexible way to include a plugin with an |
| application is to compile it into a dynamic library that is shipped |
| separately, and detected and loaded at runtime. |
| |
| Plugins can be linked statically into your application. If you |
| build the static version of Qt, this is the only option for |
| including Qt's predefined plugins. Using static plugins makes the |
| deployment less error-prone, but has the disadvantage that no |
| functionality from plugins can be added without a complete rebuild |
| and redistribution of the application. |
| |
| To link plugins statically, you need to add |
| the required plugins to your build using \c QTPLUGIN. |
| |
| In the \c .pro file for your application, you need the following |
| entry: |
| |
| \snippet plugins/doc_src_plugins-howto.pro 5 |
| |
| qmake automatically adds the plugins to QTPLUGIN that are typically |
| needed by the Qt modules used (see \l QT), while more specialized |
| plugins need to be added manually. |
| The default list of automatically added plugins can be overridden |
| per type. |
| For example, to link the minimal plugin instead of the default Qt |
| platform adaptation plugin, use: |
| |
| \snippet plugins/doc_src_plugins-howto.pro 4 |
| |
| If you want neither the default, nor the minimal QPA plugin to be |
| linked automatically, use: |
| |
| \snippet plugins/doc_src_plugins-howto.pro 6 |
| |
| The defaults are tuned towards an optimal out-of-the-box experience, |
| but may unnecessarily bloat the application. |
| It is recommended to inspect the linker command line built by qmake |
| and eliminate unnecessary plugins. |
| |
| \section2 Details of Linking Static Plugins |
| |
| To cause static plugins actually being linked and instantiated, |
| Q_IMPORT_PLUGIN() macros are also needed in application code, |
| but those are automatically generated by qmake and added to |
| your application project. |
| |
| If you do not want all plugins added to QTPLUGIN to be automatically |
| linked, remove \c import_plugins from the \c CONFIG variable: |
| |
| \snippet plugins/doc_src_plugins-howto.pro 7 |
| |
| \section2 Creating Static Plugins |
| |
| It is also possible to create your own static plugins, by |
| following these steps: |
| |
| \list 1 |
| \li Add \c{CONFIG += static} to your plugin's \c .pro file. |
| \li Use the Q_IMPORT_PLUGIN() macro in your application. |
| \li Use the Q_INIT_RESOURCE() macro in your application if the plugin ships |
| qrc files. |
| \li Link your application with your plugin library using \c LIBS |
| in the \c .pro file. |
| \endlist |
| |
| See the \l{tools/plugandpaint/app}{Plug & Paint} example and the |
| associated \l{tools/plugandpaint/plugins/basictools}{Basic Tools} |
| plugin for details on how to do this. |
| |
| \note If you are not using qmake to build your plugin you need |
| to make sure that the \c{QT_STATICPLUGIN} preprocessor macro is |
| defined. |
| |
| \section1 Deploying and Debugging Plugins |
| |
| The \l{Deploying Plugins} document covers the process of deploying |
| plugins with applications and debugging them when problems arise. |
| |
| \sa QPluginLoader, QLibrary, {Plug & Paint Example} |
| */ |
