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.
263 lines
13 KiB
263 lines
13 KiB
14 years ago
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/plugins-howto.doc:36 -->
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||
|
|
<title>Qt Plugins HOWTO</title>
|
||
|
|
<style type="text/css"><!--
|
||
|
|
fn { margin-left: 1cm; text-indent: -1cm; }
|
||
|
|
a:link { color: #004faf; text-decoration: none }
|
||
|
|
a:visited { color: #672967; text-decoration: none }
|
||
|
|
body { background: #ffffff; color: black; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
|
||
|
|
<table border="0" cellpadding="0" cellspacing="0" width="100%">
|
||
|
|
<tr bgcolor="#E5E5E5">
|
||
|
|
<td valign=center>
|
||
|
|
<a href="index.html">
|
||
|
|
<font color="#004faf">Home</font></a>
|
||
|
|
| <a href="classes.html">
|
||
|
|
<font color="#004faf">All Classes</font></a>
|
||
|
|
| <a href="mainclasses.html">
|
||
|
|
<font color="#004faf">Main Classes</font></a>
|
||
|
|
| <a href="annotated.html">
|
||
|
|
<font color="#004faf">Annotated</font></a>
|
||
|
|
| <a href="groups.html">
|
||
|
|
<font color="#004faf">Grouped Classes</font></a>
|
||
|
|
| <a href="functions.html">
|
||
|
|
<font color="#004faf">Functions</font></a>
|
||
|
|
</td>
|
||
|
|
<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>Qt Plugins HOWTO</h1>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<p> 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.
|
||
|
|
<a href="#footnote1"><sup>(1)</sup></a><a name="footnote-call1"></a>
|
||
|
|
<p> Writing a plugin is achieved by subclassing the appropriate plugin
|
||
|
|
base clase, implementing a few functions, and adding a macro.
|
||
|
|
<p> There are five plugin base classes. Derived plugins are stored
|
||
|
|
by default in the standard plugin directory.
|
||
|
|
<p> <center><table cellpadding="4" cellspacing="2" border="0">
|
||
|
|
<tr bgcolor="#a2c511">
|
||
|
|
<th valign="top">Base Class
|
||
|
|
<th valign="top">Default Path
|
||
|
|
<tr bgcolor="#f0f0f0">
|
||
|
|
<td valign="top"><a href="qimageformatplugin.html">QImageFormatPlugin</a>
|
||
|
|
<td valign="top"><tt>pluginsbase/imageformats</tt> <sup>*</sup>
|
||
|
|
<tr bgcolor="#d0d0d0">
|
||
|
|
<td valign="top"><a href="qsqldriverplugin.html">QSqlDriverPlugin</a>
|
||
|
|
<td valign="top"><tt>pluginsbase/sqldrivers</tt> <sup>*</sup>
|
||
|
|
<tr bgcolor="#f0f0f0">
|
||
|
|
<td valign="top"><a href="qstyleplugin.html">QStylePlugin</a>
|
||
|
|
<td valign="top"><tt>pluginsbase/styles</tt> <sup>*</sup>
|
||
|
|
<tr bgcolor="#d0d0d0">
|
||
|
|
<td valign="top"><a href="qtextcodecplugin.html">QTextCodecPlugin</a>
|
||
|
|
<td valign="top"><tt>pluginsbase/codecs</tt> <sup>*</sup>
|
||
|
|
<tr bgcolor="#f0f0f0">
|
||
|
|
<td valign="top"><a href="qwidgetplugin.html">QWidgetPlugin</a>
|
||
|
|
<td valign="top"><tt>pluginsbase/designer</tt> <sup>*</sup>
|
||
|
|
</table></center>
|
||
|
|
<p> But where is the <tt>pluginsbase</tt> directory? When the application is
|
||
|
|
run, Qt will first treat the application's executable directory as the
|
||
|
|
<tt>pluginsbase</tt>. For example if the application is in <tt>C:\Program Files\MyApp</tt> and has a style plugin, Qt will look in <tt>C:\Program Files\MyApp\styles</tt>. (See <a href="qapplication.html#applicationDirPath">QApplication::applicationDirPath</a>() for
|
||
|
|
how to find out where the application's executable is.) Qt will also
|
||
|
|
look in the directory given by <tt>qInstallPathPlugins()</tt>. If you want
|
||
|
|
Qt to look in additional places you can add as many paths as you need
|
||
|
|
with calls to <a href="qapplication.html#addLibraryPath">QApplication::addLibraryPath</a>(). And if you want to
|
||
|
|
set your own path or paths you can use
|
||
|
|
<a href="qapplication.html#setLibraryPaths">QApplication::setLibraryPaths</a>().
|
||
|
|
<p> Suppose that you have a new style class called 'MyStyle' that you want
|
||
|
|
to make available as a plugin. The required code is straightforward:
|
||
|
|
<pre>
|
||
|
|
class MyStylePlugin : public <a href="qstyleplugin.html">QStylePlugin</a>
|
||
|
|
{
|
||
|
|
public:
|
||
|
|
MyStylePlugin() {}
|
||
|
|
~MyStylePlugin() {}
|
||
|
|
|
||
|
|
<a href="qstringlist.html">QStringList</a> keys() const {
|
||
|
|
return QStringList() << "mystyle";
|
||
|
|
}
|
||
|
|
|
||
|
|
<a href="qstyle.html">QStyle</a>* create( const <a href="qstring.html">QString</a>& key ) {
|
||
|
|
if ( key == "mystyle" )
|
||
|
|
return new MyStyle;
|
||
|
|
return 0;
|
||
|
|
}
|
||
|
|
};
|
||
|
|
|
||
|
|
Q_EXPORT_PLUGIN( MyStylePlugin )
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> (Note that <a href="qstylefactory.html">QStyleFactory</a> is case-insensitive, and the lower case
|
||
|
|
version of the key is used; other factories, e.g. <a href="qwidgetfactory.html">QWidgetFactory</a>, are
|
||
|
|
case sensitive.)
|
||
|
|
<p> 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 <a href="qstyleplugin.html">QStylePlugin</a>, this second
|
||
|
|
function is called create().
|
||
|
|
<p> 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.
|
||
|
|
<p> For database drivers, image formats, custom widgets and text codecs,
|
||
|
|
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:
|
||
|
|
<pre>
|
||
|
|
QApplication::<a href="qapplication.html#setStyle">setStyle</a>( QStyleFactory::<a href="qstylefactory.html#create">create</a>( "MyStyle" ) );
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> Some plugin classes require additional functions to be implemented.
|
||
|
|
See the <a href="designer-manual.html">Qt Designer manual's</a>,
|
||
|
|
'Creating Custom Widgets' section in the 'Creating Custom Widgets'
|
||
|
|
chapter, for a complete example of a <a href="qwidgetplugin.html">QWidgetPlugin</a>, which implements
|
||
|
|
extra functions to integrate the plugin into <em>Qt Designer</em>. The
|
||
|
|
<a href="qwidgetfactory.html">QWidgetFactory</a> class provides additional information on
|
||
|
|
QWidgetPlugins.
|
||
|
|
<p> See the class documentation for details of the virtual functions that
|
||
|
|
must be reimplemented for each type of plugin.
|
||
|
|
<p> 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.
|
||
|
|
<p> The default directory for plugins is <tt>QTDIR/plugins</tt><sup>*</sup>,
|
||
|
|
with each type of plugin in a subdirectory for that type, e.g. <tt>styles</tt>. 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 <a href="qsettings.html">QSettings</a>, for the application to read when it runs. The
|
||
|
|
application can then call <a href="qapplication.html#addLibraryPath">QApplication::addLibraryPath</a>() with this
|
||
|
|
path and your plugins will be available to the application. Note that
|
||
|
|
the final part of the path, i.e. <tt>styles</tt>, <tt>widgets</tt>, etc., cannot
|
||
|
|
be changed.
|
||
|
|
<p> 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 <tt>DLL</tt> (or
|
||
|
|
<tt>so</tt> 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. <tt>appdir/plugins/designer</tt>, and place the plugin in that directory.
|
||
|
|
<p> For <a href="designer-manual.html">Qt Designer</a>, you may need to
|
||
|
|
call QApplication::addLibraryPath("QTDIR/plugins/designer") to load
|
||
|
|
your <a href="designer-manual.html">Qt Designer</a> plugins.
|
||
|
|
<p> <sup>*</sup><small> All references to <tt>QTDIR</tt> refer to the path
|
||
|
|
where Qt was installed. </small>
|
||
|
|
<p> <h2> Loading and Verifying Plugins
|
||
|
|
</h2>
|
||
|
|
<a name="1"></a><p> 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.
|
||
|
|
<ul>
|
||
|
|
<li> 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.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> 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.
|
||
|
|
<p> <li> Plugins linked against a Qt library <em>with</em> thread support can only be
|
||
|
|
loaded by libraries that are built <em>with</em> thread support.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> The threaded and non-threaded Qt libraries have different names.
|
||
|
|
A library <em>with</em> thread support that loads a plugin linked against a
|
||
|
|
Qt library <em>without</em> 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.
|
||
|
|
<p> <li> Plugins linked against a Qt library <em>without</em> thread support can only
|
||
|
|
be loaded by libraries that are built <em>without</em> thread support.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> See the Rationale above.
|
||
|
|
<p> <li> Starting with Qt 3.0.5, both the Qt library and all plugins are
|
||
|
|
built using a <em>build key</em>. 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.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> See the Rationale for the build key below.
|
||
|
|
</ul>
|
||
|
|
<p> <h2> The Build Key
|
||
|
|
</h2>
|
||
|
|
<a name="2"></a><p> The build key contains the following information:
|
||
|
|
<ul>
|
||
|
|
<li> Architecture, operating system and compiler.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> 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.
|
||
|
|
<p> <li> Configuration of the Qt library. The configuration is a list
|
||
|
|
of the missing features that affect the available API in the
|
||
|
|
library.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> 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.
|
||
|
|
<p> <em>Note</em>: 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 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.
|
||
|
|
<p> <li> Optionally, an extra string may be specified on the configure
|
||
|
|
script command line.
|
||
|
|
<p> <em>Rationale</em>:
|
||
|
|
<p> 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.
|
||
|
|
</ul>
|
||
|
|
<p> <h2> Plugins and Threaded Applications
|
||
|
|
</h2>
|
||
|
|
<a name="3"></a><p> 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 <a href="designer-manual.html">Qt
|
||
|
|
Designer</a> with that library. Your <tt>.pro</tt> file for your plugin
|
||
|
|
must include the line:
|
||
|
|
<pre>
|
||
|
|
CONFIG += thread
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p> <b>Warning:</b> 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.
|
||
|
|
<p>
|
||
|
|
<hr>
|
||
|
|
<ol> <li><a name="footnote1"></a>
|
||
|
|
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><em>no</em></b> plugins compiled with Qt 3.0.4 and
|
||
|
|
earlier will work with Qt 3.0.5 and later: they must be recompiled.
|
||
|
|
<a href="#footnote-call1">Back...</a></ol>
|
||
|
|
</hr>
|
||
|
|
<!-- eof -->
|
||
|
|
<p><address><hr><div align=center>
|
||
|
|
<table width=100% cellspacing=0 border=0><tr>
|
||
|
|
<td>Copyright © 2007
|
||
|
|
<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
||
|
|
<td align=right><div align=right>Qt 3.3.8</div>
|
||
|
|
</table></div></address></body>
|
||
|
|
</html>
|