PluginProgramming.docu 5.81 KB
 Jan Möbius committed Aug 29, 2008 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 /*! \page pluginProgramming Plugin Programming * \section plugin_sec Plugin Basics * * As mentioned above Openflipper is a plugin based system. It uses the qt plugin implementation to * load and unload plugins at runtime. Every algorithm should be added as one of these plugins. * * The plugins have to be created as .so (or under windows : .dll) files which should be symlinked or * copied to the Plugin subfolder. OpenFlipper distinguishes between 32/64-bit plugin versions and * max or dbg (release/debug) versions. So the compiled plugins have to reside in the right subdir of * Plugins. The Plugins are loaded on startup of the application (they may also be loaded at runtime * later). * * \section plugin_prog_sec Plugin programming * The interface between the core and the plugins is managed via simple interfaces based on the signal/slot * metaphor of qt. Your plugins have to be derived from these interfaces. You dont have to implementation * all functions or signals of the interfaces you include. This has only to be done for the BaseInterface * which must be implemented by every plugin. See the BaseInterface Documentation for details. * * Unimplemented functions will be left unconnected from the core and wont have any impact on the applications * speed or stability. As stated above, every plugin has to be derived from the BaseInterface. This is the * basic factory which makes the core aware of the plugin. The name and the description of the plugin is * exported via the baseinterface. The initialization of each plugin is done via this interface too. * * After this interface of the plugin is sucessfully processed all other interfaces will be initialized * and connected to the core. For details about the individual interfaces see their documentation. * \ref interfaces  27 28 29 30 31 32 33 34 35  * * \section ex1 A simple example * * In this section 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. \c Plugin-SimplePlugin. * The interface definition should contain the following header includes:  Jan Möbius committed Aug 29, 2008 36  *  37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78  * \dontinclude example/simplePlugin.hh * \skipline #include * \until Types.hh> * * As we know the plugin class has to be derived from at least \c BaseInterface, * the class definition will look like: * * \dontinclude example/simplePlugin.hh * \skipline class * * (Since we implement a Qt-class, our base object is QObject which provides * some basic functionality and type definitions.) * We then use the macros \c Q_OBJECT and \c 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. * * \dontinclude example/simplePlugin.hh * \skipline Q_OBJECT * \skipline Q_INTERFACES * * For now, the only thing we override from our base class is \c name() and \c 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). * * \dontinclude example/simplePlugin.hh * \skipline QString name( * \skipline QString description( * * 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 * * \dontinclude example/simplePlugin.cc * \skipline Q_EXPORT * * which exports the plugin class \c SimplePlugin with the name \c 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). *  Mike Kremer committed Jan 29, 2009 79  * The complete source code of the plugin looks like this:  80 81 82 83 84 85  * * simplePlugin.hh * \include example/simplePlugin.hh * * simplePlugin.cc * \include example/simplePlugin.cc  Mike Kremer committed Jan 29, 2009 86 87 88 89 90 91 92  * * \section ex1b Building our plugin * * The only thing that's still left to be created is our qmake project file * that is used to generate the Makefiles for the plugin. For general information on how to build * OpenFlipper with qmake see \ref buildingOpenFlipper. * So lets get started! First off we create a file \c Plugin-SimplePlugin.pro in the plugins's directory.  Mike Kremer committed Jan 29, 2009 93  * It is mandatory to name the project file after the project's directory.  Mike Kremer committed Jan 29, 2009 94 95  * * Our first line includes OpenFlipper's predefined qmake functions. This allows us to simply call  Mike Kremer committed Jan 29, 2009 96  * \c Plugin() in order to build our code as a plugin. The variable \c DIRECTORY holds  Mike Kremer committed Jan 29, 2009 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112  * the directories that are to be build (we only need the plugin's directory here since the plugin does not * depend on external libraries or sources). Our project file looks like this: * * Plugin-SimplePlugin.pro * \include example/Plugin-SimplePlugin.pro * * The \c HEADERS and \c SOURCES variables should be self-explanatory. \c FORMS contains qt user interface * files which aren't needed at this time but become important when using user forms for the plugin. * * Now go to the root path of OpenFlipper and enter \c qmake (be sure to use version 4 of qmake; some * linux distributions use the link \c qmake-qt4 against the executable) in order to create * the new Makefiles now containing our plugin. We now build OpenFlipper by entering \c make. * * To test if our plugin has been successfully loaded, we launch OpenFlipper and select \c Plugins->Unload \c Plugin. * If our plugin \c SimplePlugin is listed, everything is fine. If it's not listed, read OpenFlippers * log to see what happened wrong.  Jan Möbius committed Aug 29, 2008 113  */