You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
301 lines
12 KiB
301 lines
12 KiB
/****************************************************************************
|
|
**
|
|
** ...
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the TQt 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 TQt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements 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 TQt 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 TQt 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 TQt 3.0.4 and
|
|
earlier will work with TQt 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, TQt 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, TQt will look in \c{C:\Program
|
|
Files\MyApp\styles}. (See \l{QApplication::applicationDirPath()} for
|
|
how to find out where the application's executable is.) TQt will also
|
|
look in the directory given by \c{tqInstallPathPlugins()}. 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 required 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
|
|
required 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 required. TQt 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:
|
|
\code
|
|
QApplication::setStyle( QStyleFactory::create( "MyStyle" ) );
|
|
\endcode
|
|
|
|
Some plugin classes require additional functions to be implemented.
|
|
See the \link designer-manual.book TQt 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 require any code to find and load
|
|
plugins, since TQt handles them automatically.
|
|
|
|
The default directory for plugins is \c{TQTDIR/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 TQt Designer\endlink, you may need to
|
|
call QApplication::addLibraryPath("TQTDIR/plugins/designer") to load
|
|
your \link designer-manual.book TQt Designer\endlink plugins.
|
|
|
|
<sup>*</sup><small> All references to \c{TQTDIR} refer to the path
|
|
where TQt was installed. </small>
|
|
|
|
\section1 Loading and Verifying Plugins
|
|
|
|
When loading plugins, the TQt 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 TQt library installed side by side.
|
|
\list
|
|
\i Plugins linked with a TQt 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 TQt 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 TQt 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 TQt libraries have different names.
|
|
A library \e with thread support that loads a plugin linked against a
|
|
TQt 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 TQt library to be loaded. When this
|
|
happens, the constructors for all static objects in the TQt 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 TQt library cannot be replaced or copied
|
|
when the non-threaded TQt library is loaded.
|
|
|
|
\i Plugins linked against a TQt 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 TQt 3.0.5, both the TQt library and all plugins are
|
|
built using a \e {build key}. The build key in the TQt 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 TQt 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 TQt library are not binary compatible. The TQt 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 TQt library would require complex feature
|
|
and dependency queries and verification when loading plugins.
|
|
Requiring 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 TQt 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 TQt 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 TQt library and the threaded TQt library in
|
|
an application. If your application uses the threaded TQt library, you
|
|
should not link your plugin with the normal TQt library. Nor should you
|
|
dynamically load the normal TQt library or dynamically load another library,
|
|
e.g. a plugin, that depends on the normal TQt library. On some systems,
|
|
mixing threaded and non-threaded libraries or plugins will corrupt the
|
|
static data used in the TQt library.
|
|
|
|
*/
|