BaseInterface.hh 20.2 KB
 Jan Möbius committed Aug 05, 2009 1 /*===========================================================================*\  Jan Möbius committed Nov 25, 2010 2 3 * * * OpenFlipper *  Jan Möbius committed Jan 26, 2011 4 * Copyright (C) 2001-2011 by Computer Graphics Group, RWTH Aachen *  Jan Möbius committed Nov 25, 2010 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 . * * *  Jan Möbius committed Aug 05, 2009 33 34 35 \*===========================================================================*/ /*===========================================================================*\  Jan Möbius committed Nov 25, 2010 36 37 38 39 40 * * * $Revision$ * * $LastChangedBy$ * * $Date$ * * *  Jan Möbius committed Aug 05, 2009 41 \*===========================================================================*/  Jan Möbius committed Aug 29, 2008 42   Jan Möbius committed Sep 19, 2008 43 44 #ifndef BASEINTERFACE_HH #define BASEINTERFACE_HH  Jan Möbius committed Aug 29, 2008 45   46 47 48 #include #include #include  Jan Möbius committed Sep 19, 2008 49   Jan Möbius committed Feb 24, 2011 50   51 52 53 54 /** \file BaseInterface.hh * * OpenFlippers main plugin Interface \ref baseInterfacePage. */  Jan Möbius committed Feb 25, 2011 55   56 57  /** \brief Interface class from which all plugins have to be created.  Jan Möbius committed Sep 19, 2008 58  *  Jan Möbius committed Aug 29, 2008 59  * You have to implement at least name and description for your plugin.  Jan Möbius committed Sep 19, 2008 60  * All other functions and signals are optional. If you want to implement or use  Jan Möbius committed Mar 16, 2011 61 62  * them just add them to your plugin header. A detailed description of this interface * can be found in the \ref baseInterfacePage .  Jan Möbius committed Feb 18, 2009 63  *  Mike Kremer committed Feb 04, 2009 64 65 66 67  * 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 committed Aug 29, 2008 68 69  */ class BaseInterface {  Jan Möbius committed Sep 19, 2008 70   Jan Möbius committed Feb 03, 2009 71 72  //=========================================================================== /** @name Initialization  Jan Möbius committed Feb 14, 2012 73 74 75  * @{ * \anchor BaseInterfaceInitialization * */  Jan Möbius committed Feb 03, 2009 76  //===========================================================================  Jan Möbius committed Sep 19, 2008 77   Jan Möbius committed Feb 03, 2009 78 79  private slots: /** \brief Initialize Plugin  Jan Möbius committed Sep 19, 2008 80  *  Jan Möbius committed Aug 29, 2008 81  * This slot is called if the plugin is loaded and has to be initialized. All initialization stuff  Jan Möbius committed Feb 25, 2009 82  * in this slot has to stay inside the plugin, no external signals are allowed here (and will be ignored).  Jan Möbius committed Feb 25, 2011 83  * Don't create any objects via PluginFunctions here. Use the pluginsInitialized() slot for external  Jan Möbius committed Feb 03, 2009 84  * initialization. After execution of this slot your plugin should be fully functional.  Jan Möbius committed Sep 19, 2008 85  * Only gui elements may be uninitialized and should be created in pluginsInitialized().  Jan Möbius committed Aug 29, 2008 86 87  */ virtual void initializePlugin() {};  Jan Möbius committed Sep 19, 2008 88   Jan Möbius committed Aug 29, 2008 89  /** \brief Initialize Plugin step 2  Jan Möbius committed Sep 19, 2008 90  *  Jan Möbius committed Feb 03, 2012 91  * This slot is called if all plugins are loaded and the core is ready. Afterwards you can already send  Jan Möbius committed Feb 14, 2012 92  * signals to other plugins and the core (e.g. adding global textures). \note Do not create objects via addEmpty  Jan Möbius committed Feb 03, 2012 93  * or load objects in this slot, as the rendering system is not ready yet.  Jan Möbius committed Aug 29, 2008 94 95  */ virtual void pluginsInitialized() {};  Jan Möbius committed Sep 19, 2008 96 97   Jan Möbius committed Feb 03, 2009 98 99 100 101  /** @} */ //=========================================================================== /** @name Object/View updates  Jan Möbius committed Feb 24, 2011 102 103 104 105  * @{ * \anchor BaseInterfaceUpdateSlots * */  Jan Möbius committed Feb 03, 2009 106 107 108 109 110  //=========================================================================== signals : /** \brief Update current view in Main Application *  Jan Möbius committed Feb 25, 2009 111 112 113  * 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.  Jan Möbius committed Feb 03, 2009 114 115 116  */ virtual void updateView() {};  Jan Möbius committed Feb 25, 2009 117  /** \brief An object has been changed or added by this plugin  Jan Möbius committed Feb 03, 2009 118  *  119  * Emit this Signal, if you updated any part of an object.\n  Jan Möbius committed Feb 25, 2009 120  * If you changed the element itself (geometry, topology,..) you also have to emit this signal.\n  Jan Möbius committed Feb 24, 2011 121  * Don't emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!  Jan Möbius committed Feb 25, 2009 122  * Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.  Jan Möbius committed Feb 24, 2011 123  * For performance reasons try to always give the id and not -1!  Jan Möbius committed Feb 03, 2009 124  *  Jan Möbius committed Oct 26, 2011 125  * @param _objectId Id of the object or -1 if referring to all or deleted objects.  Jan Möbius committed Feb 03, 2009 126  */  Jan Möbius committed Feb 24, 2011 127  virtual void updatedObject(int _objectId) {};  Jan Möbius committed Feb 03, 2009 128   Dirk Wilden committed Mar 09, 2010 129 130 131 132  /** \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  Jan Möbius committed Feb 25, 2011 133  * Don't emit this Signal in BaseInterface::slotObjectUpdated() as this causes an endless Loop!!  Dirk Wilden committed Mar 09, 2010 134  * Give the id of the new object as parameter or -1 if you updated all objects or deleted an object.  Jan Möbius committed Feb 24, 2011 135  * For performance reasons try to always give the id and not -1!  Dirk Wilden committed Mar 09, 2010 136  *  Jan Möbius committed Feb 25, 2011 137  * @param _identifier id of the object or -1 if referring to all or deleted objects.  Dirk Wilden committed Mar 09, 2010 138 139  * @param _type the type states which part of the object (topology, selection, ..) has to be updated */  Jan Möbius committed Jan 12, 2012 140  virtual void updatedObject(int _identifier, const UpdateType& _type) {};  Dirk Wilden committed Mar 09, 2010 141   Jan Möbius committed Dec 08, 2009 142  /** \brief A scenegraph node has been shown or hidden  Jan Möbius committed Feb 18, 2009 143  *  Jan Möbius committed Dec 08, 2009 144  * Emit this Signal, if you changed the visibility of a scenegraph node directly (not via object->show/hide).  Jan Möbius committed Feb 18, 2009 145  * This is required to reset the near and far plane for the viewers to provide  Jan Möbius committed Dec 08, 2009 146  * an optimal view. Use the id of the object the node is attached to or -1 if it is not connected to an object.  Jan Möbius committed Feb 18, 2009 147 148  * */  Jan Möbius committed Feb 24, 2011 149  virtual void nodeVisibilityChanged( int _identifier ) {};  Jan Möbius committed Sep 15, 2011 150   Jan Möbius committed Feb 03, 2009 151 152  private slots:  Jan Möbius committed Feb 25, 2009 153  /** \brief An object has been updated by another plugin  Jan Möbius committed Feb 03, 2009 154  *  Jan Möbius committed Feb 25, 2011 155  * This slot is called by the main application if the number or status of existing objects changed or if  Jan Möbius committed Feb 03, 2009 156  * an existing object has been changed. This could mean, that objects are added or deleted  Jan Möbius committed Feb 25, 2009 157  * or that an existing object with the given id has been modified.  Jan Möbius committed Feb 03, 2009 158  * If you store local information about one of these Objects, you should check if its still valid!\n  Jan Möbius committed Feb 25, 2011 159 160  * Don't emit BaseInterface::updatedObject(int) in this slot as this causes an endless Loop!! * You don't need to call updateView as the core triggers a redraw itself.  161  * @param _identifier Identifier of the updated/new object or -1 if one is deleted.  Jan Möbius committed Feb 03, 2009 162  */  Jan Möbius committed Feb 24, 2011 163  virtual void slotObjectUpdated( int _identifier ) {};  Jan Möbius committed Feb 03, 2009 164   Dirk Wilden committed Mar 09, 2010 165 166  /** \brief An object has been updated by another plugin *  Jan Möbius committed Feb 25, 2011 167  * This slot is called by the main application if the number or status of existing objects changed or if  Dirk Wilden committed Mar 09, 2010 168 169 170  * 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  Jan Möbius committed Feb 25, 2011 171 172  * Don't emit BaseInterface::updatedObject(int) in this slot as this causes an endless Loop!! * You don't need to call updateView as the core triggers a redraw itself.  Dirk Wilden committed Mar 09, 2010 173 174 175  * @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 */  Jan Möbius committed Jan 12, 2012 176  virtual void slotObjectUpdated( int _identifier, const UpdateType& _type ) {};  Dirk Wilden committed Mar 09, 2010 177   Jan Möbius committed Feb 03, 2009 178  /** \brief Called if the whole scene is cleared  Jan Möbius committed Feb 25, 2009 179 180 181  * * 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.  Jan Möbius committed Feb 03, 2009 182 183 184 185 186 187  * */ virtual void slotAllCleared( ) {}; /** \brief The active object has changed *  Jan Möbius committed Feb 25, 2011 188  * This slot is called by the main application if the current selection of an object has changed.\n  189  * This means that the selection of source / target objects has changed.  Jan Möbius committed Feb 25, 2011 190  * Additionally you get the id of the object that has been changed or -1 if all objects  191  * have been modified.  Jan Möbius committed Feb 03, 2009 192  */  Jan Möbius committed Feb 24, 2011 193  virtual void slotObjectSelectionChanged( int _identifier ) {};  194 195 196  /** \brief An object has been shown or hidden *  Jan Möbius committed Feb 25, 2011 197  * This slot is called if an object is shown or hidden.  198 199 200 201  * The id of the object is given as a parameter. * If multiple or all objects have changed, the id will be -1. * */  Jan Möbius committed Feb 24, 2011 202  virtual void slotVisibilityChanged( int _identifier ) {};  Jan Möbius committed Feb 03, 2009 203   Jan Möbius committed Mar 18, 2009 204 205 206 207 208 209 210  /** \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. * */  Jan Möbius committed Feb 24, 2011 211  virtual void slotObjectPropertiesChanged( int _identifier ) {};  Jan Möbius committed Sep 10, 2009 212 213 214 215 216  /** \brief View has changed * * This slot is called when the view in one of the viewers changed * ( Viewing direction/viewer position )  Jan Möbius committed Feb 25, 2011 217  * !! Be careful to not change the view in this slot !!  Jan Möbius committed Sep 10, 2009 218 219 220  * !! This will of course lead to an endless loop !! */ virtual void slotViewChanged() {};  Jan Möbius committed Mar 18, 2009 221   Jan Möbius committed Sep 15, 2011 222 223 224 225 226  /** \brief A viewer changed its draw mode * * @param _viewerId Id of the viewer that changed its draw mode */ virtual void slotDrawModeChanged(int _viewerId) {};  Jan Möbius committed Feb 03, 2009 227 228 229 230 231 232 233 234  /** @} */ //=========================================================================== /** @name Plugin identification * @{ */ //=========================================================================== public :  Jan Möbius committed Feb 25, 2009 235  /** \brief Return a name for the plugin  Jan Möbius committed Feb 03, 2009 236 237 238 239 240 241 242 243 244 245  * * 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;  Jan Möbius committed Sep 19, 2008 246 247 248 249  public slots: /** \brief Return a version string for your plugin *  Jan Möbius committed Feb 25, 2011 250  * This function will be used to determine the current version of your plugin.  Jan Möbius committed Sep 19, 2008 251 252 253 254  * Should have the form x.x.x ( you do not need to give that many subversions ) */ virtual QString version() { return QString("-1"); };  Jan Möbius committed Feb 03, 2009 255  signals:  Jan Möbius committed Sep 19, 2008 256   Jan Möbius committed Feb 03, 2009 257  /** \brief Set a description for a public slot  Jan Möbius committed Sep 19, 2008 258  *  Jan Möbius committed Feb 25, 2011 259  * public slots of each plugin are automatically available for scripting. \n  Jan Möbius committed Feb 03, 2009 260 261 262 263 264 265  * 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 committed Aug 29, 2008 266  */  Jan Möbius committed Feb 24, 2011 267 268  virtual void setSlotDescription(QString _slotName , QString _slotDescription, QStringList _parameters , QStringList _descriptions) {};  Jan Möbius committed Sep 19, 2008 269   Jan Möbius committed Nov 29, 2011 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284  /** @} */ //=========================================================================== /** @name Renderer control * @{ */ //=========================================================================== signals: /** \brief Set a renderer for the given viewer * * @param _viewer Id of the viewer to set the renderer for * @param _rendererName Name of the renderer to be used */ virtual void setRenderer(unsigned int _viewer, QString _rendererName) {};  Jan Möbius committed Jan 04, 2012 285 286 287 288 289 290 291  /** \brief Get the current renderer for the given viewer * * @param _viewer Id of the viewer to set the renderer for * @param _rendererName Name of the renderer that is currently active */ virtual void getCurrentRenderer(unsigned int _viewer, QString& _rendererName) {};  Jan Möbius committed Feb 03, 2009 292 293 294 295 296 297 298 299 300 301  /** @} */ 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 committed Feb 25, 2009 302  * If your plugin does not implement this function, it will not be loaded in scripting mode without gui.  Jan Möbius committed Feb 25, 2011 303  * You don't have to do anything in this function.  Jan Möbius committed Feb 03, 2009 304 305 306 307 308 309 310  */ virtual void noguiSupported( ) {} ; public : /// Destructor virtual ~BaseInterface() {};  Jan Möbius committed Sep 19, 2008 311   Jan Möbius committed Aug 29, 2008 312 313 };  314 315 316 317 318  /** \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 committed Feb 23, 2011 319 320 321 322 323 324 325 326 To use the BaseInterface:
 Jan Möbius committed Feb 25, 2011 327 \section baseInterfacePluginInitialization Plugin Initialization  Jan Möbius committed Feb 14, 2012 328 BaseInterface provides two functions to initialize a plugin \ref BaseInterfaceInitialization. The first function is BaseInterface::initializePlugin().  Jan Möbius committed Feb 25, 2011 329 This function is called immediately after the plugin has been connected with OpenFlipper. When a plugin is  Jan Möbius committed Feb 23, 2011 330 loaded, all signals and slots from the used interfaces are connected to the core. After this, the  Jan Möbius committed Feb 24, 2011 331 332 333 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 committed Feb 23, 2011 334 After all plugins are loaded, the slot BaseInterface::pluginsInitialized() is called for each plugin. All  Jan Möbius committed Feb 25, 2011 335 other plugins are now available and you can setup your user interface components in this slot.  Jan Möbius committed Feb 24, 2011 336 The following graphic shows the initialization of a plugin.  Jan Möbius committed Feb 14, 2012 337 \image html OpenFlipperStartup.png  338   Jan Möbius committed Feb 24, 2011 339 \section baseInterfaceObjectUpdateNotification Object Update Notification  Jan Möbius committed Feb 24, 2011 340 341 342 343 344 345 The objects in OpenFlippers scene are stored and managed in OpenFlippers core. If a plugin changes one of the objects, it has to notify the core about that change. In turn OpenFlipper will then notify all other plugins about this change. This functionality is provided by the signals and slots for \ref BaseInterfaceUpdateSlots "update handling" . \image html updateObject.jpg  Jan Möbius committed Jan 12, 2012 346 If you change data you have to emit one of BaseInterface::updatedObject(int) or BaseInterface::updatedObject(int,const UpdateType&).  Jan Möbius committed Feb 24, 2011 347 \n  Jan Möbius committed Jan 12, 2012 348 BaseInterface::updatedObject(int) forces an update of the whole object while BaseInterface::updatedObject(int,const UpdateType&)  Jan Möbius committed Feb 24, 2011 349 can be restricted to a part of the object ( Geometry,Selection, ... ; see UpdateType ) and is therefore faster and should be preferred.  Jan Möbius committed Feb 24, 2011 350 351  Both signals get the id of the object that has been updated or -1 if all should be updated( you should not use -1 if you know what object changed!).  Jan Möbius committed Feb 24, 2011 352   Jan Möbius committed Jan 12, 2012 353 If the signal is emitted, the core calls BaseInterface::slotObjectUpdated( int , const UpdateType& ) of every plugin. You can  Jan Möbius committed Feb 24, 2011 354 355 implement this slot if you need to react on object changes.  Jan Möbius committed Feb 24, 2011 356 357 358 359 360 361 362 363 364 365 After all plugins have been informed, the scene will be redrawn. For more details about the UpdateType read the documentation about UpdateType and \ref DefaultUpdateTypes "predefined update types". A description for adding custom update types at runtime is available \ref UpdateTypeFunctions "here". It is also possible to insert custom nodes into the scenegraph. If you changed these nodes, you also have to inform the core. This is achieved by the BaseInterface::nodeVisibilityChanged() function. As nodes they are usually attached to objects in the scene, you should pass the id of the object to the function or -1 if its a global node (which should not be used!). If the complete scene gets cleared, the slot BaseInterface::slotAllCleared() will be executed after all objects have been removed from the scene.  Jan Möbius committed Mar 16, 2011 366 A more fine grained information about objects added or removed from the scene is available via the \ref loadSaveInterfacePage .  Jan Möbius committed Feb 24, 2011 367 368 369 370  There are three additional slots that are called by the core, if the object selection(source/target BaseInterface::slotObjectSelectionChanged() ), the object visibility(Show/Hide BaseInterface::slotVisibilityChanged()) or other properties changed (e.g. name BaseInterface::slotObjectPropertiesChanged() )  Jan Möbius committed Feb 24, 2011 371 372 373 374 375 376 Remarks:
 Jan Möbius committed Feb 24, 2011 377 \section baseInterfaceSceneUpdateNotification Scene Update Notifications  Jan Möbius committed Feb 24, 2011 378 379 380 381  OpenFlipper manages the scene updates in its core. If objects get updated the scene will be automatically redrawn. Nevertheless, you can force an update of the scene by emitting the signal BaseInterface::updateView().  Jan Möbius committed Feb 25, 2011 382 383 \image html updateView.jpg  Jan Möbius committed Feb 25, 2011 384 If the view (viewer position /viewing direction) has been changed, the slot BaseInterface::slotViewChanged() will be called. Be carefull, not to  Jan Möbius committed Feb 24, 2011 385 386 change the view in this function or you get an endless loop!  Jan Möbius committed Feb 24, 2011 387 \section baseInterfaceManagementFunctions Management Functions  Jan Möbius committed Feb 24, 2011 388 There are some basic functions for managing plugins. The BaseInterface::description() function can be used  Jan Möbius committed Feb 25, 2011 389 to provide a description for the plugin which will be printed along with the plugin name. The BaseInterface::name()  Jan Möbius committed Feb 24, 2011 390 391 392 393 394 395 396 function has to return the name of the plugin. This name will also be used inside the scripting system. Additionally it is possible to provide a plugin version number with BaseInterface::version(). OpenFlippers scripting system can use all public slots defined in your plugin. If it should also provide a small text description for your functions, you could set them with BaseInterface::setSlotDescription(). Even if you do not implement scripting functions in your plugin, the core will then be able to provide this information to the user.  Jan Möbius committed Feb 24, 2011 397   Jan Möbius committed Feb 24, 2011 398 399 400 401 Along with the scripting, OpenFlipper provides a batch mode, running without any user interface. If your plugin will work without an user interface (e.g. only scripting functions), you can define a slot BaseInterface::noguiSupported(). This empty slot is used to tell the core, that the plugin can work in batch mode. Otherwise it will not be loaded when running a batch file.  Jan Möbius committed Feb 24, 2011 402   403 404 */  Jan Möbius committed Oct 16, 2008 405 Q_DECLARE_INTERFACE(BaseInterface,"OpenFlipper.BaseInterface/1.0")  Jan Möbius committed Sep 19, 2008 406   Jan Möbius committed Aug 29, 2008 407 #endif // BASEINTERFACE_HH