PickingInterface.hh 10.1 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

Jan Möbius's avatar
 
Jan Möbius committed
43
44
#ifndef PICKINGINTERFACE_HH
#define PICKINGINTERFACE_HH
Jan Möbius's avatar
 
Jan Möbius committed
45
46
47
48

 #include <QtGui>
 #include <QMenuBar>
 #include <OpenFlipper/common/Types.hh>
Jan Möbius's avatar
 
Jan Möbius committed
49

Jan Möbius's avatar
Jan Möbius committed
50
51
52
53
54
55
56
57


/** \file PickingInterface.hh
*
* Interface Class which allows access to picking functions. \ref pickingInterfacePage
*/

/** \brief Allow access to picking functions.
Mike Kremer's avatar
Mike Kremer committed
58
  *
Jan Möbius's avatar
Jan Möbius committed
59
60
61
62
63
  * \ref pickingInterfacePage "Detailed description"
  * \n
  *
  * Using this interface you can add different pick modes to OpenFlipper and
  * separate different mouse Interactions depending on the current mode.
64
65
  *
  * Read tutorial \ref ex3 for an example of how to use mouse picking.
Jan Möbius's avatar
 
Jan Möbius committed
66
67
68
 */
class PickingInterface {
   signals :
Jan Möbius's avatar
 
Jan Möbius committed
69
70
      /** \brief Add a new picking mode to the examiner
       *
Jan Möbius's avatar
 
Jan Möbius committed
71
72
       * @param _mode Identifier of Picking mode or "Separator" to add a Separator
      */
Jan Möbius's avatar
Jan Möbius committed
73
      virtual void addPickMode( const std::string _mode) {};
Jan Möbius's avatar
 
Jan Möbius committed
74

Jan Möbius's avatar
 
Jan Möbius committed
75
      /** \brief Add a new picking mode to the examiner which will be invisible
Jan Möbius's avatar
 
Jan Möbius committed
76
       *
Jan Möbius's avatar
 
Jan Möbius committed
77
       * The added PickMode will not appear in the context menus Picking menu.
Jan Möbius's avatar
Jan Möbius committed
78
       * You have to provide a button or menu entry yourself if you want to switch to
Jan Möbius's avatar
 
Jan Möbius committed
79
       * the picking mode provided here.
Jan Möbius's avatar
 
Jan Möbius committed
80
       *
Jan Möbius's avatar
 
Jan Möbius committed
81
82
       * @param _mode Identifier of Picking mode or "Separator" to add a Separator
      */
Jan Möbius's avatar
Jan Möbius committed
83
      virtual void addHiddenPickMode( const std::string _mode ) {};
Jan Möbius's avatar
 
Jan Möbius committed
84

Dirk Wilden's avatar
Dirk Wilden committed
85
      /** \brief Set the cursor of the given PickMode
Jan Möbius's avatar
 
Jan Möbius committed
86
       *
Dirk Wilden's avatar
Dirk Wilden committed
87
       * Set the cursor that should be used inside the pickMode
Jan Möbius's avatar
 
Jan Möbius committed
88
       *
Dirk Wilden's avatar
Dirk Wilden committed
89
90
       * @param _mode Identifier of Picking mode
       * @param _cursor the new cursor
Jan Möbius's avatar
 
Jan Möbius committed
91
      */
Jan Möbius's avatar
Jan Möbius committed
92
      virtual void setPickModeCursor( const std::string _mode , QCursor _cursor ) {};
Dirk Wilden's avatar
Dirk Wilden committed
93
94

      /** \brief Set mouse tracking for the given PickMode
Jan Möbius's avatar
 
Jan Möbius committed
95
       *
Dirk Wilden's avatar
Dirk Wilden committed
96
97
       * Enable mouseTracking for the given PickMode. When MouseTracking is enabled
       * you receive mouseMove events also when no button is pressed (via MouseInterface)
Jan Möbius's avatar
 
Jan Möbius committed
98
       *
Dirk Wilden's avatar
Dirk Wilden committed
99
100
       * @param _mode Identifier of Picking mode
       * @param _mouseTracking new state of mouseTracking
Jan Möbius's avatar
 
Jan Möbius committed
101
      */
Jan Möbius's avatar
Jan Möbius committed
102
      virtual void setPickModeMouseTracking( const std::string _mode , bool _mouseTracking ) {};
Dirk Wilden's avatar
Dirk Wilden committed
103

Jan Möbius's avatar
Jan Möbius committed
104
      /** \brief Set the additional toolbar of the given PickMode
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
105
106
107
108
109
110
       *
       * Set the additional toolbar that should be shown in the pickMode
       *
       * @param _mode Identifier of Picking mode
       * @param _toolbar the toolbar
      */
Jan Möbius's avatar
Jan Möbius committed
111
      virtual void setPickModeToolbar( const std::string _mode , QToolBar * _toolbar ) {};
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
112

Jan Möbius's avatar
Jan Möbius committed
113
      /** \brief Removes the additional toolbar of the given PickMode
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
114
115
116
117
118
       *
       * Set the additional toolbar that should be shown in the pickMode
       *
       * @param _mode Identifier of Picking mode
      */
Jan Möbius's avatar
Jan Möbius committed
119
      virtual void removePickModeToolbar( const std::string _mode ) {};
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
120

121
122
     
  private slots:
Jan Möbius's avatar
 
Jan Möbius committed
123
      /**  \brief The pickingMode has changed
Jan Möbius's avatar
 
Jan Möbius committed
124
       *
Jan Möbius's avatar
 
Jan Möbius committed
125
126
127
       * This slot is called if the user changes the current picking mode
       * @param _mode Identifier of Picking mode
      */
Jan Möbius's avatar
Jan Möbius committed
128
      virtual void slotPickModeChanged( const std::string& _mode) {};
Jan Möbius's avatar
 
Jan Möbius committed
129
130
131

   public :

Jan Möbius's avatar
 
Jan Möbius committed
132
133
      /// Destructor
      virtual ~PickingInterface() {};
Jan Möbius's avatar
 
Jan Möbius committed
134

Jan Möbius's avatar
 
Jan Möbius committed
135
136
};

Jan Möbius's avatar
Jan Möbius committed
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
/** \page pickingInterfacePage Picking Interface/Mouse Picking/Pick Mode Toolbars
\n
\image html PickingInterface.png
\n


\section pickingInterface_functionality Functionality
OpenFlipper uses several different ActionModes. These include, Light interaction (Changing lights), Move interaction (navigating
through the scene) and the picking interaction. The picking interaction is separated into different pick modes. These modes
are usually defined by plugins and are used to restrict the mouse interaction to one plugin. E.g. if the current picking mode is
"vertex selection", all other plugins that react on mouse events, but are not responsible for the "vertex selection" will ignore
these events.

\section pickingInterface_managing Managing Pick Modes
Pick modes can be created in your plugin initialization. You can add them as visible pick modes (visible in the context menus
of objects) or as hidden pick modes PickingInterface::addHiddenPickMode() ( This should be preferred! ). You can also set
a special cursor that will be used when your pick mode is active via PickingInterface::setPickModeCursor(). If you need
to enable mouse tracking in your mode, you can use PickingInterface::setPickModeMouseTracking(). This will result in mouse events
even if no button is pressed.

\code
// When the plugin gets initialized
void ExamplePlugin::pluginsInitialized() {

 // Add pick mode
 emit addPickMode("ExamplePlugin Pick Mode");

}

// Triggered when the pick mode got changed.
void ExamplePlugin::slotPickModeChanged(const std::string& _mode) {

  // Enable a button depending on the current pick mode
  button_->setEnabled(_mode == "ExamplePlugin Pick Mode");

}

// From MouseInterface
void ExamplePlugin::slotMouseEvent(QMouseEvent* _event) {

  // Check if your pick mode is currently active
  if ( PluginFunctions::pickMode() == "ExamplePlugin Pick Mode" && PluginFunctions::actionMode() == Viewer::PickingMode ) {

    // Do something

  }

}
\endcode

A change of the current pick mode can be detected by the PickingInterface::slotPickModeChanged() function.

\section pickingInterface_toolbars PickMode Toolbars
\n
\image html PickModeToolbar.png
\n
Additionally it is possible to show a special toolbar in OpenFlippers viewer when your pick mode is active. This is especially
Useful, when you can change the interaction type by buttons in the bar, e.g. select vertices or faces. Every time your
pick mode is activated, your toolbar will be visible at the top of the viewer. Use the functions PickingInterface::setPickModeToolbar()
and PickingInterface::removePickModeToolbar() for controlling these toolbars. The embedding is fully transparent so that
you can manage your toolbar and connect signals and slots as usual.

\code
// When the plugin gets initialized
void ExamplePlugin::pluginsInitialized() {

  // Global variable QToolBar* pickToolbar_
  pickToolbar_ = new QToolBar(tr("Example Pickmode Toolbar"));
  pickToolbar_->setAttribute(Qt::WA_AlwaysShowToolTips, true);

  QActionGroup* pickToolBarActions = new QActionGroup(pickToolbar_);

  QAction* action = new QAction(tr("Action"),pickToolBarActions);
  action->setStatusTip(tr("Action description"));
  action->setIcon(QIcon(OpenFlipper::Options::iconDirStr()+OpenFlipper::Options::dirSeparator()+"icon.png") );
  action->setCheckable(true);
  pickToolbar_->addAction(action);

  // Connect to a local slot. The embedding is transparent, so you can connect all your actions and toolbars as usual.
  connect(pickToolBarActions, SIGNAL(triggered(QAction*)), this, SLOT(slotPickToolbarAction(QAction*)) );

  emit setPickModeToolbar ("ExamplePlugin Pick Mode", pickToolbar_);
}
\endcode


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

*/






Dirk Wilden's avatar
Dirk Wilden committed
239
Q_DECLARE_INTERFACE(PickingInterface,"OpenFlipper.PickingInterface/1.1")
Jan Möbius's avatar
 
Jan Möbius committed
240

Jan Möbius's avatar
 
Jan Möbius committed
241
#endif // PICKINGINTERFACE_HH