CopperSpice Overview  1.5.2
Creating Plugins

Plugins are used to extend an application or the functionality provided by a CopperSpice library.

Plugins must be located in sub-directories of the standard plugin directory. CopperSpice will not find plugins if they are not stored in the correct directory. The exact path can be modified using cs.conf or using QApplication::addLibraryPath().

There are two APIs for creating plugins:

  • A group of high level APIs for writing extensions to CopperSpice
    Examples: database drivers, image formats, text codecs, custom styles, etc.
  • A low level API for extending CopperSpice applications

High Level API: Writing Extensions to CS

Writing a plugin that extends CopperSpice is achieved by inheriting from the appropriate plugin base class, implementing a few functions, and calling a macro. There are several plugin base classes as shown in the following table.


Base Class NameDirectory NameCase Sensitivity
QAccessibleBridgePlugin accessiblebridge Case Sensitive
QAccessiblePlugin accessible Case Sensitive
QDecorationPlugin decorations Case Insensitive
QFontEnginePlugin fontengines Case Insensitive
QIconEnginePlugin iconengines Case Insensitive
QImageIOPlugin imageformats Case Sensitive
QInputContextPlugin inputmethods Case Sensitive
QKbdDriverPlugin kbddrivers Case Insensitive
QMouseDriverPlugin mousedrivers Case Insensitive
QScreenDriverPlugin gfxdrivers Case Insensitive
QScriptExtensionPlugin script Case Sensitive
QSqlDriverPlugin sqldrivers Case Sensitive
QStylePlugin styles Case Insensitive
QTextCodecPlugin codecs Case Sensitive

Example Plugin

To add a new style plugin called MyStyle, refer to the following example.

Class definition, mystyleplugin.h:

1 class MyStylePlugin : public QStylePlugin
2 {
3  public:
4  QStringList keys() const;
5  QStyle *create(const QString &key);
6 };

Class implementation, mystyleplugin.cpp:

1 #include "mystyleplugin.h"
2 
3 QStringList MyStylePlugin::keys() const
4 {
5  return QStringList() << "MyStyle";
6 }
7 
8 QStyle *MyStylePlugin::create(const QString &key)
9 {
10  if (key.toLower() == "mystyle")
11  return new MyStyle;
12  return 0;
13 }
14 
15 Q_EXPORT_PLUGIN2(pnp_mystyleplugin, MyStylePlugin)

The QStylePlugin is case insensitive, therefore the above code needs to use the lower case version of the key. Most other plugins are case sensitive.

For database drivers, image formats, text codecs, and most other plugin types, no explicit object creation is required. Styles are an exception, since you might want to set a style explicitly in code. To apply a style, use the following code:

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

Some plugin classes require additional functions to be implemented. Refer to the class documentation for details of the virtual methods which must be reimplemented for each type of plugin.

Low Level API: Extending CS Applications

Making an application extensible through plugins involves the following steps:

  • Define a set of interfaces (classes with only pure virtual methods) used to communicate with the plugin
  • Use the Q_DECLARE_INTERFACE() macro to inform QPluginLoader about the interface
  • Use QPluginLoader in your application to load the plugin
  • Use dynamic_cast<>() to test whether a plugin implements a given interface

Writing a plugin involves these steps:

  • Declare a plugin class that inherits from QObject and from the interfaces the plugin provides
  • Use the CS_INTERFACE() macro to inform QPluginLoader about the interface
  • Call the Q_EXPORT_PLUGIN2(x1,x2) macro, passing the necessary parameters
  • Compile and link the plugin