Commit a3318f26 authored by Mike Kremer's avatar Mike Kremer

Restructured documentation

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@5747 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 2254fe65
/** \page interfaces Plugin Interfaces
*
* OpenFlipper provides a flexible plugin interface. Plugins can implement various interfaces.
* Each interface provides special signals/slots or functions to communicate with the core or
* to react on special events. The most important interface is the BaseInterface. This Interface
* provides the core functionality for the plugin. E.g. loading the plugin, specifying its name
* and basic communication regrading object changes or view updates ( See BaseInterface for further details).\n
* Additional functionality is provided by the other interfaces. For user interaction one typically uses the
* MouseInterface or KeyInterface which will provide events based on mouse or keyboard interaction.\n
* The interface of OpenFlipper can also be used by plugins. The MenubarInterface provides functions to
* add additional icons to the menubar. Using the ToolboxInterface one can add widgets to the toolbox on
* the right of the OpenFlipper screen.
*
*
* \section BasePlugin Base Interface
* This is the Basic plugin Interface. All Plugins have to provide at least this interface. It offers plugin
* name and some important Signals and slots which will be called by the main application. See BaseInterface
* for details.
*
* \section KeyPlugin Keyboard Interface
* \image html keyInterface.png
* You have to provide this interface if you want to get key events in your plugin ( KeyInterface ).\n
*
*
* \section MousePlugin Mouse Interface
* \image html mouseInterface.png
* This interface is used to deliver mouse events to a plugin ( MouseInterface ).\n
*
*
* \section LoadSavePlugin Load / Save Interface
* \image html loadSaveInterface.png
* Provides functions to handle mesh files and load / unload geometry
* objects into the scene graph ( LoadSaveInterface ).
*
*
* \section ToolbarPlugin Toolbar Interface
* \image html ToolbarInterface.png
* Provides a function to add toolbar buttons. ( ToolbarInterface )
*
*
* \section MenubarPlugin Menubar Interface
* \image html MenubarInterface.png
* Provides a function to create an entry in the menubar ( MenuInterface ).
*
*
* \section ToolboxPlugin Toolbox Interface
* \image html ToolboxInterface.png
* Provides functions to create a separate widget in the toolbox on the right ( ToolboxInterface ).
*
*
* \section LoggingPlugin Logging Interface
* \image html LoggingInterface.png
* This is an Interface for Logging to the included textedit widget. You can log to different levels
* (LOGOUT,LOGWARN,LOGERR,LOGINFO) ( LoggingInterface ).
*
*
* \section TexturePlugin Texture Interface
* \image html TextureInterface.png
* Allows your plugin to provide a texture. ( TextureInterface )
*
*
* \section PickingPlugin Mouse Picking / Pick Modes
* \image html PickingInterface.png
* Handle mouse picking in your plugin ( PickingInterface )
*
*
* \section RPCPlugin RPC Interface
* \image html RPCInterface.png
* This interface is used to call functions across different plugins ( RPCInterface ).
*
*
* \section FilePlugin File Interface
* \image html FileInterface.png
* Provides functions to read and write custom filetypes ( FileInterface )
*
*
* \section ViewPlugin View Interface
* \image html ViewInterface.png
* This interface is used to add additional view widgets ( ViewInterface ).
*
*
* \section ScriptPlugin Script Interface
* \image html ScriptInterface.png
* For plugins who provide scriptable functions ( ScriptInterface )
*
*
* \section StatusPlugin Status Bar Interface
* \image html StatusbarInterface.png
* This interface is used to display messages in the status bar ( StatusbarInterface )
*
*
* \section OptionsPlugin Options Interface
* \image html OptionsInterface.png
* This Interface is used by plugins which will provide their own options by
* integrating its own options widget into OpenFlipper's options window. ( OptionsInterface )
*
*
* \section BackupPlugin Backup Interface
* \image html BackupInterface.png
* Use this interface to backup data ( BackupInterface )
*
*
* \section INIPlugin Use Inifiles to store information
* \image html INIInterface.png
* Receive an event if an ini file is opened by the application. ( INIInterface )\n
*/
/*! \page buildingOpenFlipper Building OpenFlipper
* \section dependencies Dependencies
*
* OpenFlipper is developed on top of the Qt framework. This framework provides
* easy cross platform development. Therefore an installed version of qt with
* at least version 4.5 is required. As the framework depends on qt we use the
* qt make tool qmake to build OpenFlipper.
*
* \section bs Build System
* The build system uses qmake to generate all makefiles. In the toplevel directory of
* OpenFlipper is a .qmake.cache file which defines the variable TOPLEVEL available
* in all qmake project files. This file also includes our qmake configuration in the
* qmake subdirectory. The files in this directory control the build process for the
* core as well as for the plugins. Library dependencies are specified in the project
* files by calling functions which will check for the requested libs. These functions are
* defined in architecture dependend files under qmake/packages . If you get errors
* about libraries not found, please change the paths in these configuration files.
*
* \section reqlibs Required libraries
* <ul>
* <li> Qt >= 4.5 ( http://www.qtsoftware.com/downloads )</li>
* <li> OpenGL ( http://www.opengl.org )</li>
* <li> GLUT ( http://glew.sourceforge.net )</li>
* <li> GLEW ( http://www.opengl.org/resources/libraries/glut/ )</li>
* <li> freetype2 ( optional http://www.freetype.org/freetype2/index.html )</li>
* <li> ftgl ( optional http://sourceforge.net/projects/ftgl/)</li>
* </ul>
*
* \section blinux Building OpenFlipper under Linux
* <ul>
* <li> First extract the source code or get it via svn:<br />
* <code><b> svn co http://www-i8.informatik.rwth-aachen.de/svnrepo/OpenFlipper/branches/Free OpenFlipper</b></code></li>
* <li> Get all required libraries and install them ( including headers! ).</li>
* <li> Go to the qmake/packages directory and change the packages.<Architecture > files to match the library paths</li>
* <li> In the toplevel Directory call <b> qmake </b> ( It should be the qmake Version for qt4! Debian uses for example qmake-qt4 )
This will build the Makefiles</li>
* <li> Now call <b> make </b> to build OpenFlipper </li>
* </ul>
*
* After building OpenFlipper the Core can be found in the OpenFlipper/<OperatingSystem>_<Arch>_Release.
* The plugins are build in the OpenFlipper/Plugins directory.
*
* \section bwin Building OpenFlipper under Windows
*
* <ul>
* <li> Get Visual Studio 2008 </li>
* <li> Get and Install Qt ( >= 4.5 ) </li>
* <li> Set the QTDIR Variable to your Qt Installation directory </li>
* <li> Extract OpenFlipper source code. </li>
* <li> Get all required libraries and install them ( including headers! ).</li>
* <li> Open <code><b> OpenMesh\qmake\packages\packages.Windows </b></code> in a text editor and change header and library paths<br>
* such that they match the ones installed (see comments to find path entries).</li>
* <li> Open Visual Studio 2008 and go to Tools->Visual Studio command prompt</li>
* <li> Go to the toplevel OpenFlipper directory </li>
* <li> Call <b> qmake -spec win32-msvc2008 -r </b> ( It should be the qmake Version for qt4! )
This will build Visual Studio project files and a solution file.</li>
* <li> Open the OpenFlipper.sln file in the toplevel directory. </li>
* <li> Now you can build OpenFlipper from within Visual Studio. </li>
* </ul>
*
* After building OpenFlipper the Core can be found in the OpenFlipper/Windows_<Arch>_Release.
* The plugins are build in the OpenFlipper/Plugins directory.
*
* \section bmac Building OpenFlipper under MacOS X
*
* - Download and install latest Xcode Tools (including gcc)
* - Download and install Qt (>= 4.5)
* - Install required libraries (using a portage system like MacPorts is recommended)
* - Download and extract OpenFlipper sources<br />
* (or download via svn:<code><b> svn co http://www-i8.informatik.rwth-aachen.de/svnrepo/OpenFlipper/branches/Free OpenFlipper</b></code>)
* - Adapt library and header paths in <code><b> $OpenFlipper/qmake/packages/packages.Darwin </b></code>
* - Go into OpenFlipper's root directory and type <code><b> qmake -spec macx-g++ </b></code>
* - Type <code><b>make qmake_all</b></code> to build all Makefiles
* - Now type <code><b>make release</b></code> to build OpenFlipper
* - Execute <code><b>Build_Darwin_Bundle.sh</b></code> in OpenFlipper's root directory to correct install_name paths within the application bundle
*
* <b>IMPORTANT: If you don't see any icons in the application you probably might have
* forgot the last step which manages to copy the <i>Icons</i>, <i>Textures</i>, <i>Shaders</i> and <i>Fonts</i>
* directories into the application bundle's resource folder. It further fixes library header paths
* such that the application bundle can be copied anywhere without getting trouble
* with missing libraries.</b>
*
* After building OpenFlipper the application bundle can be found in OpenFlipper/Darwin_<Arch>_Release.
* The plugins are build into the application bundle's Resources directory.
*
* Note: If you don't want qmake to build OpenFlipper as MacOS X application bundle
* you have to uncomment line <br /><br /><code><b># CONFIG -= app_bundle # Do not build a framework bundle</b></code><br /><br />
* of function <code>defineTest(Application)</code> and comment out line<br /><br />
* <code><b>DESTDIR = $${TOPDIR}/OpenFlipper/$${BUILDDIRECTORY}/OpenFlipper.app/Contents/Plugins/$${SYSTEMTYPE}/$${ARCHITECTURE}/$${MODE}</b></code><br /><br />
* of function <code>defineTest(Plugin)</code> in file <code>$OpenFlipper/qmake/all.include</code>.
*/
/** \page uiconcept User Interface Concepts
*
* OpenFlipper is a powerful tool that allows implementing algorithms on geometry
* with preferably small effort.
* It bases on the Qt plugin model such that it is easily extendable
* by user defined plugins. For information on how Qt plugins work we recommend
* developers to read the Qt documentation. The integration of a plugin into
* OpenFlipper's user interface and its interactivity are controlled by
* \ref interfaces that can be implemented. Also see \ref pluginProgramming for
* a few small tutorials on OpenFlipper plugin programming.
*
* \section userInterface The user interface
*
* The OpenFlipper user interface is composed of four essential widgets
* each accessible and extendable by user plugins:
*
* - \ref viewport_widget
* - \ref plugin_widget
* - \ref logging_widget
* - \ref tool_bar
*
* \section mouseKeyboardEvents Mouse and keyboard events
*
* The user interactivity is gained by plain Qt mouse and keyboard events. If
* the plugin wants to interact with the mouse or keyboard, it
* has to implement the \ref MouseInterface and \ref KeyInterface
* (for keyboard shortcuts, etc.). Read tutorial \ref ex3 to learn how
* to add mouse and keyboard interactivity to your plugin. Also see
* \ref interfaces for an overview of implementable interfaces.
*
* \section viewport_widget The viewport widget
*
* The viewport widget visualizes the whole scenegraph. One can adjust
* viewer specific settings by chosing \c View in OpenFlippers
* menu bar. Adjustable settings contain:
*
* - Drawmodes (points, wireframe, solid,...)
* - Projection mode (orthogonal, perspective)
* - Set / reset home view
* - Capture screenshots
* - Adapt colors such that they match the desired profile (for printing, presentation,...)
*
* See \ref geometryData for information on how to manipulate geometry
* in the scenegraph from within a plugin.
*
* \image html viewport_widget.png The viewport widget
*
* \section plugin_widget The plugin widget
*
* The plugin widget shows the Qt toolboxes of the loaded plugins. A plugin can integrate
* its own toolbox by simply implementing the \ref ToolboxInterface. Providing toolboxes
* is not mandatory, but most plugins make use of it in order to offer user control
* to its parameters.
*
* \image html plugin_widget.png The plugin widget with simple smoother plugin opened
*
* \section logging_widget The logging widget
*
* The logging widget is used to display plugin specific information,
* warnings or errors. By implementing the \ref LoggingInterface a plugin
* can easily tell the user what is going on inside.
*
* \image html logging_widget.png The logging widget after opening a triangle mesh file
*
* \section tool_bar The tool bar
*
* The toolbar at the top of OpenFlippers main window offers clickable icons to
* quickly access a plugins function. A user plugin can integrate its own buttons
* into the tool bar by implementing the \ref ToolbarInterface.
*
* \image html tool_bar.png The tool bar
*/
/** \page dataFlow Dataflow
*
* \section quickref Quick references:
* - \ref startup
* - \ref loadSettings
* - \ref saveSettings
* - \ref updateObjects
* - \ref updateView
*
* \section startup Startup process
*
* Starting OpenFlipper invokes the following processes: <br><br>
* \subsection ref1 References:
* \ref BaseInterface::initializePlugin(),<br>\ref BaseInterface::pluginsInitialized(),<br>\ref INIInterface::loadIniFileOptions()<br>
*
* \image html startupProcess.jpg
*
* \section loadSettings Load settings
*
* Also see \ref INIInterface
*
* \subsection ref2 References:
* \ref INIInterface::loadIniFileOptions(),<br>\ref INIInterface::loadIniFile(),<br>\ref INIInterface::loadIniFileOptionsLast()<br>
*
* \image html loadSettingsFlow.jpg
*
*
* \section saveSettings Save settings
*
* Also see \ref INIInterface
*
* \subsection ref3 References:
* \ref INIInterface::saveIniFileOptions(),<br>\ref INIInterface::saveIniFile(),<br>
* \image html saveSettingsFlow.jpg
*
*
* \section updateObjects Update objects
*
* Each time an object has been modified by a plugin, the plugin has to emit the
* signal BaseInterface::updatedObject() in order to initiate the core to inform
* all other plugins about the changes and redraw the scene.
*
* Also see \ref BaseInterface
*
* \subsection ref4 References:
* \ref BaseInterface::updatedObject(),<br>\ref BaseInterface::slotObjectUpdated(),<br>
* \image html updateObject.jpg
*
*
* \section updateView Update view
*
* A plugin can provoke a redraw of the scene by emitting the signal BaseInterface::updateView().
*
* Also see \ref BaseInterface
*
* \subsection ref5 References:
* \ref BaseInterface::updateView(),<br>
* \image html updateView.jpg
*
*/
/** \page dataStructure Datastructures
*
* \section Overview
*
*
* All Objects have to be derived from the BaseObject. For the predefined objects this is
* already the case. In BaseObject a tree structure is implemented. You can use the functions
* in BaseObject to search for items and access them. A root Object is created by OpenFlipper
* which is the root of the object tree. You can get it via PluginFunctions::objectRoot(). There
* is also a groupobject which holds no data and is used for grouping different objects.
*
* All objects in OpenFlipper are handled by the core. To create and delete objects use
* the functions provided by the LoadSaveInterface.
*
* \section loadingDataAndExistingTypes Loading data and existing types
* If you want to load or delete data from within your plugin and you only use existing types
* you can derive from the LoadSaveInterface. This interface provides load and save functions
* to tell the core that you want to access existing data types.
*
* \subsection DataAccess Access to data from within the Plugins
* From each plugin you have to get access to the data. Functions to get the right data are provided in the
* PluginFunctions Namespace. Here are all functions which should be used to access the data. Most of the
* time you will use the ObjectIterator defined there. If you need consistent data access during the plugin
* lifetime (e.g. you have to track one mesh during the plugin lifetime) you should use the identifiers made
* available in this namespace which never change.\n \n
* It is possible that the vector containing the objects changes during the plugin lifetime (added or deleted objects).
* Only the identifiers will stay constant. If one of these changes occurs, the main application will call
* BaseInterface::updatedObject() of all Plugins containing the id of a changed object or -1 if an object
* has been deleted. LoadSaveInterface::objectDeleted() will tell you if an object is deleted.
* If you have to keep track of these changes, implement these functions.
*
* \section basicObjectTypes Basic object types
* \subsection baseObjectDescription BaseObject
* All objects are derived from BaseObject. This object implements the basic object
* functions. It creates a tree structure of all available objects, includes object
* selection, name and type information. It does not contain any code to visualize
* objects.
* Each object derived from BaseObject has a datatype function BaseObject::dataType.
*
* Additionally you can add data to each object by using the perObjectData class.
* See PerObjectData
*
* \subsection baseObjectDataDescription BaseObjectData
* This class is derived from BaseObject and includes basic visualization functions. It creates
* the basic scenegraph nodes for the object ( TODO : See per Object Scenegraph structure ).
*
* For every object, the top scenegraph node is the ObjectData::SeparatorNode*. All other
* nodes ( including per object custom nodes ) have to be added below this node. Additionally
* an ManipulatorNode is added below the separator node. This manipulator is used to move
* or transform the object. Normally this node is managed by the move plugin. If you
* use per object nodes which should be transformed along with the object you can attach
* them below this node ( BaseObjectData::manipulatorNode() ).
*
* Additionally per object scenegraph nodes can be managed automatically by BaseObjectData.
*
*
* \subsection MeshObjectDescription MeshObject
* MeshObject is the class representing triangle or poly meshes. It uses OpenMesh as its
* data structure.
* It is based on BaseObjectData and adds additional scenegraph nodes. First it creates a materialNode
* used to set the meshes rendering material properties, followed by a texture node ( MeshObject::textureNode() ). A shader node ( MeshObject::shaderNode() ) is than
* added to manage the systems and user defined shaders. Below the shader node is the mesh node ( MeshObject::meshNode() )which actually
* renders the mesh.
* Additionally some nodes to render selection, features or modeling areas are added by the MeshObject
*
* See MeshObject for the detailed function documentation.
*
*
* \section creatingCustomObjectTypes Creating custom object types
*
*/
/*! \mainpage OpenFlipper
*\image html splash.png
* \section intro_sec Introduction
*
* This is the developer documentation for the OpenFlipper project.
* OpenFlipper is a flexible geometry modeling and processing system.
* OpenFlipper consists of the core application and a set of plugins. Only
* the minimal required functionality is implemented inside the core. Plugins
* can be written to extend OpenFlipper and provide new data types,
* processing functions or user interface modifications. All these plugins
* are managed by the core. This manual describes how OpenFlipper plugins
* can be created and how they can communicate with the core. There are of
* course examples for a quickstart into OpenFlippers plugin interface.
*
* This manual is divided into the following pages:
* - \subpage uiconcept "User Interface Concepts"
* - \subpage buildingOpenFlipper "Building OpenFlipper"
* - \subpage pluginProgramming "Plugin Programming"
* - \subpage interfaces "Plugin Interfaces"
* - \subpage dataStructure "Datastructures"
* - \subpage dataFlow "Dataflow"
* - \subpage options "Command line options and config files"
*/
/*! \page options Command line options and config files
* \section cmdOptions Command line options
* Load/Save Options:\n
* -p : Open files as PolyMeshes\n
*
* Gui Options:\n
* -f : Start Fullscreen\n
* -l : Start with hidden logger\n
* -t : Start with hidden Toolbox\n
* --no-splash : Disable splash screen\n
* --disable-stereo : Disable Stereo Mode\n
*
* Log options:\n
* --log-to-console ( -c ) : Write logger window contents to console\n
*
* Other options:\n
* -b : Batch mode, you have to provide a script for execution and the system will start without gui\n
* --remote-control : Batch mode accepting remote connections\n
*
* \section confFiles Config Files
* OpenFlipper uses a set of config files which are loaded at runtime and define
* basic settings. Most of these settings can be made through the options dialog.
* The settings are loaded from the following files in the given order while the later
* files overwrites previous settings:
* <ul>
* <li> OpenFlipper.ini from the application directory </li>
* <li> OpenFlipper.ini from the $HOME/.OpenFlipper </li>
* </ul>
*/
/*! \page pluginProgramming Plugin Programming
*
* \section quickref Quick references:
* - \ref plugin_sec
* - \ref plugin_prog_sec
* - \ref geometryData
* \section tuts Tutorials
* - \ref ex1
* - \ref ex1b
* - \ref ex2
* - \ref ex3
* - \ref ex4
*
* \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 implement
* 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.
* See \ref dataFlow for an overview of OpenFlipper's data flow and interface function calls.
*
* 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
*
* \section geometryData Handling geometry data within a plugin
*
* \subsection addingAndRemovingGeometry Adding and removing mesh objects in OpenFlipper
*
* If you want to load geometry data from a file or simply add objects to the scene
* from within a plugin, it has to implement the \ref LoadSavePlugin.
*
* LoadSaveInterface::load( QString _file, DataType _type, int& _id) tries to
* load file with file name _file of type _type, _id contains the new created
* object's id or -1 if loading failed. OpenFlipper will then create all
* the necessary scene graph nodes such that the developer generally does
* not need to know in detail how to create and add the required nodes to the scene.
*
* Otherwise if a file has been loaded externally, slot
*
* LoadSaveInterface::openedFile (int _id) is called.
*
* When removing objects from the scene, the plugin simply has to emit signal
*
* LoadSaveInterface::deleteObject(int _id)
*
* or
*
* LoadSaveInterface::deleteAllObjects() in order to clear the scene.
*
* \subsection pluginFunctions OpenFlipper's plugin functions
*
* As a plugin in most cases operates on geometry data, developers might want to know how to gain access to mesh data
* from within a plugin. In our tutorial \ref ex2 we roughly mentioned that the communication between OpenFlipper
* and it's plugins is accomplished through either one of the provided \ref interfaces or the \ref PluginFunctions.
*
* For example iterating over all objects that have been marked as source objects is done via
*
* <code>
* for ( PluginFunctions::ObjectIterator o_it(PluginFunctions::SOURCE_OBJECTS);<br />
* o_it != PluginFunctions::objectsEnd(); ++o_it) { ... }
* </code>
*
* Possible restrictions are \c ALL_OBJECTS (to iterate over all objects in the scene), \c TARGET_OBJECTS (objects
* that were marked as target) and \c SOURCE_OBJECTS.
*
* Another way to get handles to scene objects is to use the functions \c PluginFunctions::getObject() or
* PluginFunctions::getPickedObject(). These functions provide a pointer to either a \ref BaseObjectData
* or \ref BaseObject object. As in \ref ex2 one can easily test the type of an object by calling
*
* \c o_it->dataType(DATA_TYPE)
*
* where \c o_it is an object iterator and \c DATA_TYPE is one of the data types specified in \ref OpenFlipper/common/Types.hh.
* \c o_it->dataType(DATA_TRIANGLE_MESH) for example will return true if the object is a triangle mesh.
*
* The mesh data itself can be obtained by calling the appropriate handle plugin function. For example if we consider
* a triangle mesh, we get a handle to the mesh itself by calling
*
* <code>TriMesh* mesh = PluginFunctions::triMesh(*o_it);</code>
*
* where \c o_it once again is our object iterator. See \ref PluginFunctions for a complete overview.
*
* \subsection updatingObjects Updating objects
*
* Once your plugin has manipulated object data we have to inform OpenFlipper's core about the changes.
* When doing this, OpenFlipper distinguishes between four fundamental types of changes:
*
* - Changing geometry
* - Changing object properties
* - Changing object's visibility
* - Changing selection type
*
* When changing geometry, OpenFlipper's core will be forced to redraw the object that has been
* changed by emitting signal
*
* \ref BaseInterface::updatedObject(int _id)
*
* where \c _id is the object's id.
*
* When changing object properties it won't be necessary to redraw the scene
* since it can be expensive in computation power. In this case, one should emit
*
* \ref BaseInterface::objectPropertiesChanged(int _id)
*
* where \c _id once again is the object's id.
*
* If a plugin changed an object's visibility (hide, show), it should emit
*
* \ref BaseInterface::visibilityChanged(int _id)
*
* for the core to update the visibility state of object with identifier \c _id.
*
* Last, when changing an object's selection, it
* will be updated by emitting
*
* \ref BaseInterface::objectSelectionChanged(int _id)
*
* where \c _id as in the examples above is the object's identifier.
*
* Also see \ref BaseInterface.
*/
/*! \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 the 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.
*