/usr/share/qt3/doc/html/plugins-howto.html

<!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&nbsp;Classes</font></a>
 | <a href="mainclasses.html">
<font color="#004faf">Main&nbsp;Classes</font></a>
 | <a href="annotated.html">
<font color="#004faf">Annotated</font></a>
 | <a href="groups.html">
<font color="#004faf">Grouped&nbsp;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:&#92;Program Files&#92;MyApp</tt> and has a style plugin, Qt will look in <tt>C:&#92;Program Files&#92;MyApp&#92;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() &lt;&lt; "mystyle"; 
        }

        <a href="qstyle.html">QStyle</a>* create( const <a href="qstring.html">QString</a>&amp; 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 &copy; 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>
qt3-doc 3:3.3.8-b-8ubuntu3 / usr / share / qt3 / doc / html / plugins-howto.html
