Commit 2ca33deb authored by Mike Kremer's avatar Mike Kremer

Updated tutorial structure

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@5330 383ad7c9-94d9-4d36-a494-682f7c89f535
parent eb89dda1
/*! \page pluginProgramming Plugin Programming
*
* \section quickref Quick references:
* - \ref plugin_sec
* - \ref plugin_prog_sec
* \section tuts Tutorials
* - \ref ex1
* - \ref ex1b
* - \ref ex2
*
* \section plugin_sec Plugin Basics
*
* As mentioned above Openflipper is a plugin based system. It uses the qt plugin implementation to
......@@ -26,213 +35,4 @@
* and connected to the core. For details about the individual interfaces see their documentation.
* \ref interfaces
*
* \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:
*
* \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
*
* \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.
* 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.
*
*
* \section ex2 Implementing a mesh smoother Plugin
*
* The last section dealt with the implementation of a first plugin without any functionality at all. This section
* will show you how to progam a simple mesh smoother. We are assuming that you have read \ref ex1 and will only
* explain parts that have to be added in order to include new functionality.
*
*
* \subsection ex2Header Definition of the header
*
* To start of we first have to add two additional header files. The first one is the \c ToolboxInterface.
* We need this interface because we want to add a Toolbox to our plugin in order to be able to set parameters.
* Additionally, we want to use the \c LoggingInterface so that we can inform the user of our plugin when something
* went wrong.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline #include <OpenFlipper/BasePlugin/ToolboxInterface.hh>
* \skipline #include <OpenFlipper/BasePlugin/LoggingInterface.hh>
*
* In order to work with the Interfaces we have to define that the plugin will implement the additional interfaces.
* The class definition then looks as follows:
*
* \dontinclude example/SmootherPlugin.hh
* \skipline class SmootherPlugin
*
* Furthermore we have to insert the \c Q_INTERFACES macro. This makes the signals and slots from both interfaces available.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline Q_INTERFACES(ToolboxInterface)
* \skipline Q_INTERFACES(LoggingInterface)
*
* Now that we have defined which Interfaces to implement, we can look at which signals and slots we want to implement.
* Firstly, we need two additional signals from the \c BaseInterface :
*
* \dontinclude example/SmootherPlugin.hh
* \skipline void updateView()
* \skipline void updatedObject(
*
* The first signal updateView() is emitted when we have finished computing the smoothed mesh. The signal tells OpenFlipper
* to redraw its viewer(s). The second signal updatedObjects() is emitted to inform all other plugins that an object
* has changed and therfore allows each plugin to react on this change.
*
* Since we also want to use the \c LoggingInterface we have to define the following signals which allow us to send
* log messages to the OpenFlipper Loggers.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline void log(
* \skipline void log(
*
*
* The last Interface that's left over is the \c ToolboxInterface from which we are only implenting one function:
*
* \dontinclude example/SmootherPlugin.hh
* \skipline bool initializeToolbox
*
* As we will see later, this function is used to setup a ToolBox (i.e. a \c QWidget ) and return a reference of this
* ToolBox to OpenFlipper so that it can be intergrated into the GUI.
*
* As a last step we have to add to include additional class members to control the parameter for the smoothing and
* to actually compute the smoothed mesh.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline private:
* \until Laplace();
*
* That's it for the header of the plugin. The complete header looks like this:
*
* \include example/SmootherPlugin.hh
*
*
* \subsection ex2Implemenation1 Implemention of the GUI
*
* As we have already mentioned in \ref ex2Header, the ToolBox is generated inside the initializeToolbox() function.
* So inside this function we begin with creating the elements of the ToolBox:
*
* \dontinclude example/SmootherPlugin.cc
* \skipline QWidget
* \until Iterations:");
*
* Later, the smoothButton is used to start the mesh smoothing and the iterationsSpinbox_ allows the user to control
* the number of smoothing iterations that should be performed.
*
* The created Toolbox elements are then combined into a Layout
*
* \dontinclude example/SmootherPlugin.cc
* \skipline QGridLayout
* \until 2,0,1,2);
*
* Here, the SpacerItem, which is added last, only helps aligning the elements at the top of the toolbox.
*
* We have to connect the smoothButton to the simpleLaplace() slot of our class, so that after clicking
* the button the slot is called. Finally, we return a reference to the new Toolbox by assigning it to _widget and
* return true because we succesfully created the Toolbox.
*
* \dontinclude example/SmootherPlugin.cc
* \skipline connect
* \until true;
*
*
* \subsection ex2Implemenation2 Implemention of the Smoother
*
* Now that the Toolbox is completely setup, we can start implementing the smoother. We begin with searching objects
* on which we have to compute the smoothing. The algorithm takes all objects marked as target and tries to apply the
* smoothing.
*
* To find all these Objects we use an ObjectIterator. This iterator can be found in the PluginFunctions. Every
* communication between OpenFlipper and its Plugins is accomplished through either an interface or the PluginFunctions.
* So these are the places to look for if you want to add additional functionality and therefore need to communicate
* with OpenFlipper.
*
* We initialize the PluginFunctions::ObjectIterator with PluginFunctions::TARGET_OBJECTS and thereby make sure that the
* the iteration is restricted to target objects only.
*
* \dontinclude example/SmootherPlugin.cc
* \skipline void SmootherPlugin::simpleLaplace() {
* \until ++o_it) {
*
*
*
*
*
*/
/*! \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
*
* \section ex1b How to build a plugin with qmake
*
* 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.
* 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.
*/
\ No newline at end of file
/*! \page ex2 Implementing a mesh smoother Plugin
*
* The last section dealt with the implementation of a first plugin without any functionality at all. This section
* will show you how to progam a simple mesh smoother. We are assuming that you have read \ref ex1 and will only
* explain parts that have to be added in order to include new functionality.
*
* \subsection ex2Header Definition of the header
*
* To start of we first have to add two additional header files. The first one is the \c ToolboxInterface.
* We need this interface because we want to add a Toolbox to our plugin in order to be able to set parameters.
* Additionally, we want to use the \c LoggingInterface so that we can inform the user of our plugin when something
* went wrong.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline #include <OpenFlipper/BasePlugin/ToolboxInterface.hh>
* \skipline #include <OpenFlipper/BasePlugin/LoggingInterface.hh>
*
* In order to work with the Interfaces we have to define that the plugin will implement the additional interfaces.
* The class definition then looks as follows:
*
* \dontinclude example/SmootherPlugin.hh
* \skipline class SmootherPlugin
*
* Furthermore we have to insert the \c Q_INTERFACES macro. This makes the signals and slots from both interfaces available.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline Q_INTERFACES(ToolboxInterface)
* \skipline Q_INTERFACES(LoggingInterface)
*
* Now that we have defined which Interfaces to implement, we can look at which signals and slots we want to implement.
* Firstly, we need two additional signals from the \c BaseInterface :
*
* \dontinclude example/SmootherPlugin.hh
* \skipline void updateView()
* \skipline void updatedObject(
*
* The first signal updateView() is emitted when we have finished computing the smoothed mesh. The signal tells OpenFlipper
* to redraw its viewer(s). The second signal updatedObjects() is emitted to inform all other plugins that an object
* has changed and therfore allows each plugin to react on this change.
*
* Since we also want to use the \c LoggingInterface we have to define the following signals which allow us to send
* log messages to the OpenFlipper Loggers.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline void log(
* \skipline void log(
*
*
* The last Interface that's left over is the \c ToolboxInterface from which we are only implenting one function:
*
* \dontinclude example/SmootherPlugin.hh
* \skipline bool initializeToolbox
*
* As we will see later, this function is used to setup a ToolBox (i.e. a \c QWidget ) and return a reference of this
* ToolBox to OpenFlipper so that it can be intergrated into the GUI.
*
* As a last step we have to add to include additional class members to control the parameter for the smoothing and
* to actually compute the smoothed mesh.
*
* \dontinclude example/SmootherPlugin.hh
* \skipline private:
* \until Laplace();
*
* That's it for the header of the plugin. The complete header looks like this:
*
* \include example/SmootherPlugin.hh
*
*
* \subsection ex2Implemenation1 Implemention of the GUI
*
* As we have already mentioned in \ref ex2Header, the ToolBox is generated inside the initializeToolbox() function.
* So inside this function we begin with creating the elements of the ToolBox:
*
* \dontinclude example/SmootherPlugin.cc
* \skipline QWidget
* \until Iterations:");
*
* Later, the smoothButton is used to start the mesh smoothing and the iterationsSpinbox_ allows the user to control
* the number of smoothing iterations that should be performed.
*
* The created Toolbox elements are then combined into a Layout
*
* \dontinclude example/SmootherPlugin.cc
* \skipline QGridLayout
* \until 2,0,1,2);
*
* Here, the SpacerItem, which is added last, only helps aligning the elements at the top of the toolbox.
*
* We have to connect the smoothButton to the simpleLaplace() slot of our class, so that after clicking
* the button the slot is called. Finally, we return a reference to the new Toolbox by assigning it to _widget and
* return true because we succesfully created the Toolbox.
*
* \dontinclude example/SmootherPlugin.cc
* \skipline connect
* \until true;
*
*
* \subsection ex2Implemenation2 Implemention of the Smoother
*
* Now that the Toolbox is completely setup, we can start implementing the smoother. We begin with searching objects
* on which we have to compute the smoothing. The algorithm takes all objects marked as target and tries to apply the
* smoothing.
*
* To find all these Objects we use an ObjectIterator. This iterator can be found in the PluginFunctions. Every
* communication between OpenFlipper and its Plugins is accomplished through either an interface or the PluginFunctions.
* So these are the places to look for if you want to add additional functionality and therefore need to communicate
* with OpenFlipper.
*
* We initialize the PluginFunctions::ObjectIterator with PluginFunctions::TARGET_OBJECTS and thereby make sure that the
* the iteration is restricted to target objects only.
*
* \dontinclude example/SmootherPlugin.cc
* \skipline void SmootherPlugin::simpleLaplace() {
* \until ++o_it) {
*/
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment