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 tqInstallPathPlugins(). 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 required 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;
        }
    };

    TQ_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 required 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 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:

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

Some plugin classes require 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 require any code to find and load plugins, since TQt handles them automatically.

The default directory for plugins is TQTDIR/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("TQTDIR/plugins/designer") to load your TQt Designer plugins.

* All references to TQTDIR 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