diff options
Diffstat (limited to 'doc/html/plugins-howto.html')
| -rw-r--r-- | doc/html/plugins-howto.html | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/doc/html/plugins-howto.html b/doc/html/plugins-howto.html new file mode 100644 index 0000000..b9a38d0 --- /dev/null +++ b/doc/html/plugins-howto.html @@ -0,0 +1,262 @@ +<!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> |