From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/plugins-howto.html | 262 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 262 insertions(+) create mode 100644 doc/html/plugins-howto.html (limited to 'doc/html/plugins-howto.html') 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 @@ + + + + + +Qt Plugins HOWTO + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

Qt Plugins HOWTO

+ + + +

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. +(1) +

Writing a plugin is achieved by subclassing the appropriate plugin +base clase, implementing a few functions, and adding a macro. +

There are five plugin base classes. Derived plugins are stored +by default in the standard plugin directory. +

+ + + + + + +
Base Class +Default Path +
QImageFormatPlugin +pluginsbase/imageformats * +
QSqlDriverPlugin +pluginsbase/sqldrivers * +
QStylePlugin +pluginsbase/styles * +
QTextCodecPlugin +pluginsbase/codecs * +
QWidgetPlugin +pluginsbase/designer * +
+

But where is the pluginsbase directory? When the application is +run, Qt will first treat the application's executable directory as the +pluginsbase. For example if the application is in C:\Program Files\MyApp and has a style plugin, Qt will look in C:\Program Files\MyApp\styles. (See QApplication::applicationDirPath() for +how to find out where the application's executable is.) Qt will also +look in the directory given by qInstallPathPlugins(). If you want +Qt to look in additional places you can add as many paths as you need +with calls to QApplication::addLibraryPath(). And if you want to +set your own path or paths you can use +QApplication::setLibraryPaths(). +

Suppose that you have a new style class called 'MyStyle' that you want +to make available as a plugin. The required code is straightforward: +

+    class MyStylePlugin : public QStylePlugin
+    {
+    public:
+        MyStylePlugin() {}
+        ~MyStylePlugin() {}
+
+        QStringList keys() const { 
+            return QStringList() << "mystyle"; 
+        }
+
+        QStyle* create( const QString& key ) { 
+            if ( key == "mystyle" ) 
+                return new MyStyle;
+            return 0;
+        }
+    };
+
+    Q_EXPORT_PLUGIN( MyStylePlugin )
+
+ +

(Note that QStyleFactory is case-insensitive, and the lower case +version of the key is used; other factories, e.g. QWidgetFactory, are +case sensitive.) +

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 QStylePlugin, this second +function is called create(). +

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. +

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: +

+    QApplication::setStyle( QStyleFactory::create( "MyStyle" ) );
+
+ +

Some plugin classes require additional functions to be implemented. +See the Qt Designer manual's, +'Creating Custom Widgets' section in the 'Creating Custom Widgets' +chapter, for a complete example of a QWidgetPlugin, which implements +extra functions to integrate the plugin into Qt Designer. The +QWidgetFactory class provides additional information on +QWidgetPlugins. +

See the class documentation for details of the virtual functions that +must be reimplemented for each type of plugin. +

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. +

The default directory for plugins is QTDIR/plugins*, +with each type of plugin in a subdirectory for that type, e.g. styles. 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 QSettings, for the application to read when it runs. The +application can then call QApplication::addLibraryPath() with this +path and your plugins will be available to the application. Note that +the final part of the path, i.e. styles, widgets, etc., cannot +be changed. +

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 DLL (or +so 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. appdir/plugins/designer, and place the plugin in that directory. +

For Qt Designer, you may need to +call QApplication::addLibraryPath("QTDIR/plugins/designer") to load +your Qt Designer plugins. +

* All references to QTDIR refer to the path +where Qt was installed. +

Loading and Verifying Plugins +

+

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. +

+

The Build Key +

+

The build key contains the following information: +

+

Plugins and Threaded Applications +

+

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 Qt +Designer with that library. Your .pro file for your plugin +must include the line: +

+    CONFIG += thread
+
+ +

Warning: 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. +

+

+
  1. +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, no plugins compiled with Qt 3.0.4 and +earlier will work with Qt 3.0.5 and later: they must be recompiled. + Back...
+ + +

+ +
Copyright © 2007 +TrolltechTrademarks +
Qt 3.3.8
+
+ -- cgit v1.2.3