AuroraMiddleware/qt5base-lts
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Fixup the plugin documentation

Browse Source 
Move the plugin howto from qtdoc to corelib where
it belongs. Fix the snippets and remove all
remaining references to Q_EXPORT_PLUGIN

Task-number: QTBUG-26237
Change-Id: I43dce2ffa42193b7a992fa1a0f2fcb2f633037b2
Reviewed-by: Casper van Donderen <casper.vandonderen@nokia.com>
This commit is contained in:
Lars Knoll 2012-07-26 13:56:14 +02:00 committed by Qt by Nokia
parent 3658eedc97
commit b31501020f
7 changed files with 497 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
src/corelib/doc/snippets/code/doc_src_plugins-howto.cpp Normal file
View File

@ -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]

50
src/corelib/doc/snippets/code/doc_src_plugins-howto.pro Normal file
View File

@ -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]

43
src/corelib/doc/snippets/code/doc_src_plugins-howto.qdoc Normal file
View File

@ -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]

303
src/corelib/doc/src/plugins-howto.qdoc Normal file
View File

@ -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}
*/

12
src/widgets/doc/snippets/qstyleplugin/main.cpp
View File

@ -41,14 +41,17 @@
#include <QApplication> #include <QApplication>
#include <QtGui> #include <QtGui>
//! [0]
class MyStylePlugin : public QStylePlugin class MyStylePlugin : public QStylePlugin
{ {
Q_OBJECT
Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QStyleFactoryInterface" FILE mystyleplugin.json)
public: public:
MyStylePlugin(QObject *parent = 0); MyStylePlugin(QObject *parent = 0);
QStyle *create(const QString &key); QStyle *create(const QString &key);
QStringList keys() const;
}; };
//! [0]
class RocketStyle : public QCommonStyle class RocketStyle : public QCommonStyle
{ {
@ -68,26 +71,23 @@ MyStylePlugin::MyStylePlugin(QObject *parent)
{ {
} }
//! [0]
QStringList MyStylePlugin::keys() const QStringList MyStylePlugin::keys() const
{ {
return QStringList() << "Rocket" << "StarBuster"; return QStringList() << "Rocket" << "StarBuster";
} }
//! [0]
//! [1] //! [1]
QStyle *MyStylePlugin::create(const QString &key) QStyle *MyStylePlugin::create(const QString &key)
{ {
QString lcKey = key; QString lcKey = key.toLower();
if (lcKey == "rocket") { if (lcKey == "rocket") {
return new RocketStyle; return new RocketStyle;
} else if (lcKey == "starbuster") { } else if (lcKey == "starbuster") {
return new StarBusterStyle; return new StarBusterStyle;
} }
return 0; return 0;
//! [1] //! [2]
} }
//! [2] //! [1]
int main(int argc, char *argv[]) int main(int argc, char *argv[])
{ {

2
src/widgets/doc/snippets/qstyleplugin/mystyleplugin.json Normal file
View File

@ -0,0 +1,2 @@
{ "Keys": [ "Rocket", "Starbuster" ] }

19
src/widgets/styles/qstyleplugin.cpp
View File

@ -57,15 +57,17 @@ QT_BEGIN_NAMESPACE
Writing a style plugin is achieved by subclassing this base class, Writing a style plugin is achieved by subclassing this base class,
reimplementing the pure virtual create() function, and reimplementing the pure virtual create() function, and
exporting the class using the Q_PLUGIN_METADATA() macro. See \l exporting the class using the Q_PLUGIN_METADATA() macro.
{How to Create Qt Plugins} for details.
The json metadata file for the plugin needs to contain information \snippet qstyleplugin/main.cpp 0
about the names of the styles the plugins supports as follows:
\code The json metadata file \c mystyleplugin.json for the plugin needs
{ "Keys": [ "mystyle" ] } to contain information about the names of the styles the plugins
\endcode supports as follows:
\quotefile qstyleplugin/mystyleplugin.json
See \l {How to Create Qt Plugins} for details.
\sa QStyleFactory, QStyle \sa QStyleFactory, QStyle
*/ */
@ -79,10 +81,7 @@ QT_BEGIN_NAMESPACE
The style key is usually the class name of the required The style key is usually the class name of the required
style. Note that the keys are case insensitive. For example: 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 1
\snippet qstyleplugin/main.cpp 2
\sa keys() \sa keys()
*/ */