diff options
| -rw-r--r-- | src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp | 84 | ||||
| -rw-r--r-- | src/corelib/doc/snippets/code/doc_src_plugins-howto.pro | 50 | ||||
| -rw-r--r-- | src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc | 43 | ||||
| -rw-r--r-- | src/corelib/doc/src/plugins-howto.qdoc | 303 | ||||
| -rw-r--r-- | src/widgets/doc/snippets/qstyleplugin/main.cpp | 12 | ||||
| -rw-r--r-- | src/widgets/doc/snippets/qstyleplugin/mystyleplugin.json | 2 | ||||
| -rw-r--r-- | src/widgets/styles/qstyleplugin.cpp | 19 |
7 files changed, 497 insertions, 16 deletions
diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp b/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp new file mode 100644 index 0000000000..71f0d7e171 --- /dev/null +++ b/src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp @@ -0,0 +1,84 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [0] +class MyStylePlugin : public QStylePlugin +{ + Q_OBJECT + Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QStyleFactoryInterface" FILE mystyleplugin.json) +public: + QStyle *create(const QString &key); +}; +//! [0] + + +//! [1] +#include "mystyleplugin.h" + +QStyle *MyStylePlugin::create(const QString &key) +{ + if (key.toLower() == "mystyle") + return new MyStyle; + return 0; +} + +//! [1] + + +//! [2] +QApplication::setStyle(QStyleFactory::create("MyStyle")); +//! [2] + + +//! [4] +#include <QApplication> +#include <QtPlugin> + +Q_IMPORT_PLUGIN(qjpeg) +Q_IMPORT_PLUGIN(qgif) +Q_IMPORT_PLUGIN(qkrcodecs) + +int main(int argc, char *argv[]) +{ + QApplication app(argc, argv); + ... + return app.exec(); +} +//! [4] diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro b/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro new file mode 100644 index 0000000000..c4c5238bdd --- /dev/null +++ b/src/corelib/doc/snippets/code/doc_src_plugins-howto.pro @@ -0,0 +1,50 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +#! [3] +CONFIG += release +#! [3] + + +#! [5] +QTPLUGIN += qjpeg \ + qgif \ + qkrcodecs +#! [5] diff --git a/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc b/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc new file mode 100644 index 0000000000..029acf1c8c --- /dev/null +++ b/src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc @@ -0,0 +1,43 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:BSD$ +** You may use this file under the terms of the BSD license as follows: +** +** "Redistribution and use in source and binary forms, with or without +** modification, are permitted provided that the following conditions are +** met: +** * Redistributions of source code must retain the above copyright +** notice, this list of conditions and the following disclaimer. +** * Redistributions in binary form must reproduce the above copyright +** notice, this list of conditions and the following disclaimer in +** the documentation and/or other materials provided with the +** distribution. +** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor +** the names of its contributors may be used to endorse or promote +** products derived from this software without specific prior written +** permission. +** +** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +//! [6] +{ "Keys": [ "mystyleplugin" ] } +//! [6] diff --git a/src/corelib/doc/src/plugins-howto.qdoc b/src/corelib/doc/src/plugins-howto.qdoc new file mode 100644 index 0000000000..059a02f566 --- /dev/null +++ b/src/corelib/doc/src/plugins-howto.qdoc @@ -0,0 +1,303 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \group plugins + \title Plugin Classes + \ingroup groups + + \brief Plugin related classes. + + These classes deal with shared libraries, (e.g. .so and DLL files), + and with Qt plugins. + + See the \link plugins-howto.html plugins documentation\endlink. + + See also the \l{ActiveQt framework} for Windows. +*/ + +/*! + \page plugins-howto.html + \title How to Create Qt Plugins + \brief A guide to creating plugins to extend Qt applications and + functionality provided by Qt. + + \ingroup frameworks-technologies + \ingroup qt-basic-concepts + + + \keyword QT_DEBUG_PLUGINS + \keyword QT_NO_PLUGIN_CHECK + + Qt provides two APIs for creating plugins: + + \list + \li A higher-level API for writing extensions to Qt itself: custom database + drivers, image formats, text codecs, custom styles, etc. + \li A lower-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 \QD, see the QtDesigner + module documentation. + + Topics: + + \tableofcontents + + \section1 The Higher-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 right + directory. + + \table + \header \li Base Class \li Directory Name \li Key Case Sensitivity + \row \li QAccessibleBridgePlugin \li \c accessiblebridge \li Case Sensitive + \row \li QAccessiblePlugin \li \c accessible \li Case Sensitive + \row \li QDecorationPlugin \li \c decorations \li Case Insensitive + \row \li QFontEnginePlugin \li \c fontengines \li Case Insensitive + \row \li QIconEnginePlugin \li \c iconengines \li Case Insensitive + \row \li QImageIOPlugin \li \c imageformats \li Case Sensitive + \row \li QInputContextPlugin \li \c inputmethods \li Case Sensitive + \row \li QKbdDriverPlugin \li \c kbddrivers \li Case Insensitive + \row \li QMouseDriverPlugin \li \c mousedrivers \li Case Insensitive + \row \li QScreenDriverPlugin \li \c gfxdrivers \li Case Insensitive + \row \li QScriptExtensionPlugin \li \c script \li Case Sensitive + \row \li QSqlDriverPlugin \li \c sqldrivers \li Case Sensitive + \row \li QStylePlugin \li \c styles \li Case Insensitive + \row \li QTextCodecPlugin \li \c codecs \li Case Sensitive + \endtable + + Suppose that you have a new style class called \c MyStyle that you + want to make available as a plugin. The required code is + straightforward, here is the class definition (\c + mystyleplugin.h): + + \snippet code/doc_src_plugins-howto.cpp 0 + + Ensure that the class implementation is located in a \c .cpp file: + + \snippet code/doc_src_plugins-howto.cpp 1 + + (Note that QStylePlugin is case insensitive, and the lower-case + version of the key is used in our + \l{QStylePlugin::create()}{create()} implementation; most other + plugins are case sensitive.) + + In addition a \c mystyleplugin.json file 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 code/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 code/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 Lower-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 examples/tools/plugandpaint/interfaces.h 2 + + Here's the definition of a plugin class that implements that + interface: + + \snippet examples/tools/plugandpaintplugins/extrafilters/extrafiltersplugin.h 0 + + The \l{tools/plugandpaint}{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 \QD. You can also take a look at the \l{Echo Plugin + Example} 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, e.g. \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, e.g. 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 (e.g., \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 sub-directory 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 against 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. + + When compiled as a static library, Qt provides the following + static plugins: + + \table + \header \li Plugin name \li Type \li Description + \row \li \c qtaccessiblewidgets \li Accessibility \li Accessibility for Qt widgets + \row \li \c qgif \li Image formats \li GIF + \row \li \c qjpeg \li Image formats \li JPEG + \row \li \c qmng \li Image formats \li MNG + \row \li \c qico \li Image formats \li ICO + \row \li \c qsvg \li Image formats \li SVG + \row \li \c qtiff \li Image formats \li TIFF + \row \li \c qsqldb2 \li SQL driver \li IBM DB2 \row \li \c qsqlibase \li SQL driver \li Borland InterBase + \row \li \c qsqlite \li SQL driver \li SQLite version 3 + \row \li \c qsqlite2 \li SQL driver \li SQLite version 2 + \row \li \c qsqlmysql \li SQL driver \li MySQL + \row \li \c qsqloci \li SQL driver \li Oracle (OCI) + \row \li \c qsqlodbc \li SQL driver \li Open Database Connectivity (ODBC) + \row \li \c qsqlpsql \li SQL driver \li PostgreSQL + \row \li \c qsqltds \li SQL driver \li Sybase Adaptive Server (TDS) + \endtable + + To link statically against those plugins, you need to use the + Q_IMPORT_PLUGIN() macro in your application and you need to add + the required plugins to your build using \c QTPLUGIN. + For example, in your \c main.cpp: + + \snippet code/doc_src_plugins-howto.cpp 4 + + In the \c .pro file for your application, you need the following + entry: + + \snippet code/doc_src_plugins-howto.pro 5 + + 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 Link your application with your plugin library using \c LIBS + in the \c .pro file. + \endlist + + See the \l{tools/plugandpaint}{Plug & Paint} example and the + associated \l{tools/plugandpaintplugins/basictools}{Basic Tools} + plugin for details on how to do this. + + \note If you are not using qmake to build your application 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} +*/ diff --git a/src/widgets/doc/snippets/qstyleplugin/main.cpp b/src/widgets/doc/snippets/qstyleplugin/main.cpp index 10a122016f..46554695f7 100644 --- a/src/widgets/doc/snippets/qstyleplugin/main.cpp +++ b/src/widgets/doc/snippets/qstyleplugin/main.cpp @@ -41,14 +41,17 @@ #include <QApplication> #include <QtGui> +//! [0] class MyStylePlugin : public QStylePlugin { + Q_OBJECT + Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QStyleFactoryInterface" FILE mystyleplugin.json) public: MyStylePlugin(QObject *parent = 0); QStyle *create(const QString &key); - QStringList keys() const; }; +//! [0] class RocketStyle : public QCommonStyle { @@ -68,26 +71,23 @@ MyStylePlugin::MyStylePlugin(QObject *parent) { } -//! [0] QStringList MyStylePlugin::keys() const { return QStringList() << "Rocket" << "StarBuster"; } -//! [0] //! [1] QStyle *MyStylePlugin::create(const QString &key) { - QString lcKey = key; + QString lcKey = key.toLower(); if (lcKey == "rocket") { return new RocketStyle; } else if (lcKey == "starbuster") { return new StarBusterStyle; } return 0; -//! [1] //! [2] } -//! [2] +//! [1] int main(int argc, char *argv[]) { diff --git a/src/widgets/doc/snippets/qstyleplugin/mystyleplugin.json b/src/widgets/doc/snippets/qstyleplugin/mystyleplugin.json new file mode 100644 index 0000000000..64f140c60c --- /dev/null +++ b/src/widgets/doc/snippets/qstyleplugin/mystyleplugin.json @@ -0,0 +1,2 @@ +{ "Keys": [ "Rocket", "Starbuster" ] } + diff --git a/src/widgets/styles/qstyleplugin.cpp b/src/widgets/styles/qstyleplugin.cpp index ed68b7cbc1..63d11af963 100644 --- a/src/widgets/styles/qstyleplugin.cpp +++ b/src/widgets/styles/qstyleplugin.cpp @@ -57,15 +57,17 @@ QT_BEGIN_NAMESPACE Writing a style plugin is achieved by subclassing this base class, reimplementing the pure virtual create() function, and - exporting the class using the Q_PLUGIN_METADATA() macro. See \l - {How to Create Qt Plugins} for details. + exporting the class using the Q_PLUGIN_METADATA() macro. - The json metadata file for the plugin needs to contain information - about the names of the styles the plugins supports as follows: + \snippet qstyleplugin/main.cpp 0 + + The json metadata file \c mystyleplugin.json for the plugin needs + to contain information about the names of the styles the plugins + supports as follows: - \code - { "Keys": [ "mystyle" ] } - \endcode + \quotefile qstyleplugin/mystyleplugin.json + + See \l {How to Create Qt Plugins} for details. \sa QStyleFactory, QStyle */ @@ -79,10 +81,7 @@ QT_BEGIN_NAMESPACE The style key is usually the class name of the required style. Note that the keys are case insensitive. For example: - \snippet qstyleplugin/main.cpp 0 - \codeline \snippet qstyleplugin/main.cpp 1 - \snippet qstyleplugin/main.cpp 2 \sa keys() */ |