tutorial1.docu 5.08 KB
Newer Older
Mike Kremer's avatar
Mike Kremer committed
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 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
/*! \page ex1 A simple plugin
 *
 * 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:
 * 
 * \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).
 *
 * The complete source code of the plugin looks like this:
 *
 * simplePlugin.hh
 * \include example/simplePlugin.hh
 *
 * simplePlugin.cc
 * \include example/simplePlugin.cc
 *
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83
 *
 * \section ex1c How to build the plugin with cmake (recommended)
 * 
 * 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
 * \c openflipper_plugin() macro in order to build our code as a plugin. Our project file then looks like this:
 *
 * CMakeLists.txt
 * \include example/CMakeLists.txt
 *
 * Note that you have several options that can be passed to the openflipper_plugin() function:
 * The usage of this function is:
 *
 * \include example/cmake_plugin_usage.txt
 *
 * See the cmake documentation for detailed information on the different parameters.
 *
 * Now, when building OpenFlipper with cmake, your plugin should be found and built automatically.
 *
 * \section ex1b How to build the plugin with qmake (obsolete)
Mike Kremer's avatar
Mike Kremer committed
84
 * 
85 86 87
 * If you use QMake to generate your makefiles, you can drop the previous section.
 * Note: Using QMake as build system has become obsolete since OpenFlipper 1.0 RC1.
 * For general information on how to build
Mike Kremer's avatar
Mike Kremer committed
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
 * 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.
 * It is mandatory to name the project file after the project's directory.
 *
 * Our first line includes OpenFlipper's predefined qmake functions. This allows us to simply call
 * \c Plugin() in order to build our code as a plugin. The variable \c DIRECTORY holds
 * 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 went wrong.
 *
 * See \ref dataFlow for further information on interface function calls.
 */