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
<!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>TQt 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>TQt Plugins HOWTO</h1>
|
|
|
|
|
|
|
|
<p> TQt 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="tqimageformatplugin.html">TQImageFormatPlugin</a>
|
|
<td valign="top"><tt>pluginsbase/imageformats</tt> <sup>*</sup>
|
|
<tr bgcolor="#d0d0d0">
|
|
<td valign="top"><a href="tqsqldriverplugin.html">TQSqlDriverPlugin</a>
|
|
<td valign="top"><tt>pluginsbase/sqldrivers</tt> <sup>*</sup>
|
|
<tr bgcolor="#f0f0f0">
|
|
<td valign="top"><a href="tqstyleplugin.html">TQStylePlugin</a>
|
|
<td valign="top"><tt>pluginsbase/styles</tt> <sup>*</sup>
|
|
<tr bgcolor="#d0d0d0">
|
|
<td valign="top"><a href="tqtextcodecplugin.html">TQTextCodecPlugin</a>
|
|
<td valign="top"><tt>pluginsbase/codecs</tt> <sup>*</sup>
|
|
<tr bgcolor="#f0f0f0">
|
|
<td valign="top"><a href="tqwidgetplugin.html">TQWidgetPlugin</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, TQt 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, TQt will look in <tt>C:\Program Files\MyApp\styles</tt>. (See <a href="ntqapplication.html#applicationDirPath">TQApplication::applicationDirPath</a>() for
|
|
how to find out where the application's executable is.) TQt will also
|
|
look in the directory given by <tt>tqInstallPathPlugins()</tt>. If you want
|
|
TQt to look in additional places you can add as many paths as you need
|
|
with calls to <a href="ntqapplication.html#addLibraryPath">TQApplication::addLibraryPath</a>(). And if you want to
|
|
set your own path or paths you can use
|
|
<a href="ntqapplication.html#setLibraryPaths">TQApplication::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="tqstyleplugin.html">TQStylePlugin</a>
|
|
{
|
|
public:
|
|
MyStylePlugin() {}
|
|
~MyStylePlugin() {}
|
|
|
|
<a href="tqstringlist.html">TQStringList</a> keys() const {
|
|
return TQStringList() << "mystyle";
|
|
}
|
|
|
|
<a href="tqstyle.html">TQStyle</a>* create( const <a href="tqstring.html">TQString</a>& key ) {
|
|
if ( key == "mystyle" )
|
|
return new MyStyle;
|
|
return 0;
|
|
}
|
|
};
|
|
|
|
TQ_EXPORT_PLUGIN( MyStylePlugin )
|
|
</pre>
|
|
|
|
<p> (Note that <a href="tqstylefactory.html">TQStyleFactory</a> is case-insensitive, and the lower case
|
|
version of the key is used; other factories, e.g. <a href="tqwidgetfactory.html">TQWidgetFactory</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="tqstyleplugin.html">TQStylePlugin</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. TQStylePlugin.
|
|
<p> 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:
|
|
<pre>
|
|
TQApplication::<a href="ntqapplication.html#setStyle">setStyle</a>( TQStyleFactory::<a href="tqstylefactory.html#create">create</a>( "MyStyle" ) );
|
|
</pre>
|
|
|
|
<p> Some plugin classes require additional functions to be implemented.
|
|
See the <a href="designer-manual.html">TQt Designer manual's</a>,
|
|
'Creating Custom Widgets' section in the 'Creating Custom Widgets'
|
|
chapter, for a complete example of a <a href="tqwidgetplugin.html">TQWidgetPlugin</a>, which implements
|
|
extra functions to integrate the plugin into <em>TQt Designer</em>. The
|
|
<a href="tqwidgetfactory.html">TQWidgetFactory</a> class provides additional information on
|
|
TQWidgetPlugins.
|
|
<p> See the class documentation for details of the virtual functions that
|
|
must be reimplemented for each type of plugin.
|
|
<p> TQt 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.
|
|
<p> The default directory for plugins is <tt>TQTDIR/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="ntqsettings.html">TQSettings</a>, for the application to read when it runs. The
|
|
application can then call <a href="ntqapplication.html#addLibraryPath">TQApplication::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">TQt Designer</a>, you may need to
|
|
call TQApplication::addLibraryPath("TQTDIR/plugins/designer") to load
|
|
your <a href="designer-manual.html">TQt Designer</a> plugins.
|
|
<p> <sup>*</sup><small> All references to <tt>TQTDIR</tt> refer to the path
|
|
where TQt was installed. </small>
|
|
<p> <h2> Loading and Verifying Plugins
|
|
</h2>
|
|
<a name="1"></a><p> 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.
|
|
<ul>
|
|
<li> 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.
|
|
<p> <em>Rationale</em>:
|
|
<p> 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.
|
|
<p> <li> Plugins linked against a TQt 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 TQt libraries have different names.
|
|
A library <em>with</em> thread support that loads a plugin linked against a
|
|
TQt 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 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.
|
|
<p> <li> Plugins linked against a TQt 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 TQt 3.0.5, both the TQt library and all plugins are
|
|
built using a <em>build key</em>. 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 TQt
|
|
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 TQt 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 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.
|
|
<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 TQt. 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.
|
|
<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 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.
|
|
</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 TQt
|
|
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 <a href="designer-manual.html">TQt
|
|
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 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.
|
|
<p>
|
|
<hr>
|
|
<ol> <li><a name="footnote1"></a>
|
|
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><em>no</em></b> plugins compiled with TQt 3.0.4 and
|
|
earlier will work with TQt 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>TQt 3.3.8</div>
|
|
</table></div></address></body>
|
|
</html>
|