<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- /tmp/qt-3.0-reggie-28534/qt-x11-free-3.0.2/doc/plugins-howto.doc:1 -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Qt Plugins HOWTO</title>
<style type="text/css"><!--
h3.fn,span.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.
<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, and their plugins are stored in
the standard plugin directory.
<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>$QTDIR/plugins/imageformats</tt>
<tr bgcolor="#d0d0d0">
<td valign="top"><a href="qsqldriverplugin.html">QSqlDriverPlugin</a>
<td valign="top"><tt>$QTDIR/plugins/sqldrivers</tt>
<tr bgcolor="#f0f0f0">
<td valign="top"><a href="qstyleplugin.html">QStylePlugin</a>
<td valign="top"><tt>$QTDIR/plugins/styles</tt>
<tr bgcolor="#d0d0d0">
<td valign="top"><a href="qtextcodecplugin.html">QTextCodecPlugin</a>
<td valign="top"><tt>$QTDIR/plugins/codecs</tt>
<tr bgcolor="#f0f0f0">
<td valign="top"><a href="qwidgetplugin.html">QWidgetPlugin</a>
<td valign="top"><tt>$QTDIR/plugins/widgets</tt>
</table></center>
<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> 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>.
<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>, 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> <h2> Plugins and Threaded Applications
</h2>
<a name="1"></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 use 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 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>
<!-- eof -->
<p><address><hr><div align=center>
<table width=100% cellspacing=0 border=0><tr>
<td>Copyright © 2001
<a href="http://www.trolltech.com">Trolltech</a><td><a href="http://www.trolltech.com/trademarks.html">Trademarks</a>
<td align=right><div align=right>Qt version 3.0.2</div>
</table></div></address></body>
</html>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
112b0974ad288f6cd55bf971ee6026a9
>
files
>
824
