Commit 53ccd59e authored by Jan Möbius's avatar Jan Möbius

PickingInterface Documentation

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11145 383ad7c9-94d9-4d36-a494-682f7c89f535
parent 93cff168
......@@ -198,10 +198,10 @@ from the scenegraph. So if this function is invoked, the object still exists. Al
If you want to know if the whole scene got cleared, use BaseInterface::slotAllCleared( ).
\section Usage
\section loadSaveInterface_usage Usage
To use the LoadSaveInterface:
<ul>
<li> include LoadSaveInterface in your plugins header file
<li> include LoadSaveInterface.hh in your plugins header file
<li> derive your plugin from the class LoadSaveInterface
<li> add Q_INTERFACES(LoadSaveInterface) 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)
......
......@@ -134,9 +134,9 @@ inside the viewers.
You can add handlers for these mouse events in your plugin. Remember that all plugins receive these signals.\n
The picking mode is only a global mode which is devided into several other picking modes that can be managed
through the PickingInterface. If you react on mouse events from picking mode, you should check if the current
picking mode is yours.
The picking action is only a global mode which is divided into several other picking modes that can be managed
through the PickingInterface. If you react on mouse events, you should check if the current
picking mode is yours and of course define such a mode for your plugin.
\code
void MousePlugin::slotMouseEvent(QMouseEvent* _event) {
......
......@@ -47,10 +47,20 @@
#include <QMenuBar>
#include <OpenFlipper/common/Types.hh>
/**
* \brief Allow access to picking functions.
/** \file PickingInterface.hh
*
* Interface Class which allows access to picking functions. \ref pickingInterfacePage
*/
/** \brief Allow access to picking functions.
*
* Interface Class which allows access to picking functions.
* \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.
*
* Read tutorial \ref ex3 for an example of how to use mouse picking.
*/
......@@ -60,17 +70,17 @@ class PickingInterface {
*
* @param _mode Identifier of Picking mode or "Separator" to add a Separator
*/
virtual void addPickMode( const std::string /*_mode*/) {};
virtual void addPickMode( const std::string _mode) {};
/** \brief Add a new picking mode to the examiner which will be invisible
*
* The added PickMode will not appear in the context menus Picking menu.
* You have to provide a button or menuentry yourself if you want to switch to
* You have to provide a button or menu entry yourself if you want to switch to
* the picking mode provided here.
*
* @param _mode Identifier of Picking mode or "Separator" to add a Separator
*/
virtual void addHiddenPickMode( const std::string /*_mode*/ ) {};
virtual void addHiddenPickMode( const std::string _mode ) {};
/** \brief Set the cursor of the given PickMode
*
......@@ -79,7 +89,7 @@ class PickingInterface {
* @param _mode Identifier of Picking mode
* @param _cursor the new cursor
*/
virtual void setPickModeCursor( const std::string /*_mode*/ , QCursor /*_cursor*/ ) {};
virtual void setPickModeCursor( const std::string _mode , QCursor _cursor ) {};
/** \brief Set mouse tracking for the given PickMode
*
......@@ -89,24 +99,24 @@ class PickingInterface {
* @param _mode Identifier of Picking mode
* @param _mouseTracking new state of mouseTracking
*/
virtual void setPickModeMouseTracking( const std::string /*_mode*/ , bool /*_mouseTracking*/ ) {};
virtual void setPickModeMouseTracking( const std::string _mode , bool _mouseTracking ) {};
/** \brief Set the additinal toolbar of the given PickMode
/** \brief Set the additional toolbar of the given PickMode
*
* Set the additional toolbar that should be shown in the pickMode
*
* @param _mode Identifier of Picking mode
* @param _toolbar the toolbar
*/
virtual void setPickModeToolbar( const std::string /*_mode*/ , QToolBar * /*_toolbar*/ ) {};
virtual void setPickModeToolbar( const std::string _mode , QToolBar * _toolbar ) {};
/** \brief Removes the additinal toolbar of the given PickMode
/** \brief Removes the additional toolbar of the given PickMode
*
* Set the additional toolbar that should be shown in the pickMode
*
* @param _mode Identifier of Picking mode
*/
virtual void removePickModeToolbar( const std::string /*_mode*/ ) {};
virtual void removePickModeToolbar( const std::string _mode ) {};
private slots:
......@@ -115,7 +125,7 @@ class PickingInterface {
* This slot is called if the user changes the current picking mode
* @param _mode Identifier of Picking mode
*/
virtual void slotPickModeChanged( const std::string& /*_mode*/) {};
virtual void slotPickModeChanged( const std::string& _mode) {};
public :
......@@ -124,6 +134,108 @@ class PickingInterface {
};
/** \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>
*/
Q_DECLARE_INTERFACE(PickingInterface,"OpenFlipper.PickingInterface/1.1")
#endif // PICKINGINTERFACE_HH
......@@ -57,7 +57,6 @@ The following groups of Interfaces are available:
BackupInterface
FileInterface
IniInterface
PickingInterface
ProcessInterface
TextureInterface
ViewInterface
......@@ -71,12 +70,6 @@ This page gives an overview over the available interfaces which control other pa
\image html TextureInterface.png
Allows your plugin to provide a texture. ( TextureInterface )
\subsection PickingPlugin Mouse Picking / Pick Modes
\image html PickingInterface.png
Handle mouse picking in your plugin ( PickingInterface )
\subsection FilePlugin File Interface
\image html FileInterface.png
Provides functions to read and write custom filetypes ( FileInterface )
......@@ -124,6 +117,13 @@ This Interface is used by plugins which will provide their own options by
integrating an options widget into OpenFlipper's options window ( \ref optionsInterfacePage ).
\n
\subpage pickingInterfacePage
\n
\image html PickingInterface.png
\n
Handle pick modes in your plugin ( \ref pickingInterfacePage )
\n
\subpage statusbarInterfacePage
\image html StatusbarInterface.png
This interface is used to display messages in the status bar or adding widgets to it ( \ref statusbarInterfacePage ).
......@@ -175,9 +175,19 @@ This page shows interfaces which could be used to get data from input devices.
This interface is used to deliver mouse events to a plugin ( \ref mouseInterfacePage ).\n
\n
\subpage pickingInterfacePage
\n
\image html PickingInterface.png
\n
Handle pick modes in your plugin ( \ref pickingInterfacePage )
\n
\subpage keyInterfacePage
\n
\image html keyInterface.png
\n
You have to implement this interface if you want to get key events in your plugin ( \ref keyInterfacePage ).\n
\n
*/
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment