A simple plugin

In this tutorial we are going to build our own OpenFlipper plugin step by step. The goal of this tutorial is to build a simple plugin that is loaded by OpenFlipper at launch.

We start by creating the plugin directory in OpenFlipper's root directory, naming it e.g. Plugin-SimplePlugin. The interface definition should contain the following header includes:

#include <OpenFlipper/BasePlugin/BaseInterface.hh>
#include <OpenFlipper/common/Types.hh>

As we know the plugin class has to be derived from at least BaseInterface, the class definition will look like:

class SimplePlugin : public QObject, BaseInterface

(Since we implement a Qt-class, our base object is QObject which provides some basic functionality and type definitions.) We then use the macros Q_OBJECT and Q_INTERFACES in order to make accessible the signals and slots which have to be overridden later on. See BaseInterface documentation for signals and slots that can be overriden.

Q_OBJECT
Q_INTERFACES(BaseInterface)

For now, the only thing we override from our base class is name() and description() which each returns the name and description of our plugin, respectively. The override of these two functions is mandatory, all other slots/signals are optional. Each of the functions returns a QString (see Qt documentation for information on Qt types).

  QString name() { return QString("SimplePlugin"); };
  QString description() { return QString("Does actually nothing but works!"); };

If you made it to this point, don't give up, we're almost there! Looks like this is it for the interface definition. We're now considering our implementation which consists of only a few lines. (Since we don't want to implement any functionality at this point).

The implementation only contains the macro

Q_EXPORT_PLUGIN2( simplePlugin , SimplePlugin );

which exports the plugin class SimplePlugin with the name simplePlugin (note that our class name is with a capital s whereas the export name is lower case). An important constraint is that the export name has to be unique (in case there exist multiple plugins).

The complete source code of the plugin looks like this:

simplePlugin.hh

#ifndef SIMPLEPLUGIN_HH_INCLUDED
#define SIMPLEPLUGIN_HH_INCLUDED

#include <OpenFlipper/BasePlugin/BaseInterface.hh>
#include <OpenFlipper/common/Types.hh>

class SimplePlugin : public QObject, BaseInterface
{
Q_OBJECT
Q_INTERFACES(BaseInterface)

public :
  
  ~SimplePlugin() {};
  
  QString name() { return QString("SimplePlugin"); };
  
  QString description() { return QString("Does actually nothing but works!"); };
  
};


#endif

simplePlugin.cc

#include "simplePlugin.hh"
#include "OpenFlipper/BasePlugin/PluginFunctions.hh"

Q_EXPORT_PLUGIN2( simplePlugin , SimplePlugin );

How to build the plugin with CMake

The only thing that's still left to be created is our cmake project file that is used to generate the Makefiles for the plugin. This step is very easy, so let's start. In your plugin's root directory create a CMakeLists.txt file.

Our first line includes OpenFlipper's predefined cmake plugin functions. This allows us to simply call the openflipper_plugin() macro in order to build our code as a plugin. Our project file then looks like this:

CMakeLists.txt

include (plugin)
openflipper_plugin ()

Note that you have several options that can be passed to the openflipper_plugin() function, see Building OpenFlipper Plugins with CMake for details. For our example project we just have to leave this line as it is.

Now, when building OpenFlipper with cmake, your plugin should be found and built automatically.

To test if our plugin has been successfully loaded, we launch OpenFlipper and select Plugins->Unload Plugin. If our plugin SimplePlugin is listed, everything is fine. If it's not listed, read OpenFlippers log to see what went wrong.

See Dataflow for further information on interface function calls.