PluginProgramming.docu 4.17 KB
Newer Older
Jan Möbius's avatar
 
Jan Möbius 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
/*! \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's avatar
 
Jan Möbius committed
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
79
80
81
82
83
84
85
 * \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 looks like this:
 *
 * simplePlugin.hh
 * \include example/simplePlugin.hh
 *
 * simplePlugin.cc
 * \include example/simplePlugin.cc
Jan Möbius's avatar
 
Jan Möbius committed
86
 */