PickingInterface.hh 10.7 KB
Newer Older
1
/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
2 3
*                                                                            *
*                              OpenFlipper                                   *
Martin Schultz's avatar
Martin Schultz committed
4 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 33 34 35 36 37 38
 *           Copyright (c) 2001-2015, RWTH-Aachen University                 *
 *           Department of Computer Graphics and Multimedia                  *
 *                          All rights reserved.                             *
 *                            www.openflipper.org                            *
 *                                                                           *
 *---------------------------------------------------------------------------*
 * This file is part of OpenFlipper.                                         *
 *---------------------------------------------------------------------------*
 *                                                                           *
 * Redistribution and use in source and binary forms, with or without        *
 * modification, are permitted provided that the following conditions        *
 * are met:                                                                  *
 *                                                                           *
 * 1. Redistributions of source code must retain the above copyright notice, *
 *    this list of conditions and the following disclaimer.                  *
 *                                                                           *
 * 2. Redistributions in binary form must reproduce the above copyright      *
 *    notice, this list of conditions and the following disclaimer in the    *
 *    documentation and/or other materials provided with the distribution.   *
 *                                                                           *
 * 3. Neither the name of the copyright holder nor the names of its          *
 *    contributors may be used to endorse or promote products derived from   *
 *    this software without specific prior written permission.               *
 *                                                                           *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS       *
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED *
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A           *
 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER *
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,  *
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,       *
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR        *
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF    *
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING      *
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS        *
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.              *
Jan Möbius's avatar
Jan Möbius committed
39
*                                                                            *
40 41 42
\*===========================================================================*/

/*===========================================================================*\
Jan Möbius's avatar
Jan Möbius committed
43 44 45 46 47
*                                                                            *
*   $Revision$                                                       *
*   $LastChangedBy$                                                *
*   $Date$                     *
*                                                                            *
48
\*===========================================================================*/
Jan Möbius's avatar
 
Jan Möbius committed
49

Jan Möbius's avatar
 
Jan Möbius committed
50 51
#ifndef PICKINGINTERFACE_HH
#define PICKINGINTERFACE_HH
Jan Möbius's avatar
 
Jan Möbius committed
52

Matthias Möller's avatar
Matthias Möller committed
53 54
 #include <OpenFlipper/common/Types.hh>

Matthias Möller's avatar
Matthias Möller committed
55 56
  #include <QtWidgets>

Jan Möbius's avatar
 
Jan Möbius committed
57
 #include <QMenuBar>
Matthias Möller's avatar
Matthias Möller committed
58

Jan Möbius's avatar
 
Jan Möbius committed
59

Jan Möbius's avatar
Jan Möbius committed
60 61 62 63 64 65 66 67


/** \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
68
  *
Jan Möbius's avatar
Jan Möbius committed
69 70 71 72 73
  * \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.
74 75
  *
  * Read tutorial \ref ex3 for an example of how to use mouse picking.
Jan Möbius's avatar
 
Jan Möbius committed
76 77 78
 */
class PickingInterface {
   signals :
Jan Möbius's avatar
 
Jan Möbius committed
79 80
      /** \brief Add a new picking mode to the examiner
       *
Jan Möbius's avatar
 
Jan Möbius committed
81 82
       * @param _mode Identifier of Picking mode or "Separator" to add a Separator
      */
83
      virtual void addPickMode( const std::string& _mode) {};
Jan Möbius's avatar
 
Jan Möbius committed
84

Jan Möbius's avatar
 
Jan Möbius committed
85
      /** \brief Add a new picking mode to the examiner which will be invisible
Jan Möbius's avatar
 
Jan Möbius committed
86
       *
Jan Möbius's avatar
 
Jan Möbius committed
87
       * The added PickMode will not appear in the context menus Picking menu.
Jan Möbius's avatar
Jan Möbius committed
88
       * 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
89
       * the picking mode provided here.
Jan Möbius's avatar
 
Jan Möbius committed
90
       *
Jan Möbius's avatar
 
Jan Möbius committed
91 92
       * @param _mode Identifier of Picking mode or "Separator" to add a Separator
      */
93
      virtual void addHiddenPickMode( const std::string& _mode ) {};
Jan Möbius's avatar
 
Jan Möbius committed
94

Dirk Wilden's avatar
Dirk Wilden committed
95
      /** \brief Set the cursor of the given PickMode
Jan Möbius's avatar
 
Jan Möbius committed
96
       *
Dirk Wilden's avatar
Dirk Wilden committed
97
       * Set the cursor that should be used inside the pickMode
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 _cursor the new cursor
Jan Möbius's avatar
 
Jan Möbius committed
101
      */
102
      virtual void setPickModeCursor( const std::string& _mode , QCursor _cursor ) {};
Dirk Wilden's avatar
Dirk Wilden committed
103 104

      /** \brief Set mouse tracking for the given PickMode
Jan Möbius's avatar
 
Jan Möbius committed
105
       *
Dirk Wilden's avatar
Dirk Wilden committed
106 107
       * 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
108
       *
Dirk Wilden's avatar
Dirk Wilden committed
109 110
       * @param _mode Identifier of Picking mode
       * @param _mouseTracking new state of mouseTracking
Jan Möbius's avatar
 
Jan Möbius committed
111
      */
112
      virtual void setPickModeMouseTracking( const std::string& _mode , bool _mouseTracking ) {};
Dirk Wilden's avatar
Dirk Wilden committed
113

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

Jan Möbius's avatar
Jan Möbius committed
123
      /** \brief Removes the additional toolbar of the given PickMode
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
124 125 126 127 128
       *
       * Set the additional toolbar that should be shown in the pickMode
       *
       * @param _mode Identifier of Picking mode
      */
129
      virtual void removePickModeToolbar( const std::string& _mode ) {};
Jan Möbius's avatar
Dennis:  
Jan Möbius committed
130

131 132
     
  private slots:
Jan Möbius's avatar
 
Jan Möbius committed
133
      /**  \brief The pickingMode has changed
Jan Möbius's avatar
 
Jan Möbius committed
134
       *
Jan Möbius's avatar
 
Jan Möbius committed
135 136 137
       * 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
138
      virtual void slotPickModeChanged( const std::string& _mode) {};
Jan Möbius's avatar
 
Jan Möbius committed
139 140 141

   public :

Jan Möbius's avatar
 
Jan Möbius committed
142 143
      /// Destructor
      virtual ~PickingInterface() {};
Jan Möbius's avatar
 
Jan Möbius committed
144

Jan Möbius's avatar
 
Jan Möbius committed
145 146
};

Jan Möbius's avatar
Jan Möbius committed
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 239 240 241 242 243 244 245 246 247 248
/** \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
249
Q_DECLARE_INTERFACE(PickingInterface,"OpenFlipper.PickingInterface/1.1")
Jan Möbius's avatar
 
Jan Möbius committed
250

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