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

43 44
#ifndef TOOLBOXINTERFACE_HH
#define TOOLBOXINTERFACE_HH
45

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

51 52 53 54
/** \file ToolboxInterface.hh
*
* Interface for adding per plugin toolboxes to OpenFlippers UI.\ref toolboxInterfacePage
*/
55

56

57
 /**
Mike Kremer's avatar
Mike Kremer committed
58
  * \brief Plugins can add its own toolbox to the main widget's toolbox area by using this interface.
59
  *
60 61 62 63
  * \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
64
  * 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
65
  * emit addToolbox( QString  _name  , QWidget* _widget ) \n
66 67
  * 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
68 69 70
  *
  * 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
71
  */
72 73 74 75 76 77 78 79 80 81
class ToolboxInterface {

   private slots :

   public :

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

    signals :
Dirk Wilden's avatar
Dirk Wilden committed
82

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

Jan Möbius's avatar
Jan Möbius committed
92
      /** \brief Add a toolbox widget to the gui with the given name and an icon
Dirk Wilden's avatar
Dirk Wilden committed
93
       *
Jan Möbius's avatar
Jan Möbius committed
94
       * 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
95 96 97 98
       *
       * @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
99
       */
Jan Möbius's avatar
Jan Möbius committed
100
      virtual void addToolbox( QString  _name  , QWidget* _widget, QIcon* _icon) {};
101 102
};

103 104 105 106 107 108


/** \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
109
UI. The toolboxes are located left or right of the GL viewer (See image).
110 111 112 113 114 115 116 117 118 119 120

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>

121
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
122
your toolbox ( some kind of QWidget, can also be any widget created with QT-designer). Optionally you can also
123 124 125 126
add an icon to the toolbox. 

The following code shows a simple example to create an empty toolbox.
\code 
127
void ExamplePlugin::pluginsInitialized()
128 129 130 131 132
{
  // Create the Toolbox Widget
  QWidget* toolBox = new QWidget();
  
  // Create an icon which is shown along with the toolbox
133
  QIcon* toolIcon = new QIcon(OpenFlipper::Options::iconDirStr()+OpenFlipper::Options::dirSeparator()+"exampleIcon.png");
134 135
  
  // 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
136
  emit addToolbox( tr("Example Plugin Toolbox") , toolBox, toolIcon );
137 138 139 140 141 142 143 144
}
\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.

*/

145
Q_DECLARE_INTERFACE(ToolboxInterface,"OpenFlipper.ToolboxInterface/1.1")
146 147

#endif // TOOLBOXINTERFACE_HH