diff options
Diffstat (limited to 'doc/plugins-howto.doc')
| -rw-r--r-- | doc/plugins-howto.doc | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/plugins-howto.doc b/doc/plugins-howto.doc new file mode 100644 index 000000000..813dc9c22 --- /dev/null +++ b/doc/plugins-howto.doc @@ -0,0 +1,300 @@ +/**************************************************************************** +** +** ... +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + +/*! +\page plugins-howto.html + +\title Qt Plugins HOWTO + +Qt provides a simple plugin interface which makes it easy to create +custom database drivers, image formats, text codecs, styles and +widgets as stand-alone components. +\footnote Qt 3.0.5 introduces changes into some aspects of plugins, in +particular regarding loading, path handling and library versions. As +a result of this change, <b>\e{no}</b> plugins compiled with Qt 3.0.4 and +earlier will work with Qt 3.0.5 and later: they must be recompiled. +\endfootnote + +Writing a plugin is achieved by subclassing the appropriate plugin +base clase, implementing a few functions, and adding a macro. + +There are five plugin base classes. Derived plugins are stored +by default in the standard plugin directory. + +\table +\header +\i Base Class +\i Default Path +\row +\i \l QImageFormatPlugin +\i \c{pluginsbase/imageformats} <sup>*</sup> +\row +\i \l QSqlDriverPlugin +\i \c{pluginsbase/sqldrivers} <sup>*</sup> +\row +\i \l QStylePlugin +\i \c{pluginsbase/styles} <sup>*</sup> +\row +\i \l QTextCodecPlugin +\i \c{pluginsbase/codecs} <sup>*</sup> +\row +\i \l QWidgetPlugin +\i \c{pluginsbase/designer} <sup>*</sup> +\endtable + +But where is the \c{pluginsbase} 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 \l{QApplication::applicationDirPath()} for +how to find out where the application's executable is.) Qt will also +look in the directory given by \c{qInstallPathPlugins()}. If you want +Qt to look in additional places you can add as many paths as you need +with calls to \c{QApplication::addLibraryPath()}. And if you want to +set your own path or paths you can use +\c{QApplication::setLibraryPaths()}. + +Suppose that you have a new style class called 'MyStyle' that you want +to make available as a plugin. The retquired code is straightforward: +\code + class MyStylePlugin : public QStylePlugin + { + public: + MyStylePlugin() {} + ~MyStylePlugin() {} + + QStringList keys() const { + return QStringList() << "mystyle"; + } + + QStyle* create( const QString& key ) { + if ( key == "mystyle" ) + return new MyStyle; + return 0; + } + }; + + Q_EXPORT_PLUGIN( MyStylePlugin ) +\endcode + +(Note that QStyleFactory is case-insensitive, and the lower case +version of the key is used; other factories, e.g. QWidgetFactory, are +case sensitive.) + +The constructor and destructor do not need to do anything, so are left +empty. There are only two virtual functions that must be implemented. +The first is keys() which returns a string list of the classes +implemented in the plugin. (We've just implemented one class in the +example above.) The second is a function that returns an object of the +retquired class (or 0 if the plugin is asked to create an object of a +class that it doesn't implement). For QStylePlugin, this second +function is called create(). + +It is possible to implement any number of plugin subclasses in a +single plugin, providing they are all derived from the same base +class, e.g. QStylePlugin. + +For database drivers, image formats, custom widgets and text codecs, +no explicit object creation is retquired. Qt will find and create them +as retquired. Styles are an exception, since you might want to set a +style explicitly in code. To apply a style, use code like this: +\code + QApplication::setStyle( QStyleFactory::create( "MyStyle" ) ); +\endcode + +Some plugin classes retquire additional functions to be implemented. +See the \link designer-manual.book Qt Designer manual's\endlink, +'Creating Custom Widgets' section in the 'Creating Custom Widgets' +chapter, for a complete example of a QWidgetPlugin, which implements +extra functions to integrate the plugin into \e{Qt Designer}. The +\l QWidgetFactory class provides additional information on +QWidgetPlugins. + +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 retquire any code to find and load +plugins, since Qt handles them automatically. + +The default directory for plugins is \c{QTDIR/plugins}<sup>*</sup>, +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 QApplication::addLibraryPath() with this +path and your plugins will be available to the application. Note that +the final part of the path, i.e. \c styles, \c widgets, etc., cannot +be changed. + +The normal way to include a plugin with an application is either to +compile it in with the application, or to compile it into a \c DLL (or +\c so or other platform specific library type) 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, e.g. \c +appdir/plugins/designer, and place the plugin in that directory. + +For \link designer-manual.book Qt Designer\endlink, you may need to +call QApplication::addLibraryPath("QTDIR/plugins/designer") to load +your \link designer-manual.book Qt Designer\endlink plugins. + +<sup>*</sup><small> All references to \c{QTDIR} refer to the path +where Qt was installed. </small> + +\section1 Loading and Verifying Plugins + +When loading plugins, the Qt library does some sanity checking to +determine whether or not the plugin can be loaded and used. This +provides the ability to have multiple versions and configurations of +the Qt library installed side by side. +\list +\i Plugins linked with a Qt library that has a higher major and/or + minor version number will not be loaded by a library with a lower + major and/or minor version number. + + \e Rationale: + + A plugin linked against a newer Qt library may use new + features that are not available in older versions. Trolltech + has a policy of adding new features and APIs only between minor + releases, which is why this test only looks at the major and minor + version numbers, and not at the patchlevel version number. + +\i Plugins linked against a Qt library \e with thread support can only be + loaded by libraries that are built \e with thread support. + + \e Rationale: + + The threaded and non-threaded Qt libraries have different names. + A library \e with thread support that loads a plugin linked against a + Qt library \e without thread support will cause two versions of the same + library to be in memory at the same time. On UNIX systems, this + causes the non-threaded Qt library to be loaded. When this + happens, the constructors for all static objects in the Qt library + will be called a second time, but they will operate on the objects + already in memory. There is no way to work around this, as this is + a feature of the object binary format: the static symbols already + defined by the threaded Qt library cannot be replaced or copied + when the non-threaded Qt library is loaded. + +\i Plugins linked against a Qt library \e without thread support can only + be loaded by libraries that are built \e without thread support. + + \e Rationale: + + See the Rationale above. + +\i Starting with Qt 3.0.5, both the Qt library and all plugins are + built using a \e {build key}. The build key in the Qt library is + examined against the build key in the plugin, and if they match, + the plugin is loaded. If the build keys do not match, then the Qt + library refuses to load the plugin. + + \e Rationale: + + See the Rationale for the build key below. +\endlist + +\section1 The Build Key + +The build key contains the following information: +\list +\i Architecture, operating system and compiler. + + \e Rationale: + + In cases where different versions of the same compiler do not + produce binary compatible code, the version of the compiler is + also present in the build key. + +\i Configuration of the Qt library. The configuration is a list + of the missing features that affect the available API in the + library. + + \e Rationale: + + Two different configurations of the same version of + the Qt library are not binary compatible. The Qt library that + loads the plugin uses the list of (missing) features to + determine if the plugin is binary compatible. + + \e Note: There are cases where a plugin can use features that are + available in two different configurations. However, the + developer writing plugins would need to know which features are + in use, both in their plugin and internally by the utility + classes in Qt. The Qt library would retquire complex feature + and dependency queries and verification when loading plugins. + Retquiring this would place an unnecessary burden on the developer, and + increase the overhead of loading a plugin. To reduce both + development time and application runtime costs, a simple string + comparision of the build keys is used. + +\i Optionally, an extra string may be specified on the configure + script command line. + + \e Rationale: + + When distributing binaries of the Qt library with an + application, this provides a way for developers to write + plugins that can only be loaded by the library with which the + plugins were linked. +\endlist + +\section1 Plugins and Threaded Applications + +If you want to build a plugin which you want to use with a threaded Qt +library (whether or not the plugin itself uses threads) you must use a +threaded environment. Specifically, you must link the plugin with a +threaded Qt library, and you must build \link designer-manual.book Qt +Designer\endlink with that library. Your \c{.pro} file for your plugin +must include the line: +\code + CONFIG += thread +\endcode + +\warning Do not mix the normal Qt library and the threaded Qt library in +an application. If your application uses the threaded Qt library, you +should not link your plugin with the normal Qt library. Nor should you +dynamically load the normal Qt library or dynamically load another library, +e.g. a plugin, that depends on the normal Qt library. On some systems, +mixing threaded and non-threaded libraries or plugins will corrupt the +static data used in the Qt library. + +*/ |