ToolboxInterface.hh 6.74 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-2014 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
\*===========================================================================*/
42

43 44
#ifndef TOOLBOXINTERFACE_HH
#define TOOLBOXINTERFACE_HH
45

Matthias Möller's avatar
Matthias Möller committed
46 47 48 49 50 51 52

#if QT_VERSION >= 0x050000 
  #include <QtWidgets>
#else
  #include <QtGui>
#endif

53 54 55
#include <QMenuBar>
#include <QStringList>
#include <OpenFlipper/common/Types.hh>
56

57 58 59 60
/** \file ToolboxInterface.hh
*
* Interface for adding per plugin toolboxes to OpenFlippers UI.\ref toolboxInterfacePage
*/
61

62

63
 /**
Mike Kremer's avatar
Mike Kremer committed
64
  * \brief Plugins can add its own toolbox to the main widget's toolbox area by using this interface.
65
  *
66 67 68 69
  * \ref toolboxInterfacePage "Detailed description" 
  * \n
  *
  * This Interface can be used by plugins which will provide a toolbox widget.
Jan Möbius's avatar
Jan Möbius committed
70
  * Each Plugin can create own Widgets in the toolbox area. Just create your widget and then add it with \n
Jan Möbius's avatar
Jan Möbius committed
71
  * emit addToolbox( QString  _name  , QWidget* _widget ) \n
72 73
  * to the user interface. You can create extra signals and slots in your Plugin.
  * These can be connected between your toolbox and your plugin.\n
74 75 76
  *
  * See our tutorials \ref ex2 and \ref ex3 for an example of to add custom toolboxes to
  * OpenFlipper.
Mike Kremer's avatar
Mike Kremer committed
77
  */
78 79 80 81 82 83 84 85 86 87
class ToolboxInterface {

   private slots :

   public :

      /// Destructor
      virtual ~ToolboxInterface() {};

    signals :
Dirk Wilden's avatar
Dirk Wilden committed
88

89 90
      /** \brief Add a toolbox widget to the gui with the given name
       *
Jan Möbius's avatar
Jan Möbius committed
91
       * This signal adds a toolbox widget to the toolbox area on the right.
Jan Möbius's avatar
Jan Möbius committed
92 93 94
       *
       * @param _name   Visible name of the toolbox
       * @param _widget Pointer to the toolbox widget
95
       */
Jan Möbius's avatar
Jan Möbius committed
96
      virtual void addToolbox( QString  _name  , QWidget* _widget ) {};
97

Jan Möbius's avatar
Jan Möbius committed
98
      /** \brief Add a toolbox widget to the gui with the given name and an icon
Dirk Wilden's avatar
Dirk Wilden committed
99
       *
Jan Möbius's avatar
Jan Möbius committed
100
       * This signal adds a toolbox widget to the toolbox area on the right. And sets an icon for it
Jan Möbius's avatar
Jan Möbius committed
101 102 103 104
       *
       * @param _name   Visible name of the toolbox
       * @param _widget Pointer to the toolbox widget
       * @param _icon   Icon for the toolbox
Dirk Wilden's avatar
Dirk Wilden committed
105
       */
Jan Möbius's avatar
Jan Möbius committed
106
      virtual void addToolbox( QString  _name  , QWidget* _widget, QIcon* _icon) {};
107 108
};

109 110 111 112 113 114


/** \page toolboxInterfacePage Toolbox Interface
\image html ToolboxInterface.png

The ToolboxInterface can be used by plugins to add widgets to the list of toolboxes in OpenFlippers
Jan Möbius's avatar
Jan Möbius committed
115
UI. The toolboxes are located left or right of the GL viewer (See image).
116 117 118 119 120 121 122 123 124 125 126

The list can be hidden by pressing Ctrl + t.

To use the ToolboxInterface:
<ul>
<li> include ToolboxInterface.hh in your plugins header file
<li> derive your plugin from the class ToolboxInterface
<li> add Q_INTERFACES(ToolboxInterface) 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)
</ul>

127
Usually you should implement the BaseInterface::pluginsInitialized() function from BaseInterface. In this function you can setup
Jan Möbius's avatar
Jan Möbius committed
128
your toolbox ( some kind of QWidget, can also be any widget created with QT-designer). Optionally you can also
129 130 131 132
add an icon to the toolbox. 

The following code shows a simple example to create an empty toolbox.
\code 
Jan Möbius's avatar
Jan Möbius committed
133
void ExamplePlugin::pluginsInitialized()
134 135 136 137 138
{
  // Create the Toolbox Widget
  QWidget* toolBox = new QWidget();
  
  // Create an icon which is shown along with the toolbox
Jan Möbius's avatar
Jan Möbius committed
139
  QIcon* toolIcon = new QIcon(OpenFlipper::Options::iconDirStr()+OpenFlipper::Options::dirSeparator()+"exampleIcon.png");
140 141
  
  // Tell the core to include the new toolbox widget with the name Simple Smoother, a pointer to the widget and a pointer to the icon
Jan Möbius's avatar
Jan Möbius committed
142
  emit addToolbox( tr("Example Plugin Toolbox") , toolBox, toolIcon );
143 144 145 146 147 148 149 150
}
\endcode

Signals and slots of your toolbox (e.g. from a QPushButton inside it) can be directly connected to signals and slots in
your plugin. Therefore the embedding of the widget into the toolbox list is fully transparent.

*/

151
Q_DECLARE_INTERFACE(ToolboxInterface,"OpenFlipper.ToolboxInterface/1.1")
152 153

#endif // TOOLBOXINTERFACE_HH