OpenWalnut  1.4.0
WCustomWidgetEventHandler.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WCUSTOMWIDGETEVENTHANDLER_H
00026 #define WCUSTOMWIDGETEVENTHANDLER_H
00027 
00028 #include <boost/signals2/signal.hpp>
00029 
00030 #include <osgGA/GUIEventAdapter>
00031 #include <osgGA/GUIEventHandler>
00032 
00033 #include "../common/math/linearAlgebra/WVectorFixed.h"
00034 #include "../common/WLogger.h"
00035 #include "WCustomWidget.h"
00036 
00037 /**
00038  * An event handler for a custom widget which eases interaction with GUIEvents within your module. Without you need to write your
00039  * own event handler and register it. However if you still need your own event handler you might consider subclassing from this
00040  * one. Basically there are two ways of getting notified of GUIEvents. First you can connect a member function to events or you
00041  * can overwrite member functions of this class to handle specific events.
00042  *
00043  * Use boost::bind and the subscribeXY methods to connect a member function of your module to a specific GUIEvent. Please note
00044  * that this is now called in context of the GUI thread and that you need to take care of threadsafety by yourself.
00045  *
00046  * Use the corresponding handleXY() member functions if you still need a custom event handler. But take care that you may need to
00047  * set the WCustomWidgetEventHandler::m_preselection event-mask accordingly within the constructor then.
00048  *
00049  * In case you might not know what the specific parameters of the handle function represent you might have luck looking into the
00050  * OpenSceneGraph documentation http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs within the GUIEventAdapter
00051  * class.
00052  */
00053 class WCustomWidgetEventHandler : public osgGA::GUIEventHandler
00054 {
00055 public:
00056     /**
00057      * Constructor.
00058      *
00059      * \param widget The custom widget for which events should be handled.
00060      */
00061     explicit WCustomWidgetEventHandler( WCustomWidget::SPtr widget );
00062 
00063     /**
00064      * The OSG calls this function whenever a new event has occured.
00065      *
00066      * \param ea Event class for storing GUI events such as mouse or keyboard interation etc.
00067      *
00068      * \return true if the event was handled.
00069      */
00070     bool handle( const osgGA::GUIEventAdapter& ea, osgGA::GUIActionAdapter& /* aa */ );
00071 
00072     /**
00073      * Short hand type for signal signature of PUSH, RELEASE and DOUBLECLICK event.
00074      */
00075     typedef boost::signals2::signal< void ( WVector2f, int ) >                           ButtonSignalType;
00076 
00077     /**
00078      * Short hand type for signal signature of DRAG event.
00079      */
00080     typedef boost::signals2::signal< void ( WVector2f, unsigned int ) >                  DragSignalType;
00081 
00082     /**
00083      * Short hand type for signal signature of MOVE event.
00084      */
00085     typedef boost::signals2::signal< void ( WVector2f ) >                                MoveSignalType;
00086 
00087     /**
00088      * Short hand type for signal signature of SCROLL event.
00089      */
00090     typedef boost::signals2::signal< void ( GUIEvents::ScrollingMotion, float, float ) > ScrollSignalType;
00091 
00092     /**
00093      * Short hand type for signal signature of FRAME, PEN_PROXIMITY_ENTER, -LEAVE, CLOSE_WINDOW, QUIT_APPLICATION and USER event.
00094      */
00095     typedef boost::signals2::signal< void ( void ) >                                     TriggerSignalType;
00096 
00097     /**
00098      * Short hand type for signal signature of KEYDOWN and KEYUP event.
00099      */
00100     typedef boost::signals2::signal< void ( int, unsigned int ) >                        KeySignalType;
00101 
00102     /**
00103      * Short hand type for signal signature of RESIZE event.
00104      */
00105     typedef boost::signals2::signal< void ( int, int, int, int ) >                       ResizeSignalType;
00106 
00107     /**
00108      * Short hand type for signal signature of PEN_PRESSURE event.
00109      */
00110     typedef boost::signals2::signal< void ( float ) >                                    PenPressureSignalType;
00111 
00112     /**
00113      * Short hand type for signal signature of PEN_ORIENTATION event.
00114      */
00115     typedef boost::signals2::signal< void ( const osg::Matrix ) >                        PenOrientationSignalType;
00116 
00117     /**
00118      * Registers a function slot to PUSH events. Whenever the event occurs, the slot is called with current parameters.
00119      *
00120      * \param slot Function object having the appropriate signature according to the used SignalType.
00121      */
00122     virtual void subscribePush( ButtonSignalType::slot_type slot );
00123 
00124     /**
00125      * Registers a function slot to RELEASE events. Whenever the event occurs, the slot is called with current parameters.
00126      * \copydetails subscribePush()
00127      */
00128     virtual void subscribeRelease( ButtonSignalType::slot_type slot );
00129 
00130     /**
00131      * Registers a function slot to DOUBLECLICK events.
00132      * \copydetails subscribePush()
00133      */
00134     virtual void subscribeDoubleclick( ButtonSignalType::slot_type slot );
00135 
00136     /**
00137      * Registers a function slot to DRAG events.
00138      * \copydetails subscribePush()
00139      */
00140     virtual void subscribeDrag( DragSignalType::slot_type slot );
00141 
00142     /**
00143      * Registers a function slot to MOVE events.
00144      *
00145      * \copydetails subscribePush()
00146      */
00147     virtual void subscribeMove( MoveSignalType::slot_type slot );
00148 
00149     /**
00150      * Registers a function slot to KEYDOWN events.
00151      *
00152      * \copydetails subscribePush()
00153      */
00154     virtual void subscribeKeydown( KeySignalType::slot_type slot );
00155 
00156     /**
00157      * Registers a function slot to KEYUP events.
00158      *
00159      * \copydetails subscribePush()
00160      */
00161     virtual void subscribeKeyup( KeySignalType::slot_type slot );
00162 
00163     /**
00164      * Registers a function slot to FRAME events.
00165      *
00166      * \copydetails subscribePush()
00167      */
00168     virtual void subscribeFrame( TriggerSignalType::slot_type );
00169 
00170     /**
00171      * Registers a function slot to RESIZE events.
00172      *
00173      * \copydetails subscribePush()
00174      */
00175     virtual void subscribeResize( ResizeSignalType::slot_type slot );
00176 
00177     /**
00178      * Registers a function slot to SCROLL events.
00179      *
00180      * \copydetails subscribePush()
00181      */
00182     virtual void subscribeScroll( ScrollSignalType::slot_type slot );
00183 
00184     /**
00185      * Registers a function slot to PEN_PRESSURE events.
00186      *
00187      * \copydetails subscribePush()
00188      */
00189     virtual void subscribePenPressure( PenPressureSignalType::slot_type slot );
00190 
00191     /**
00192      * Registers a function slot to PEN_ORIENTATION events.
00193      *
00194      * \copydetails subscribePush()
00195      */
00196     virtual void subscribePenOrientation( PenOrientationSignalType::slot_type slot );
00197 
00198     /**
00199      * Registers a function slot to PEN_PROXIMITY_ENTER events.
00200      *
00201      * \copydetails subscribePush()
00202      */
00203     virtual void subscribePenProximityEnter( TriggerSignalType::slot_type slot );
00204 
00205     /**
00206      * Registers a function slot to PEN_PROXIMITY_LEAVE events.
00207      *
00208      * \copydetails subscribePush()
00209      */
00210     virtual void subscribePenProximityLeave( TriggerSignalType::slot_type slot );
00211 
00212     /**
00213      * Registers a function slot to CLOSE_WINDOW events.
00214      *
00215      * \copydetails subscribePush()
00216      */
00217     virtual void subscribeCloseWindow( TriggerSignalType::slot_type slot );
00218 
00219     /**
00220      * Registers a function slot to QUIT_APPLICATION events.
00221      * \copydetails subscribePush()
00222      */
00223     virtual void subscribeQuitApplication( TriggerSignalType::slot_type slot );
00224 
00225     /**
00226      * Registers a function slot to USER events.
00227      * \copydetails subscribePush()
00228      */
00229     virtual void subscribeUser( TriggerSignalType::slot_type slot );
00230 
00231     /**
00232      * Called whenever the PUSH event occurs.
00233      *
00234      * \param mousePos Current mouse position in X and Y.
00235      * \param button The involved mouse button. See http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs
00236      * GUIEventAdapter class for values.
00237      */
00238     virtual void handlePush( WVector2f mousePos, int button );
00239 
00240     /**
00241      * Called whenever the RELEASE event occurs.
00242      * \copydetails handlePush()
00243      */
00244     virtual void handleRelease( WVector2f mousePos, int button );
00245 
00246     /**
00247      * Called whenever the DOUBLECLICK event occurs.
00248      * \copydetails handlePush()
00249      */
00250     virtual void handleDoubleclick( WVector2f mousePos, int button );
00251 
00252     /**
00253      * Called whenever the DRAG event occurs.
00254      *
00255      * \param mousePos Current mouse position in X and Y.
00256      * \param buttonMask The pushed mouse buttons as a mask. See http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs
00257      * GUIEventAdapter class for values.
00258      */
00259     virtual void handleDrag( WVector2f mousePos, int buttonMask );
00260 
00261     /**
00262      * Called whenever the MOVE event occurs.
00263      *
00264      * \param mousePos Current mouse position in X and Y.
00265      */
00266     virtual void handleMove( WVector2f mousePos );
00267 
00268     /**
00269      * Called whenever the KEYDOWN event occurs.
00270      *
00271      * \param keyID The pressed key. See http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs GUIEventAdapter
00272      * class for values.
00273      * \param modKeyMask Additional function keys pressed.
00274      */
00275     virtual void handleKeydown( int keyID, unsigned int modKeyMask );
00276 
00277     /**
00278      * Called whenever the KEYUP event occurs.
00279      *
00280      * \param keyID The released key. See http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs GUIEventAdapter
00281      * class for values.
00282      * \param modKeyMask Additional function keys pressed.
00283      */
00284     virtual void handleKeyup( int keyID, unsigned int modKeyMask );
00285 
00286     /**
00287      * Called whenever the FRAME event occurs. This is every new frame.
00288      */
00289     virtual void handleFrame();
00290 
00291     /**
00292      * Called whenever the widget has resized.
00293      *
00294      * \param xPos Position in X.
00295      * \param yPos Position in Y.
00296      * \param width Width of the widget.
00297      * \param height Height of the widget.
00298      */
00299     virtual void handleResize( int xPos, int yPos, int width, int height );
00300 
00301     /**
00302      * Called whenever the SCROLL event occurs.
00303      *
00304      * \param motion Scrolling motion. See http://www.openscenegraph.org/documentation/OpenSceneGraphReferenceDocs GUIEventAdapter class for values.
00305      * \param deltaX Delta in X.
00306      * \param deltaY Delta in Y.
00307      */
00308     virtual void handleScroll( GUIEvents::ScrollingMotion motion, float deltaX, float deltaY );
00309 
00310     /**
00311      * Called whenever the PEN_PRESSURE event occurs.
00312      *
00313      * \param pressure pressure of the pen.
00314      */
00315     virtual void handlePenPressure( float pressure );
00316 
00317     /**
00318      * Called whenever the PEN_ORIENTATION event occurs.
00319      *
00320      * \param orientation the orientation of the pen.
00321      */
00322     virtual void handlePenOrientation( const osg::Matrix orientation );
00323 
00324     /**
00325      * Called whenever the PEN_PROXIMITY_ENTER event occurs.
00326      */
00327     virtual void handlePenProximityEnter();
00328 
00329     /**
00330      * Called whenever the PEN_PROXIMITY_LEAVE event occurs.
00331      */
00332     virtual void handlePenProximityLeave();
00333 
00334     /**
00335      * Called whenever the CLOSE_WINDOW event occurs.
00336      */
00337     virtual void handleCloseWindow();
00338 
00339     /**
00340      * Called whenever the QUIT_APPLICATION event occurs.
00341      */
00342     virtual void handleQuitApplication();
00343 
00344     /**
00345      * Called whenever the USER event occurs.
00346      */
00347     virtual void handleUser();
00348 
00349 protected:
00350     /**
00351      * Signal used for notification of the PUSH event.
00352      */
00353     ButtonSignalType         m_sigPush;
00354 
00355     /**
00356      * Signal used for notification of the RELEASE event.
00357      */
00358     ButtonSignalType         m_sigRelease;
00359 
00360     /**
00361      * Signal used for notification of the DOUBLECLICK event.
00362      */
00363     ButtonSignalType         m_sigDoubleclick;
00364 
00365     /**
00366      * Signal used for notification of the DRAG event.
00367      */
00368     DragSignalType           m_sigDrag;
00369 
00370     /**
00371      * Signal used for notification of the MOVE event.
00372      */
00373     MoveSignalType           m_sigMove;
00374 
00375     /**
00376      * Signal used for notification of the KEYDOWN event.
00377      */
00378     KeySignalType            m_sigKeydown;
00379 
00380     /**
00381      * Signal used for notification of the KEYUP event.
00382      */
00383     KeySignalType            m_sigKeyup;
00384 
00385     /**
00386      * Signal used for notification of the FRAME event.
00387      */
00388     TriggerSignalType        m_sigFrame;
00389 
00390     /**
00391      * Signal used for notification of the RESIZE event.
00392      */
00393     ResizeSignalType         m_sigResize;
00394 
00395     /**
00396      * Signal used for notification of the SCROLL event.
00397      */
00398     ScrollSignalType         m_sigScroll;
00399 
00400     /**
00401      * Signal used for notification of the PEN_PRESSURE event.
00402      */
00403     PenPressureSignalType    m_sigPenPressure;
00404 
00405     /**
00406      * Signal used for notification of the PEN_ORIENTATION event.
00407      */
00408     PenOrientationSignalType m_sigPenOrientation;
00409 
00410     /**
00411      * Signal used for notification of the PEN_PROXIMITY_ENTER event.
00412      */
00413     TriggerSignalType        m_sigPenProximityEnter;
00414 
00415     /**
00416      * Signal used for notification of the PEN_PROXIMITY_LEAVE event.
00417      */
00418     TriggerSignalType        m_sigPenProximityLeave;
00419 
00420     /**
00421      * Signal used for notification of the CLOSE_WINDOW event.
00422      */
00423     TriggerSignalType        m_sigCloseWindow;
00424 
00425     /**
00426      * Signal used for notification of the QUIT_APPLICATION event.
00427      */
00428     TriggerSignalType        m_sigQuitApplication;
00429 
00430     /**
00431      * Signal used for notification of the USER event.
00432      */
00433     TriggerSignalType        m_sigUser;
00434 
00435     /**
00436      * Reference to the WCustomWidget for which event handling should performed.
00437      */
00438     WCustomWidget::SPtr m_widget;
00439 
00440     /**
00441      * Binary mask describing which events should be used for notification or subscription.
00442      */
00443     unsigned int m_preselection;
00444 
00445     /**
00446      * Logger instance for comfortable error logging. Simply use errorLog() << "my error".
00447      *
00448      * \return the logger stream.
00449      */
00450     wlog::WStreamedLogger errorLog() const;
00451 };
00452 
00453 #endif  // WCUSTOMWIDGETEVENTHANDLER_H