Home · All Classes · Main Classes · Annotated · Grouped Classes · Functions

How to Create Qt Plugins

Qt provides two APIs for creating plugins:

For example, if you want to write a custom QStyle subclass and have Qt applications load it dynamically, you would then use the higher-level API; whereas if you want to extend Qt Designer, you would use the lower-level API.

Since the higher-level API is built on top of the lower-level API, some issues are common to both.

Topics:

The Higher-Level API: Writing Qt Extensions

Writing a plugin that extends Qt itself 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 ClassDefault Path
QImageIOPluginpluginsbase/imageformats
QSqlDriverPluginpluginsbase/sqldrivers
QStylePluginpluginsbase/styles
QTextCodecPluginpluginsbase/codecs
QWidgetPluginpluginsbase/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 QCoreApplication::applicationDirPath() for how to find out where the application's executable is.) Qt will also look in the directory specified by qInstallPathPlugins(). If you want Qt to look in additional places you can add as many paths as you need with calls to QCoreApplication::addLibraryPath(). And if you want to set your own path or paths you can use QCoreApplication::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().

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 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 (where QTDIR is the directory where Qt is installed), 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 QCoreApplication::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.

The Lower-Level API: Extending Qt Applications

Qt application can be extended through plugins. This requires the application to detect and load plugins using QPluginLoader. In that context, plugins may provide arbitrary functionality and are not limited to database drivers, image formats, text codecs, styles, and widgets.

The Plug & Paint example documentation explains this process in detail.

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:


Copyright © 2005 Trolltech Trademarks
Qt 4.0.0-rc1