BaseInterface.hh 13 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
45
46
47
48




//
// C++ Interface: BasePlugin
//
49
// Description:
Jan Möbius's avatar
   
Jan Möbius committed
50
51
52
53
54
//
//
// Author: Jan Moebius <jan_moebius@web.de>, (C) 2007
//

55
56
#ifndef BASEINTERFACE_HH
#define BASEINTERFACE_HH
Jan Möbius's avatar
   
Jan Möbius committed
57
58
59
60

 #include <QtGui>
 #include <QMenuBar>
 #include <OpenFlipper/common/Types.hh>
61

Jan Möbius's avatar
   
Jan Möbius committed
62
 /** \brief Interface class from which all plugins have to be created.
63
  *
Jan Möbius's avatar
   
Jan Möbius committed
64
  * You have to implement at least name and description for your plugin.
65
  * All other functions and signals are optional. If you want to implement or use
Jan Möbius's avatar
   
Jan Möbius committed
66
  * them just add them to your plugin header.
67
  *
68
69
70
71
  * 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
72
73
 */
class BaseInterface {
74

75
76
77
78
   //===========================================================================
    /** @name Initialization
    * @{ */
   //===========================================================================
79

80
81
  private slots:
      /**  \brief Initialize Plugin
82
       *
Jan Möbius's avatar
   
Jan Möbius committed
83
       *   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
84
85
       *   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
86
       *   initialization. After execution of this slot your plugin should be fully functional.
87
       *   Only gui elements may be uninitialized and should be created in pluginsInitialized().
Jan Möbius's avatar
   
Jan Möbius committed
88
89
      */
      virtual void initializePlugin() {};
90

Jan Möbius's avatar
   
Jan Möbius committed
91
      /**  \brief Initialize Plugin step 2
92
       *
Jan Möbius's avatar
   
Jan Möbius committed
93
94
95
96
       *   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() {};
97
98


99
100
101
102
103
104
105
106
107
108
  /** @} */

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

  signals :
    /** \brief Update current view in Main Application
      *
Jan Möbius's avatar
Jan Möbius committed
109
110
111
      *  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.
112
113
114
    */
    virtual void updateView() {};

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

Dirk Wilden's avatar
Dirk Wilden committed
126
127
128
129
130
131
132
133
134
135
136
137
    /** \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*/) {};
    
138
    /** \brief A scenegraph node has been shown or hidden
139
      *
140
      *  Emit this Signal, if you changed the visibility of a scenegraph node directly (not via object->show/hide).
141
      *  This is required to reset the near and far plane for the viewers to provide
142
      *  an optimal view. Use the id of the object the node is attached to or -1 if it is not connected to an object.
143
144
      *
      */
145
    virtual void nodeVisibilityChanged( int /*_identifier*/ ) {};
146
   
147
148
  private slots:

Jan Möbius's avatar
Jan Möbius committed
149
    /**  \brief An object has been updated by another plugin
150
      *
Jan Möbius's avatar
Jan Möbius committed
151
      *   This slot is called by the main aplication if the number or status of existing objects changed or if
152
      *   an existing object has been changed. This could mean, that objects are added or deleted
Jan Möbius's avatar
Jan Möbius committed
153
      *   or that an existing object with the given id has been modified.
154
155
156
      *   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.
157
      *  @param _identifier Identifier of the updated/new object or -1 if one is deleted.
158
159
160
    */
    virtual void slotObjectUpdated( int /*_identifier*/ ) {};

Dirk Wilden's avatar
Dirk Wilden committed
161
162
163
164
165
166
167
168
169
170
171
172
173
    /**  \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*/ ) {};

174
    /**  \brief Called if the whole scene is cleared
Jan Möbius's avatar
Jan Möbius committed
175
176
177
      *
      * 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.
178
179
180
181
182
183
      *
      */
    virtual void slotAllCleared( ) {};

      /**  \brief The active object has changed
      *
184
185
186
187
      *   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.
188
    */
189
190
191
192
193
194
195
196
197
198
    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*/ ) {};
199

Jan Möbius's avatar
Jan Möbius committed
200
201
202
203
204
205
206
207
    /**  \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*/ ) {};
208
209
210
211
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 )
      * !! 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
217

218
219
220
221
222
223
224
225
  /** @} */

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

Jan Möbius's avatar
Jan Möbius committed
226
    /** \brief Return a name for the plugin
227
228
229
230
231
232
233
234
235
236
      *
      * 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;
237
238
239
240
241
242
243
244
245

  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"); };

246
  signals:
247

248
      /**  \brief Set a description for a public slot
249
       *
250
251
252
253
254
255
256
       *   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
257
      */
258
259
      virtual void setSlotDescription(QString     /*_slotName*/,    QString     /*_slotDescription*/,
                                      QStringList /*_parameters*/, QStringList /*_descriptions*/) {};
260

261
262
263
264
265
266
267
268
269
270
  /** @} */

  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
271
      * If your plugin does not implement this function, it will not be loaded in scripting mode without gui.
272
273
274
275
276
277
278
279
      * You dont have to do anything in this function.
      */
    virtual void noguiSupported( ) {} ;

  public :

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

Jan Möbius's avatar
   
Jan Möbius committed
281
282
};

283
Q_DECLARE_INTERFACE(BaseInterface,"OpenFlipper.BaseInterface/1.0")
284

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