| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|---|
| 2 | <!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/plugins-howto.doc:36 -->
|
|---|
| 3 | <html>
|
|---|
| 4 | <head>
|
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
|---|
| 6 | <title>Qt Plugins HOWTO</title>
|
|---|
| 7 | <style type="text/css"><!--
|
|---|
| 8 | fn { margin-left: 1cm; text-indent: -1cm; }
|
|---|
| 9 | a:link { color: #004faf; text-decoration: none }
|
|---|
| 10 | a:visited { color: #672967; text-decoration: none }
|
|---|
| 11 | body { background: #ffffff; color: black; }
|
|---|
| 12 | --></style>
|
|---|
| 13 | </head>
|
|---|
| 14 | <body>
|
|---|
| 15 |
|
|---|
| 16 | <table border="0" cellpadding="0" cellspacing="0" width="100%">
|
|---|
| 17 | <tr bgcolor="#E5E5E5">
|
|---|
| 18 | <td valign=center>
|
|---|
| 19 | <a href="index.html">
|
|---|
| 20 | <font color="#004faf">Home</font></a>
|
|---|
| 21 | | <a href="classes.html">
|
|---|
| 22 | <font color="#004faf">All Classes</font></a>
|
|---|
| 23 | | <a href="mainclasses.html">
|
|---|
| 24 | <font color="#004faf">Main Classes</font></a>
|
|---|
| 25 | | <a href="annotated.html">
|
|---|
| 26 | <font color="#004faf">Annotated</font></a>
|
|---|
| 27 | | <a href="groups.html">
|
|---|
| 28 | <font color="#004faf">Grouped Classes</font></a>
|
|---|
| 29 | | <a href="functions.html">
|
|---|
| 30 | <font color="#004faf">Functions</font></a>
|
|---|
| 31 | </td>
|
|---|
| 32 | <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>
|
|---|
| 33 |
|
|---|
| 34 |
|
|---|
| 35 |
|
|---|
| 36 | <p> Qt provides a simple plugin interface which makes it easy to create
|
|---|
| 37 | custom database drivers, image formats, text codecs, styles and
|
|---|
| 38 | widgets as stand-alone components.
|
|---|
| 39 | <a href="#footnote1"><sup>(1)</sup></a><a name="footnote-call1"></a>
|
|---|
| 40 | <p> Writing a plugin is achieved by subclassing the appropriate plugin
|
|---|
| 41 | base clase, implementing a few functions, and adding a macro.
|
|---|
| 42 | <p> There are five plugin base classes. Derived plugins are stored
|
|---|
| 43 | by default in the standard plugin directory.
|
|---|
| 44 | <p> <center><table cellpadding="4" cellspacing="2" border="0">
|
|---|
| 45 | <tr bgcolor="#a2c511">
|
|---|
| 46 | <th valign="top">Base Class
|
|---|
| 47 | <th valign="top">Default Path
|
|---|
| 48 | <tr bgcolor="#f0f0f0">
|
|---|
| 49 | <td valign="top"><a href="qimageformatplugin.html">QImageFormatPlugin</a>
|
|---|
| 50 | <td valign="top"><tt>pluginsbase/imageformats</tt> <sup>*</sup>
|
|---|
| 51 | <tr bgcolor="#d0d0d0">
|
|---|
| 52 | <td valign="top"><a href="qsqldriverplugin.html">QSqlDriverPlugin</a>
|
|---|
| 53 | <td valign="top"><tt>pluginsbase/sqldrivers</tt> <sup>*</sup>
|
|---|
| 54 | <tr bgcolor="#f0f0f0">
|
|---|
| 55 | <td valign="top"><a href="qstyleplugin.html">QStylePlugin</a>
|
|---|
| 56 | <td valign="top"><tt>pluginsbase/styles</tt> <sup>*</sup>
|
|---|
| 57 | <tr bgcolor="#d0d0d0">
|
|---|
| 58 | <td valign="top"><a href="qtextcodecplugin.html">QTextCodecPlugin</a>
|
|---|
| 59 | <td valign="top"><tt>pluginsbase/codecs</tt> <sup>*</sup>
|
|---|
| 60 | <tr bgcolor="#f0f0f0">
|
|---|
| 61 | <td valign="top"><a href="qwidgetplugin.html">QWidgetPlugin</a>
|
|---|
| 62 | <td valign="top"><tt>pluginsbase/designer</tt> <sup>*</sup>
|
|---|
| 63 | </table></center>
|
|---|
| 64 | <p> But where is the <tt>pluginsbase</tt> directory? When the application is
|
|---|
| 65 | run, Qt will first treat the application's executable directory as the
|
|---|
| 66 | <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
|
|---|
| 67 | how to find out where the application's executable is.) Qt will also
|
|---|
| 68 | look in the directory given by <tt>qInstallPathPlugins()</tt>. If you want
|
|---|
| 69 | Qt to look in additional places you can add as many paths as you need
|
|---|
| 70 | with calls to <a href="qapplication.html#addLibraryPath">QApplication::addLibraryPath</a>(). And if you want to
|
|---|
| 71 | set your own path or paths you can use
|
|---|
| 72 | <a href="qapplication.html#setLibraryPaths">QApplication::setLibraryPaths</a>().
|
|---|
| 73 | <p> Suppose that you have a new style class called 'MyStyle' that you want
|
|---|
| 74 | to make available as a plugin. The required code is straightforward:
|
|---|
| 75 | <pre>
|
|---|
| 76 | class MyStylePlugin : public <a href="qstyleplugin.html">QStylePlugin</a>
|
|---|
| 77 | {
|
|---|
| 78 | public:
|
|---|
| 79 | MyStylePlugin() {}
|
|---|
| 80 | ~MyStylePlugin() {}
|
|---|
| 81 |
|
|---|
| 82 | <a href="qstringlist.html">QStringList</a> keys() const {
|
|---|
| 83 | return QStringList() << "mystyle";
|
|---|
| 84 | }
|
|---|
| 85 |
|
|---|
| 86 | <a href="qstyle.html">QStyle</a>* create( const <a href="qstring.html">QString</a>& key ) {
|
|---|
| 87 | if ( key == "mystyle" )
|
|---|
| 88 | return new MyStyle;
|
|---|
| 89 | return 0;
|
|---|
| 90 | }
|
|---|
| 91 | };
|
|---|
| 92 |
|
|---|
| 93 | Q_EXPORT_PLUGIN( MyStylePlugin )
|
|---|
| 94 | </pre>
|
|---|
| 95 |
|
|---|
| 96 | <p> (Note that <a href="qstylefactory.html">QStyleFactory</a> is case-insensitive, and the lower case
|
|---|
| 97 | version of the key is used; other factories, e.g. <a href="qwidgetfactory.html">QWidgetFactory</a>, are
|
|---|
| 98 | case sensitive.)
|
|---|
| 99 | <p> The constructor and destructor do not need to do anything, so are left
|
|---|
| 100 | empty. There are only two virtual functions that must be implemented.
|
|---|
| 101 | The first is keys() which returns a string list of the classes
|
|---|
| 102 | implemented in the plugin. (We've just implemented one class in the
|
|---|
| 103 | example above.) The second is a function that returns an object of the
|
|---|
| 104 | required class (or 0 if the plugin is asked to create an object of a
|
|---|
| 105 | class that it doesn't implement). For <a href="qstyleplugin.html">QStylePlugin</a>, this second
|
|---|
| 106 | function is called create().
|
|---|
| 107 | <p> It is possible to implement any number of plugin subclasses in a
|
|---|
| 108 | single plugin, providing they are all derived from the same base
|
|---|
| 109 | class, e.g. QStylePlugin.
|
|---|
| 110 | <p> For database drivers, image formats, custom widgets and text codecs,
|
|---|
| 111 | no explicit object creation is required. Qt will find and create them
|
|---|
| 112 | as required. Styles are an exception, since you might want to set a
|
|---|
| 113 | style explicitly in code. To apply a style, use code like this:
|
|---|
| 114 | <pre>
|
|---|
| 115 | QApplication::<a href="qapplication.html#setStyle">setStyle</a>( QStyleFactory::<a href="qstylefactory.html#create">create</a>( "MyStyle" ) );
|
|---|
| 116 | </pre>
|
|---|
| 117 |
|
|---|
| 118 | <p> Some plugin classes require additional functions to be implemented.
|
|---|
| 119 | See the <a href="designer-manual.html">Qt Designer manual's</a>,
|
|---|
| 120 | 'Creating Custom Widgets' section in the 'Creating Custom Widgets'
|
|---|
| 121 | chapter, for a complete example of a <a href="qwidgetplugin.html">QWidgetPlugin</a>, which implements
|
|---|
| 122 | extra functions to integrate the plugin into <em>Qt Designer</em>. The
|
|---|
| 123 | <a href="qwidgetfactory.html">QWidgetFactory</a> class provides additional information on
|
|---|
| 124 | QWidgetPlugins.
|
|---|
| 125 | <p> See the class documentation for details of the virtual functions that
|
|---|
| 126 | must be reimplemented for each type of plugin.
|
|---|
| 127 | <p> Qt applications automatically know which plugins are available,
|
|---|
| 128 | because plugins are stored in the standard plugin subdirectories.
|
|---|
| 129 | Because of this applications don't require any code to find and load
|
|---|
| 130 | plugins, since Qt handles them automatically.
|
|---|
| 131 | <p> The default directory for plugins is <tt>QTDIR/plugins</tt><sup>*</sup>,
|
|---|
| 132 | 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
|
|---|
| 133 | want to use the standard plugins path, have your installation process
|
|---|
| 134 | determine the path you want to use for the plugins, and save the path,
|
|---|
| 135 | e.g. using <a href="qsettings.html">QSettings</a>, for the application to read when it runs. The
|
|---|
| 136 | application can then call <a href="qapplication.html#addLibraryPath">QApplication::addLibraryPath</a>() with this
|
|---|
| 137 | path and your plugins will be available to the application. Note that
|
|---|
| 138 | the final part of the path, i.e. <tt>styles</tt>, <tt>widgets</tt>, etc., cannot
|
|---|
| 139 | be changed.
|
|---|
| 140 | <p> The normal way to include a plugin with an application is either to
|
|---|
| 141 | compile it in with the application, or to compile it into a <tt>DLL</tt> (or
|
|---|
| 142 | <tt>so</tt> or other platform specific library type) and use it like any
|
|---|
| 143 | other library. If you want the plugin to be loadable then one approach
|
|---|
| 144 | is to create a subdirectory under the application, e.g. <tt>appdir/plugins/designer</tt>, and place the plugin in that directory.
|
|---|
| 145 | <p> For <a href="designer-manual.html">Qt Designer</a>, you may need to
|
|---|
| 146 | call QApplication::addLibraryPath("QTDIR/plugins/designer") to load
|
|---|
| 147 | your <a href="designer-manual.html">Qt Designer</a> plugins.
|
|---|
| 148 | <p> <sup>*</sup><small> All references to <tt>QTDIR</tt> refer to the path
|
|---|
| 149 | where Qt was installed. </small>
|
|---|
| 150 | <p> <h2> Loading and Verifying Plugins
|
|---|
| 151 | </h2>
|
|---|
| 152 | <a name="1"></a><p> When loading plugins, the Qt library does some sanity checking to
|
|---|
| 153 | determine whether or not the plugin can be loaded and used. This
|
|---|
| 154 | provides the ability to have multiple versions and configurations of
|
|---|
| 155 | the Qt library installed side by side.
|
|---|
| 156 | <ul>
|
|---|
| 157 | <li> Plugins linked with a Qt library that has a higher major and/or
|
|---|
| 158 | minor version number will not be loaded by a library with a lower
|
|---|
| 159 | major and/or minor version number.
|
|---|
| 160 | <p> <em>Rationale</em>:
|
|---|
| 161 | <p> A plugin linked against a newer Qt library may use new
|
|---|
| 162 | features that are not available in older versions. Trolltech
|
|---|
| 163 | has a policy of adding new features and APIs only between minor
|
|---|
| 164 | releases, which is why this test only looks at the major and minor
|
|---|
| 165 | version numbers, and not at the patchlevel version number.
|
|---|
| 166 | <p> <li> Plugins linked against a Qt library <em>with</em> thread support can only be
|
|---|
| 167 | loaded by libraries that are built <em>with</em> thread support.
|
|---|
| 168 | <p> <em>Rationale</em>:
|
|---|
| 169 | <p> The threaded and non-threaded Qt libraries have different names.
|
|---|
| 170 | A library <em>with</em> thread support that loads a plugin linked against a
|
|---|
| 171 | Qt library <em>without</em> thread support will cause two versions of the same
|
|---|
| 172 | library to be in memory at the same time. On UNIX systems, this
|
|---|
| 173 | causes the non-threaded Qt library to be loaded. When this
|
|---|
| 174 | happens, the constructors for all static objects in the Qt library
|
|---|
| 175 | will be called a second time, but they will operate on the objects
|
|---|
| 176 | already in memory. There is no way to work around this, as this is
|
|---|
| 177 | a feature of the object binary format: the static symbols already
|
|---|
| 178 | defined by the threaded Qt library cannot be replaced or copied
|
|---|
| 179 | when the non-threaded Qt library is loaded.
|
|---|
| 180 | <p> <li> Plugins linked against a Qt library <em>without</em> thread support can only
|
|---|
| 181 | be loaded by libraries that are built <em>without</em> thread support.
|
|---|
| 182 | <p> <em>Rationale</em>:
|
|---|
| 183 | <p> See the Rationale above.
|
|---|
| 184 | <p> <li> Starting with Qt 3.0.5, both the Qt library and all plugins are
|
|---|
| 185 | built using a <em>build key</em>. The build key in the Qt library is
|
|---|
| 186 | examined against the build key in the plugin, and if they match,
|
|---|
| 187 | the plugin is loaded. If the build keys do not match, then the Qt
|
|---|
| 188 | library refuses to load the plugin.
|
|---|
| 189 | <p> <em>Rationale</em>:
|
|---|
| 190 | <p> See the Rationale for the build key below.
|
|---|
| 191 | </ul>
|
|---|
| 192 | <p> <h2> The Build Key
|
|---|
| 193 | </h2>
|
|---|
| 194 | <a name="2"></a><p> The build key contains the following information:
|
|---|
| 195 | <ul>
|
|---|
| 196 | <li> Architecture, operating system and compiler.
|
|---|
| 197 | <p> <em>Rationale</em>:
|
|---|
| 198 | <p> In cases where different versions of the same compiler do not
|
|---|
| 199 | produce binary compatible code, the version of the compiler is
|
|---|
| 200 | also present in the build key.
|
|---|
| 201 | <p> <li> Configuration of the Qt library. The configuration is a list
|
|---|
| 202 | of the missing features that affect the available API in the
|
|---|
| 203 | library.
|
|---|
| 204 | <p> <em>Rationale</em>:
|
|---|
| 205 | <p> Two different configurations of the same version of
|
|---|
| 206 | the Qt library are not binary compatible. The Qt library that
|
|---|
| 207 | loads the plugin uses the list of (missing) features to
|
|---|
| 208 | determine if the plugin is binary compatible.
|
|---|
| 209 | <p> <em>Note</em>: There are cases where a plugin can use features that are
|
|---|
| 210 | available in two different configurations. However, the
|
|---|
| 211 | developer writing plugins would need to know which features are
|
|---|
| 212 | in use, both in their plugin and internally by the utility
|
|---|
| 213 | classes in Qt. The Qt library would require complex feature
|
|---|
| 214 | and dependency queries and verification when loading plugins.
|
|---|
| 215 | Requiring this would place an unnecessary burden on the developer, and
|
|---|
| 216 | increase the overhead of loading a plugin. To reduce both
|
|---|
| 217 | development time and application runtime costs, a simple string
|
|---|
| 218 | comparision of the build keys is used.
|
|---|
| 219 | <p> <li> Optionally, an extra string may be specified on the configure
|
|---|
| 220 | script command line.
|
|---|
| 221 | <p> <em>Rationale</em>:
|
|---|
| 222 | <p> When distributing binaries of the Qt library with an
|
|---|
| 223 | application, this provides a way for developers to write
|
|---|
| 224 | plugins that can only be loaded by the library with which the
|
|---|
| 225 | plugins were linked.
|
|---|
| 226 | </ul>
|
|---|
| 227 | <p> <h2> Plugins and Threaded Applications
|
|---|
| 228 | </h2>
|
|---|
| 229 | <a name="3"></a><p> If you want to build a plugin which you want to use with a threaded Qt
|
|---|
| 230 | library (whether or not the plugin itself uses threads) you must use a
|
|---|
| 231 | threaded environment. Specifically, you must link the plugin with a
|
|---|
| 232 | threaded Qt library, and you must build <a href="designer-manual.html">Qt
|
|---|
| 233 | Designer</a> with that library. Your <tt>.pro</tt> file for your plugin
|
|---|
| 234 | must include the line:
|
|---|
| 235 | <pre>
|
|---|
| 236 | CONFIG += thread
|
|---|
| 237 | </pre>
|
|---|
| 238 |
|
|---|
| 239 | <p> <b>Warning:</b> Do not mix the normal Qt library and the threaded Qt library in
|
|---|
| 240 | an application. If your application uses the threaded Qt library, you
|
|---|
| 241 | should not link your plugin with the normal Qt library. Nor should you
|
|---|
| 242 | dynamically load the normal Qt library or dynamically load another library,
|
|---|
| 243 | e.g. a plugin, that depends on the normal Qt library. On some systems,
|
|---|
| 244 | mixing threaded and non-threaded libraries or plugins will corrupt the
|
|---|
| 245 | static data used in the Qt library.
|
|---|
| 246 | <p>
|
|---|
| 247 | <hr>
|
|---|
| 248 | <ol> <li><a name="footnote1"></a>
|
|---|
| 249 | Qt 3.0.5 introduces changes into some aspects of plugins, in
|
|---|
| 250 | particular regarding loading, path handling and library versions. As
|
|---|
| 251 | a result of this change, <b><em>no</em></b> plugins compiled with Qt 3.0.4 and
|
|---|
| 252 | earlier will work with Qt 3.0.5 and later: they must be recompiled.
|
|---|
| 253 | <a href="#footnote-call1">Back...</a></ol>
|
|---|
| 254 | </hr>
|
|---|
| 255 | <!-- eof -->
|
|---|
| 256 | <p><address><hr><div align=center>
|
|---|
| 257 | <table width=100% cellspacing=0 border=0><tr>
|
|---|
| 258 | <td>Copyright © 2007
|
|---|
| 259 | <a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
|
|---|
| 260 | <td align=right><div align=right>Qt 3.3.8</div>
|
|---|
| 261 | </table></div></address></body>
|
|---|
| 262 | </html>
|
|---|
