BaseInterface.hh 14.4 KB
Newer Older
1
/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
2 3
*                                                                            *
*                              OpenFlipper                                   *
Jan Möbius's avatar
Jan Möbius committed
4
*      Copyright (C) 2001-2011 by Computer Graphics Group, RWTH Aachen       *
Jan Möbius's avatar
Jan Möbius committed
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
*                           www.openflipper.org                              *
*                                                                            *
*--------------------------------------------------------------------------- *
*  This file is part of OpenFlipper.                                         *
*                                                                            *
*  OpenFlipper is free software: you can redistribute it and/or modify       *
*  it under the terms of the GNU Lesser General Public License as            *
*  published by the Free Software Foundation, either version 3 of            *
*  the License, or (at your option) any later version with the               *
*  following exceptions:                                                     *
*                                                                            *
*  If other files instantiate templates or use macros                        *
*  or inline functions from this file, or you compile this file and          *
*  link it with other files to produce an executable, this file does         *
*  not by itself cause the resulting executable to be covered by the         *
*  GNU Lesser General Public License. This exception does not however        *
*  invalidate any other reasons why the executable file might be             *
*  covered by the GNU Lesser General Public License.                         *
*                                                                            *
*  OpenFlipper is distributed in the hope that it will be useful,            *
*  but WITHOUT ANY WARRANTY; without even the implied warranty of            *
*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the             *
*  GNU Lesser General Public License for more details.                       *
*                                                                            *
*  You should have received a copy of the GNU LesserGeneral Public           *
*  License along with OpenFlipper. If not,                                   *
*  see <http://www.gnu.org/licenses/>.                                       *
*                                                                            *
33 34 35
\*===========================================================================*/

/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
36 37 38 39 40
*                                                                            *
*   $Revision$                                                       *
*   $LastChangedBy$                                                *
*   $Date$                     *
*                                                                            *
41
\*===========================================================================*/
Jan Möbius's avatar
 
Jan Möbius committed
42

43 44
#ifndef BASEINTERFACE_HH
#define BASEINTERFACE_HH
Jan Möbius's avatar
 
Jan Möbius committed
45

46 47 48
#include <QtGui>
#include <QMenuBar>
#include <OpenFlipper/common/Types.hh>
49

50 51 52 53 54 55 56
/** \file BaseInterface.hh
*
* OpenFlippers main plugin Interface \ref baseInterfacePage.
*/
 

/** \brief Interface class from which all plugins have to be created.
57
  *
Jan Möbius's avatar
 
Jan Möbius committed
58
  * You have to implement at least name and description for your plugin.
59
  * All other functions and signals are optional. If you want to implement or use
Jan Möbius's avatar
 
Jan Möbius committed
60
  * them just add them to your plugin header.
61
  *
62 63 64 65
  * See \ref pluginProgramming for a tutorial on plugin programming.
  *
  * Also see \ref dataFlow diagrams for a detailed overview of
  * OpenFlipper's data flow and interface function calls.
Jan Möbius's avatar
 
Jan Möbius committed
66 67
 */
class BaseInterface {
68

69 70 71 72
   //===========================================================================
    /** @name Initialization
    * @{ */
   //===========================================================================
73

74 75
  private slots:
      /**  \brief Initialize Plugin
76
       *
Jan Möbius's avatar
 
Jan Möbius committed
77
       *   This slot is called if the plugin is loaded and has to be initialized. All initialization stuff
Jan Möbius's avatar
Jan Möbius committed
78 79
       *   in this slot has to stay inside the plugin, no external signals are allowed here (and will be ignored).
       *   Don't create any objects via pluginfunctions here. Use the pluginsInitialized() slot for external
Jan Möbius's avatar
Jan Möbius committed
80
       *   initialization. After execution of this slot your plugin should be fully functional.
81
       *   Only gui elements may be uninitialized and should be created in pluginsInitialized().
Jan Möbius's avatar
 
Jan Möbius committed
82 83
      */
      virtual void initializePlugin() {};
84

Jan Möbius's avatar
 
Jan Möbius committed
85
      /**  \brief Initialize Plugin step 2
86
       *
Jan Möbius's avatar
 
Jan Möbius committed
87 88 89 90
       *   This slot is called if all plugins are loaded and the core is ready. Here you can create objects,
       *   set Textures and everything which will involve signals to the core.
      */
      virtual void pluginsInitialized() {};
91 92


93 94 95 96 97 98 99 100 101 102
  /** @} */

  //===========================================================================
  /** @name Object/View updates
  * @{ */
  //===========================================================================

  signals :
    /** \brief Update current view in Main Application
      *
Jan Möbius's avatar
Jan Möbius committed
103 104 105
      *  Emit this Signal if the viewer widget in the main application should update the current view.
      *  If you do an updatedObject the core will trigger an update itself and you don't have to care
      *  about it.
106 107 108
    */
    virtual void updateView() {};

Jan Möbius's avatar
Jan Möbius committed
109
    /** \brief An object has been changed or added by this plugin
110
      *
111
      *  Emit this Signal, if you updated any part of an object.\n
Jan Möbius's avatar
Jan Möbius committed
112
      *  If you changed the element itself (geometry, topology,..) you also have to emit this signal.\n
113
      *  Dont emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!
Jan Möbius's avatar
Jan Möbius committed
114
      *  Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.
115
      *
Jan Möbius's avatar
Jan Möbius committed
116
      *  The parameter has to be the id of the object or -1 if refering to all or deleted objects.
117 118 119
      */
    virtual void updatedObject(int ) {};

Dirk Wilden's avatar
Dirk Wilden committed
120 121 122 123 124 125 126 127 128 129 130 131
    /** \brief An object has been changed or added by this plugin
      *
      *  Emit this Signal, if you updated any part of an object.\n
      *  If you changed the element itself (geometry, topology,..) you also have to emit this signal.\n
      *  Dont emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!
      *  Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.
      *
      * @param _identifier id of the object or -1 if refering to all or deleted objects.
      * @param _type the type states which part of the object (topology, selection, ..) has to be updated
      */
    virtual void updatedObject(int /*_identifier*/, const UpdateType /*_type*/) {};
    
132
    /** \brief A scenegraph node has been shown or hidden
133
      *
134
      *  Emit this Signal, if you changed the visibility of a scenegraph node directly (not via object->show/hide).
135
      *  This is required to reset the near and far plane for the viewers to provide
136
      *  an optimal view. Use the id of the object the node is attached to or -1 if it is not connected to an object.
137 138
      *
      */
139
    virtual void nodeVisibilityChanged( int /*_identifier*/ ) {};
140
   
141 142
  private slots:

Jan Möbius's avatar
Jan Möbius committed
143
    /**  \brief An object has been updated by another plugin
144
      *
Jan Möbius's avatar
Jan Möbius committed
145
      *   This slot is called by the main aplication if the number or status of existing objects changed or if
146
      *   an existing object has been changed. This could mean, that objects are added or deleted
Jan Möbius's avatar
Jan Möbius committed
147
      *   or that an existing object with the given id has been modified.
148 149 150
      *   If you store local information about one of these Objects, you should check if its still valid!\n
      *   Dont emit BaseInterface::updatedObject(int) in this slot as this causes an endless Loop!!
      *   You dont need to call updateView as the core triggers a redraw itself.
151
      *  @param _identifier Identifier of the updated/new object or -1 if one is deleted.
152 153 154
    */
    virtual void slotObjectUpdated( int /*_identifier*/ ) {};

Dirk Wilden's avatar
Dirk Wilden committed
155 156 157 158 159 160 161 162 163 164 165 166 167
    /**  \brief An object has been updated by another plugin
      *
      *   This slot is called by the main aplication if the number or status of existing objects changed or if
      *   an existing object has been changed. This could mean, that objects are added or deleted
      *   or that an existing object with the given id has been modified.
      *   If you store local information about one of these Objects, you should check if its still valid!\n
      *   Dont emit BaseInterface::updatedObject(int) in this slot as this causes an endless Loop!!
      *   You dont need to call updateView as the core triggers a redraw itself.
      *  @param _identifier Identifier of the updated/new object or -1 if one is deleted.
      *  @param _type the type states which part of the object (topology, selection, ..) had been updated
    */
    virtual void slotObjectUpdated( int /*_identifier*/, const UpdateType /*_type*/ ) {};

168
    /**  \brief Called if the whole scene is cleared
Jan Möbius's avatar
Jan Möbius committed
169 170 171
      *
      * This slot is called if the main application cleared the whole scene. No objects will remain in memory
      * and all destructors of the objects are called before this signal is emitted.
172 173 174 175 176 177
      *
      */
    virtual void slotAllCleared( ) {};

      /**  \brief The active object has changed
      *
178 179 180 181
      *   This slot is called by the main aplication if the currentselection of an object has changed.\n
      *   This means that the selection of source / target objects has changed.
      *   Addisionally you get the id of the object that has been changed or -1 if all objects
      *   have been modified.
182
    */
183 184 185 186 187 188 189 190 191 192
    virtual void slotObjectSelectionChanged( int /*_identifier*/ ) {};

    /** \brief An object has been shown or hidden
      *
      *  This slot is called if an objecct is shown or hidden.
      *  The id of the object is given as a parameter.
      *  If multiple or all objects have changed, the id will be -1.
      *
      */
    virtual void slotVisibilityChanged( int /*_identifier*/ ) {};
193

Jan Möbius's avatar
Jan Möbius committed
194 195 196 197 198 199 200 201
    /**  \brief Object properties have been changed
      *
      *  This slot is called if the object properties (e.g. name ) have changed
      *  The id of the object is given as a parameter.
      *  If multiple or all objects have changed, the id will be -1.
      *
    */
    virtual void slotObjectPropertiesChanged( int /*_identifier*/ ) {};
202 203 204 205 206 207 208 209 210
    
    /** \brief View has changed
      *
      * This slot is called when the view in one of the viewers changed
      * ( Viewing direction/viewer position )
      * !! Be carefull to not change the view in this slot !!
      * !! This will of course lead to an endless loop !!
    */
    virtual void slotViewChanged() {};
Jan Möbius's avatar
Jan Möbius committed
211

212 213 214 215 216 217 218 219
  /** @} */

  //===========================================================================
  /** @name Plugin identification
  * @{ */
  //===========================================================================
  public :

Jan Möbius's avatar
Jan Möbius committed
220
    /** \brief Return a name for the plugin
221 222 223 224 225 226 227 228 229 230
      *
      * This Function has to return the name of the plugin.
    */
    virtual QString name() = 0;

    /** \brief Return a description of what the plugin is doing
      *
      * This function has to return a basic description of the plugin
      */
    virtual QString description() = 0;
231 232 233 234 235 236 237 238 239

  public slots:
      /** \brief Return a version string for your plugin
       *
       * This function will be used to determin the current version of your plugin.
       * Should have the form x.x.x ( you do not need to give that many subversions )
       */
      virtual QString version() { return QString("-1"); };

240
  signals:
241

242
      /**  \brief Set a description for a public slot
243
       *
244 245 246 247 248 249 250
       *   public slots of each plugin are automaticly available for scripting. \n
       *   Use this Signal to add a description for your slot so that everyone knows what it is used for. \n
       *
       *   @param _slotName the name of the slot
       *   @param _slotDescription a description for the slot
       *   @param _parameters list of parameters
       *   @param _descriptions list of descriptions for the parameters (_descriptions[i] corresponds to _parameters[i])
Jan Möbius's avatar
 
Jan Möbius committed
251
      */
252 253
      virtual void setSlotDescription(QString     /*_slotName*/,    QString     /*_slotDescription*/,
                                      QStringList /*_parameters*/, QStringList /*_descriptions*/) {};
254

255 256 257 258 259 260 261 262 263 264
  /** @} */

  private slots :

    /** This function is called when the application exits or when your plugin is about to be unloaded.
      * Here you can clean up your plugin, delete local variables...
      */
    virtual void exit(){};

    /** Using this function you can inform the core that your plugin can run without creating a widget.
Jan Möbius's avatar
Jan Möbius committed
265
      * If your plugin does not implement this function, it will not be loaded in scripting mode without gui.
266 267 268 269 270 271 272 273
      * You dont have to do anything in this function.
      */
    virtual void noguiSupported( ) {} ;

  public :

    /// Destructor
    virtual ~BaseInterface() {};
274

Jan Möbius's avatar
 
Jan Möbius committed
275 276
};

277 278 279 280 281

/** \page baseInterfacePage Base Interface
The BaseInterface has to be used by every plugin in OpenFlipper. As the minimum a plugin
has to implement the BaseInterface::name() and BaseInterface::description() functions from this interface.

Jan Möbius's avatar
Jan Möbius committed
282 283 284 285 286 287 288 289
To use the BaseInterface:
<ul>
<li> include BaseInterface.hh in your plugins header file
<li> derive your plugin from the class BaseInterface
<li> add Q_INTERFACES(BaseInterface) to your plugin class 
<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them except BaseInterface::description() and BaseInterface::name() )
</ul>

290
\section Plugin Initialization
Jan Möbius's avatar
Jan Möbius committed
291 292 293
BaseInterface provides two functions to initialize a plugin. The first function is BaseInterface::initializePlugin().
This function is called immediatly after the plugin has been connected with OpenFlipper. When a plugin is
loaded, all signals and slots from the used interfaces are connected to the core. After this, the
294 295 296
BaseInterface::initializePlugin() slot is called. In this slot you can initialize your plugin.
The order how plugins are loaded is not fixed. So you should not rely or communicate with other plugins
in this slot. \n
Jan Möbius's avatar
Jan Möbius committed
297
After all plugins are loaded, the slot  BaseInterface::pluginsInitialized() is called for each plugin. All
298 299 300
other plugins are now available and you can setup your userinterface components in this slot.
The following graphic shows the initialization of a plugin.
\image html startupProcess.jpg
301 302 303

*/

304
Q_DECLARE_INTERFACE(BaseInterface,"OpenFlipper.BaseInterface/1.0")
305

Jan Möbius's avatar
 
Jan Möbius committed
306
#endif // BASEINTERFACE_HH