Main Page   Class Hierarchy   Compound List   All functions   Search  

MouseGrabber Class Reference

Abstract class for mouse interactive objects. More...

Inherited by ManipulatedFrame.

List of all members.

Mouse detection

virtual void checkIfGrabsMouse (int x, int y, const Camera *const camera)=0
bool grabsMouse ()
void setGrabsMouse (const bool flag)

MouseGrabber pool

bool isInMouseGrabberPool () const
void addInMouseGrabberPool ()
void removeFromMouseGrabberPool ()
const QPtrList< MouseGrabber > & MouseGrabberPool ()

Mouse event handlers

The different functions called by the QGLViewer when the MouseGrabber grabsMouse().

virtual void mousePressEvent (QMouseEvent *const, Camera *const)
virtual void mouseDoubleClickEvent (QMouseEvent *const, Camera *const)
virtual void mouseReleaseEvent (QMouseEvent *const, Camera *const)
virtual void mouseMoveEvent (QMouseEvent *const, const Camera *const)
virtual void wheelEvent (QWheelEvent *const, const Camera *const)

Public Methods

 MouseGrabber ()
virtual ~MouseGrabber ()


Detailed Description

Abstract class for mouse interactive objects.

MouseGrabber are object which react to the mouse cursor, usually when it get close to them. Their actual behavior can be arbitrary and has to be defined in a derived class. This class only provides a common interface for all these classes.

All the created MouseGrabber objects are grouped in a MouseGrabberPool(). All the QGLViewers parse this pool, calling the MouseGrabbers' checkIfGrabsMouse() functions to determine if one of the MouseGrabber grabsMouse(). Individual MouseGrabbers can be removed from this pool using removeFromMouseGrabberPool() if you want to (temporarily) disable them.

When a MouseGrabber grabsMouse(), it becomes the QGLViewer::mouseGrabber(). All the mouse events (mousePressEvent(), mouseReleaseEvent(), mouseMoveEvent(), mouseDoubleClickEvent() and wheelEvent()) are then transmitted to the QGLViewer::mouseGrabber() instead of being normally processed.

checkIfGrabsMouse() is still called after each mouse motion to check if the QGLViewer::mouseGrabber() still grabs the mouse.

In order to make MouseGrabber react to mouse events, the mouse tracking option has to be activated in the QGLViewers which want to use MouseGrabbers:

  init() { setMouseTracking(true); }
  
Call QGLViewer::hasMouseTracking() to get the current state of this flag.

The camera parameter of the different functions is a pointer to the Camera used by the QGLViewer which calls the MouseGrabber. It can be used to compute 2D to 3D coordinates conversion using Camera::projectedCoordinatesOf() and Camera::unprojectedCoordinatesOf().

Very complex behaviors can be implemented using this framework: auto-selected objects (no need to press a key to use them), automatic drop-down menus, 3D GUI, spinners using the wheelEvent(), and whatever your imagination creates.

See the mouseGrabber example for an illustration.

Here is for instance a draft version of a movableObject class. Instances of these class can freely be moved on screen using the mouse. A possible application would be movable post-it-like notes.

  class movableObject : public MouseGrabber
  {
    movableObject() : posX(0), posY(0), moved(false) {};

    void checkIfGrabsMouse(int x, int y, const qglviewer::Camera* const)
    {
      // Active in a region of 5 pixel. Criterion should depend on object's shape.
      setGrabsMouse( sqrt((x-posX)*(x-posX) + (y-posY)*(y-posY)) < 5 );
    }

    void mousePressEvent(QMouseEvent *, Camera* const)   { moved = true; }
    void mouseReleaseEvent(QMouseEvent *, Camera* const) { moved = false; }
    
    void mouseMoveEvent(QMouseEvent *e, Camera* const)
    {
      if (moved)
      {
        posX = e->x();
        posY = e->y();
      }
    }

    void draw()
    {
      if (grabsMouse())
        if (moved)
          // Object being moved, maybe a transparent display
        else
          // Visual feedback (highlight) : object ready to be grabbed 
      else
        // Normal display
    }
  };
  


Constructor & Destructor Documentation

MouseGrabber  
 

Adds the created MouseGrabber in the MouseGrabberPool(). grabsMouse() set to false.

virtual ~MouseGrabber   [inline, virtual]
 

Virtual destructor. Removes object from the MouseGrabberPool().


Member Function Documentation

void addInMouseGrabberPool  
 

Adds the MouseGrabber in the MouseGrabberPool(). Note that all MouseGrabber are automatically added in the MouseGrabberPool() by the constructor. Trying to add a MouseGrabber that already isInMouseGrabberPool() has no effect.

Use removeFromMouseGrabberPool() to remove the MouseGrabber from the list, so that it is no longer tested with checkIfGrabsMouse() by the QGLViewer. Use isInMouseGrabberPool() to know the current state of the MouseGrabber.

virtual void checkIfGrabsMouse int    x,
int    y,
const Camera *const    camera
[pure virtual]
 

This is the core function of the MouseGrabber. It has to be overloaded and defined in your derived classes. Its goal is to update the grabsMouse() flag according to the mouse current positon, using setGrabsMouse().

grabsMouse() should be set to true when the mouse cursor is close enough to the MouseGrabber position (or whatever is appropriate). It also must be set to false as soon as the mouse cursor leaves this region in order to release the mouse focus for the other parts of the application.

A typical implementation will look like:

    // (posX,posY) is the position of the MouseGrabber on screen. Here,
    // distance to mouse must be less than 10 pixels to activate the MouseGrabber.
    setGrabsMouse( sqrt((x-posX)*(x-posX) + (y-posY)*(y-posY)) < 10);
    

If the MouseGrabber position is defined in 3D. Project it on screen and then compare the projected coordinates:

    Vec proj = camera->projectedCoordinatesOf(position());
    setGrabsMouse((fabs(x-proj.x) < 5) && (fabs(y-proj.y) < 2));
    

More complex behavior can be obtained using extra flags, for instance related to mousePressEvent() and mouseReleaseEvent(). See the detailed description section and the mouseGrabber example.

Implemented in ManipulatedFrame.

bool grabsMouse   [inline]
 

Returns true when the MouseGrabber grabs the mouse and hence receives all the QGLViewer's mouse events. This flag is set with setGrabsMouse() by the checkIfGrabsMouse() function.

bool isInMouseGrabberPool   const [inline]
 

Returns true if the MouseGrabber is currently in the MouseGrabberPool(). Default value is true. When set to false using removeFromMouseGrabberPool(), the MouseGrabber is no longer checkIfGrabsMouse() by QGLViewers. See also addInMouseGrabberPool().

virtual void mouseDoubleClickEvent QMouseEvent *    const,
Camera   const
[inline, protected, virtual]
 

See the associated QGLWidget documentation. See also mousePressEvent().

Reimplemented in ManipulatedCameraFrame, and ManipulatedFrame.

const QPtrList<MouseGrabber>& MouseGrabberPool   [inline, static]
 

This list contains all the created MouseGrabber. Used by the QGLViewer to check if any of them grabsMouse() using checkIfGrabsMouse().

You should not have to directly use this list. In case you want to, use code like:

    QPtrListIterator<MouseGrabber> it(MouseGrabber::MouseGrabberPool());
    for (MouseGrabber* mg; (mg = it.current()) != NULL; ++it)
      mg->anyAction(); // possible dynamic_cast here.
    

virtual void mouseMoveEvent QMouseEvent *    const,
const Camera   const
[inline, protected, virtual]
 

See the associated QGLWidget documentation. Probably useful to update the state of the MouseGrabber between a mousePressEvent() and a mouseReleaseEvent(). See the detailed description section for an example.

Reimplemented in ManipulatedCameraFrame, and ManipulatedFrame.

virtual void mousePressEvent QMouseEvent *    const,
Camera   const
[inline, protected, virtual]
 

See the associated QGLWidget documentation. The MouseGrabber will probably start an action or change its state when a mouse button is pressed. See the detailed description section for an example.

Reimplemented in ManipulatedCameraFrame, and ManipulatedFrame.

virtual void mouseReleaseEvent QMouseEvent *    const,
Camera   const
[inline, protected, virtual]
 

See the associated QGLWidget documentation. A probable use of this function will be to desactivate the MouseGrabber. See the detailed description section for an example.

Reimplemented in ManipulatedCameraFrame, and ManipulatedFrame.

void removeFromMouseGrabberPool  
 

Removes the MouseGrabber from the MouseGrabberPool(). See addInMouseGrabberPool() for details. Removing a MouseGrabber that is not in MouseGrabberPool() has no effect.

void setGrabsMouse const bool    flag [inline, protected]
 

The protected method is used to define the grabsMouse() flag. See the grabsMouse() and the checkIfGrabsMouse() documentations.

virtual void wheelEvent QWheelEvent *    const,
const Camera   const
[inline, protected, virtual]
 

See the associated QGLWidget documentation. Can be useful to implement spinners.

Reimplemented in ManipulatedFrame.


Generated on Fri Jun 27 18:34:04 2003 for libQGLViewer by doxygen1.3-rc2