From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- 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 000000000..97ecd683e --- /dev/null +++ b/doc/html/plugins-howto.html @@ -0,0 +1,262 @@ + + + + + +TQt Plugins HOWTO + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQt Plugins HOWTO

+ + + +

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. +(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 +
TQImageFormatPlugin +pluginsbase/imageformats * +
TQSqlDriverPlugin +pluginsbase/sqldrivers * +
TQStylePlugin +pluginsbase/styles * +
TQTextCodecPlugin +pluginsbase/codecs * +
TQWidgetPlugin +pluginsbase/designer * +
+

But where is the pluginsbase directory? When the application is +run, TQt 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, TQt will look in C:\Program Files\MyApp\styles. (See TQApplication::applicationDirPath() for +how to find out where the application's executable is.) TQt will also +look in the directory given by qInstallPathPlugins(). If you want +TQt to look in additional places you can add as many paths as you need +with calls to TQApplication::addLibraryPath(). And if you want to +set your own path or paths you can use +TQApplication::setLibraryPaths(). +

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

+    class MyStylePlugin : public TQStylePlugin
+    {
+    public:
+        MyStylePlugin() {}
+        ~MyStylePlugin() {}
+
+        TQStringList keys() const { 
+            return TQStringList() << "mystyle"; 
+        }
+
+        TQStyle* create( const TQString& key ) { 
+            if ( key == "mystyle" ) 
+                return new MyStyle;
+            return 0;
+        }
+    };
+
+    Q_EXPORT_PLUGIN( MyStylePlugin )
+
+ +

(Note that TQStyleFactory is case-insensitive, and the lower case +version of the key is used; other factories, e.g. TQWidgetFactory, 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 +retquired class (or 0 if the plugin is asked to create an object of a +class that it doesn't implement). For TQStylePlugin, 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. TQStylePlugin. +

For database drivers, image formats, custom widgets and text codecs, +no explicit object creation is retquired. TQt will find and create them +as retquired. Styles are an exception, since you might want to set a +style explicitly in code. To apply a style, use code like this: +

+    TQApplication::setStyle( TQStyleFactory::create( "MyStyle" ) );
+
+ +

Some plugin classes retquire additional functions to be implemented. +See the TQt Designer manual's, +'Creating Custom Widgets' section in the 'Creating Custom Widgets' +chapter, for a complete example of a TQWidgetPlugin, which implements +extra functions to integrate the plugin into TQt Designer. The +TQWidgetFactory class provides additional information on +TQWidgetPlugins. +

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

TQt applications automatically know which plugins are available, +because plugins are stored in the standard plugin subdirectories. +Because of this applications don't retquire any code to find and load +plugins, since TQt 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 TQSettings, for the application to read when it runs. The +application can then call TQApplication::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 TQt Designer, you may need to +call TQApplication::addLibraryPath("QTDIR/plugins/designer") to load +your TQt Designer plugins. +

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

Loading and Verifying Plugins +

+

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

+

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

+    CONFIG += thread
+
+ +

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

+

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

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1