CopperSpice API  1.9.2
Creating Plugins

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

CopperSpice will not find plugins unless they are located in the correct relative path. For example, all SQL drivers must be located in a sub-directory called sqldrivers. Typically this sub-directory will be relative to the application executable. However, the exact path for the sqldrivers directory can be modified using cs.conf or using QApplication::addLibraryPath().

Refer to Plugin Path Configuration for more information.

Writing Extensions to CopperSpice

There are two APIs for creating plugins:

  • A group of APIs for writing extensions to CopperSpice
    Examples: database drivers, image formats, text codecs, custom styles, etc.
  • An API for extending your CopperSpice application

Writing a plugin that extends CopperSpice is achieved by subclassing the appropriate plugin base class, reimplementing a few methods and then exporting the class with the CS_PLUGIN_REGISTER() macro.

For a list of the interfaces and plugin base classes refer to List of Plugins.

Example Plugin

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

// header file
class MyStylePlugin : public QStylePlugin
{
CS_OBJECT(MyStylePlugin)
CS_PLUGIN_IID("com.copperspice.CS.QStyleFactoryInterface")
CS_PLUGIN_KEY("mystyle")
public:
QStyle *create(const QString &key);
};
// cpp file
#include "mystyleplugin.h"
QStyle *MyStylePlugin::create(const QString &key) {
if (key.toLower() == "mystyle") {
return new MyStyle;
}
return nullptr;
}
CS_PLUGIN_REGISTER(MyStylePlugin)

The QStylePlugin is case insensitive so the call to toLower() is required in the implementation of the create() method. Most of the other plugins are case sensitive.

For database drivers, image formats, text codecs, and 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 type of code.

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

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

Extending a CopperSpice Application

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 if 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 CS_PLUGIN_REGISTER() macro
  • Compile and link the plugin