source: trunk/doc/src/plugins-howto.qdoc@ 477

/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Qt Software Information ([email protected])
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** Commercial Usage
** Licensees holding valid Qt Commercial licenses may use this file in
** accordance with the Qt Commercial License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Nokia.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at [email protected].
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \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 howto

    \keyword QT_DEBUG_PLUGINS
    \keyword QT_NO_PLUGIN_CHECK

    Qt provides two APIs for creating plugins:

    \list
    \o A higher-level API for writing extensions to Qt itself: custom database
       drivers, image formats, text codecs, custom styles, etc.
    \o 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 \o Base Class              \o Directory Name                \o Key Case Sensitivity
    \row    \o QAccessibleBridgePlugin \o \c accessiblebridge \o Case Sensitive
    \row    \o QAccessiblePlugin       \o \c accessible       \o Case Sensitive
    \row    \o QDecorationPlugin       \o \c decorations      \o Case Insensitive
    \row    \o QFontEnginePlugin       \o \c fontengines      \o Case Insensitive
    \row    \o QIconEnginePlugin       \o \c iconengines      \o Case Insensitive
    \row    \o QImageIOPlugin          \o \c imageformats     \o Case Sensitive
    \row    \o QInputContextPlugin     \o \c inputmethods     \o Case Sensitive
    \row    \o QKbdDriverPlugin        \o \c kbddrivers       \o Case Insensitive
    \row    \o QMouseDriverPlugin      \o \c mousedrivers     \o Case Insensitive
    \row    \o QPictureFormatPlugin    \o \c pictureformats   \o Case Sensitive
    \row    \o QScreenDriverPlugin     \o \c gfxdrivers       \o Case Insensitive
    \row    \o QScriptExtensionPlugin  \o \c script           \o Case Sensitive
    \row    \o QSqlDriverPlugin        \o \c sqldrivers       \o Case Sensitive
    \row    \o QStylePlugin            \o \c styles           \o Case Insensitive
    \row    \o QTextCodecPlugin        \o \c codecs           \o Case Sensitive
    \endtable

    But where is the \c{plugins} directory? When the application
    is run, Qt will first treat the application's executable directory
    as the \c{pluginsbase}. For example if the application is in
    \c{C:\Program Files\MyApp} and has a style plugin, Qt will look in
    \c{C:\Program Files\MyApp\styles}. (See
    QCoreApplication::applicationDirPath() for how to find out where
    the application's executable is.) Qt will also look in the
    directory specified by
    QLibraryInfo::location(QLibraryInfo::PluginsPath), which typically
    is located in \c QTDIR/plugins (where \c QTDIR is the directory
    where Qt is installed). If you want Qt to look in additional
    places you can add as many paths as you need with calls to
    QCoreApplication::addLibraryPath(). And if you want to set your
    own path or paths you can use QCoreApplication::setLibraryPaths().
    You can also use a \c qt.conf file to override the hard-coded
    paths that are compiled into the Qt library. For more information,
    see the \l {Using qt.conf} documentation. Yet another possibility
    is to set the \c QT_PLUGIN_PATH environment variable before running
    the application. If set, Qt will look for plugins in the
    paths (separated by the system path separator) specified in the variable.

    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 doc/src/snippets/code/doc_src_plugins-howto.qdoc 0

    Ensure that the class implementation is located in a \c .cpp file
    (including the class definition):

    \snippet doc/src/snippets/code/doc_src_plugins-howto.qdoc 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.)

    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 doc/src/snippets/code/doc_src_plugins-howto.qdoc 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.

    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.

    The default 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.

    The normal way to include a plugin with an application is either
    to \l{Static Plugins}{compile it in with the application} or to
    compile it into a dynamic library and use it like any other
    library.

    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} documentation.

    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
    \o Define a set of interfaces (classes with only pure virtual
       functions) used to talk to the plugins.
    \o Use the Q_DECLARE_INTERFACE() macro to tell Qt's
       \l{meta-object system} about the interface.
    \o Use QPluginLoader in the application to load the plugins.
    \o Use qobject_cast() to test whether a plugin implements a given
       interface.
    \endlist

    Writing a plugin involves these steps:

    \list 1
    \o Declare a plugin class that inherits from QObject and from the
       interfaces that the plugin wants to provide.
    \o Use the Q_INTERFACES() macro to tell Qt's \l{meta-object
       system} about the interfaces.
    \o Export the plugin using the Q_EXPORT_PLUGIN2() macro.
    \o Build the plugin using a suitable \c .pro file.