Abstract class for objects that grab mouse focus in a QGLViewer. More...

#include <QGLViewer/mouseGrabber.h>

Inheritance diagram for qglviewer::MouseGrabber:

Public Member Functions
	MouseGrabber ()

virtual	~MouseGrabber ()

Private Member Functions
	MouseGrabber (const MouseGrabber &)

MouseGrabber &	operator= (const MouseGrabber &)

Private Attributes
bool	grabsMouse_

Static Private Attributes
static QPtrList< MouseGrabber >	MouseGrabberPool_

Friends
class	::QGLViewer

Mouse grabbing detection
virtual void	checkIfGrabsMouse (int x, int y, const Camera *const camera)=0

bool	grabsMouse () const

void	setGrabsMouse (bool grabs)

MouseGrabber pool
bool	isInMouseGrabberPool () const

void	addInMouseGrabberPool ()

void	removeFromMouseGrabberPool ()

void	clearMouseGrabberPool (bool autoDelete=false)

static const QList< MouseGrabber > &	MouseGrabberPool ()

Mouse event handlers
virtual void	mousePressEvent (QMouseEvent const event, Camera const camera)

virtual void	mouseDoubleClickEvent (QMouseEvent const event, Camera const camera)

virtual void	mouseReleaseEvent (QMouseEvent const event, Camera const camera)

virtual void	mouseMoveEvent (QMouseEvent const event, Camera const camera)

virtual void	wheelEvent (QWheelEvent const event, Camera const camera)

Detailed Description

Abstract class for objects that grab mouse focus in a QGLViewer.

MouseGrabber are objects which react to the mouse cursor, usually when it hovers over them. This abstract class only provides an interface for all these objects: their actual behavior has to be defined in a derived class.

How does it work ?

All the created MouseGrabber are grouped in a MouseGrabberPool(). The QGLViewers parse this pool, calling all the MouseGrabbers' checkIfGrabsMouse() methods that setGrabsMouse() if desired.

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. This continues while grabsMouse() (updated using checkIfGrabsMouse()) returns true.

If you want to (temporarily) disable a specific MouseGrabbers, you can remove it from this pool using removeFromMouseGrabberPool(). You can also disable a MouseGrabber in a specific QGLViewer using QGLViewer::setMouseGrabberIsEnabled().

Implementation details

In order to make MouseGrabber react to mouse events, mouse tracking has to be activated in the QGLViewer which wants to use MouseGrabbers:

init() { setMouseTracking(true); }

Call QGLWidget::hasMouseTracking() to get the current state of this flag.

The camera parameter of the different mouse event methods is a pointer to the QGLViewer::camera() of the QGLViewer that uses 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.

Note that ManipulatedFrame are MouseGrabber: see the keyFrame example for an illustration. Every created ManipulatedFrame is hence present in the MouseGrabberPool() (note however that ManipulatedCameraFrame are not inserted).

Example

Here is for instance a draft version of a MovableObject class. Instances of these class can freely be moved on screen using the mouse, as movable post-it-like notes:

class MovableObject : public MouseGrabber
{
public:
  MovableObject() : pos(0,0), moved(false) {};
  void checkIfGrabsMouse(int x, int y, const qglviewer::Camera* const)
  {
    // MovableObject is active in a region of 5 pixels around its pos.
    // May depend on the actual shape of the object. Customize as desired.
    // Once clicked (moved = true), it keeps grabbing mouse until button is released.
    setGrabsMouse( moved || ((pos-QPoint(x,y)).manhattanLength() < 5) );
  }
  void mousePressEvent( QMouseEvent* const e, Camera* const) { prevPos = e->pos(); moved = true; }
  void mouseMoveEvent(QMouseEvent* const e, const Camera* const)
  {
    if (moved)
    {
      // Add position delta to current pos
      pos += e->pos() - prevPos;
      prevPos = e->pos();
    }
  }
  void mouseReleaseEvent(QMouseEvent* const, Camera* const) { moved = false; }
  void draw()
  {
    // The object is drawn centered on its pos, with different possible aspects:
    if (grabsMouse())
      if (moved)
        // Object being moved, maybe a transparent display
      else
        // Object ready to be moved, maybe a highlighted visual feedback
    else
      // Normal display
  }
private:
  QPoint pos, prevPos;
  bool moved;
};

Note that the different event callback methods are called only once the MouseGrabber grabsMouse().

Definition at line 134 of file mouseGrabber.h.

Constructor & Destructor Documentation

MouseGrabber::MouseGrabber ( )

Default constructor.

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

Definition at line 37 of file mouseGrabber.cpp.

virtual qglviewer::MouseGrabber::~MouseGrabber ( )

inlinevirtual

Virtual destructor. Removes the MouseGrabber from the MouseGrabberPool().

Definition at line 146 of file mouseGrabber.h.

qglviewer::MouseGrabber::MouseGrabber ( const MouseGrabber & )

private

Member Function Documentation

void MouseGrabber::addInMouseGrabberPool ( )

Adds the MouseGrabber in the MouseGrabberPool().

All created 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, and hence can no longer grab mouse focus. Use isInMouseGrabberPool() to know the current state of the MouseGrabber.

Definition at line 51 of file mouseGrabber.cpp.

virtual void qglviewer::MouseGrabber::checkIfGrabsMouse	(	int	x,
		int	y,
		const Camera *const	camera
	)

pure virtual

Pure virtual method, called by the QGLViewers before they test if the MouseGrabber grabsMouse(). Should setGrabsMouse() according to the mouse position.

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

grabsMouse() is usually set to true when the mouse cursor is close enough to the MouseGrabber position. It should also be set to false when the mouse cursor leaves this region in order to release the mouse focus.

x and y are the mouse cursor coordinates (Qt coordinate system: (0,0) corresponds to the upper left corner).

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, use the camera parameter, corresponding to the calling QGLViewer Camera. Project on screen and then compare the projected coordinates:

Vec proj = camera->projectedCoordinatesOf(myMouseGrabber->frame()->position());

setGrabsMouse((fabs(x-proj.x) < 5) && (fabs(y-proj.y) < 2)); // Rectangular region

See examples in the detailed description section and in the mouseGrabber example.

Implemented in qglviewer::ManipulatedFrame.

void MouseGrabber::clearMouseGrabberPool ( bool autoDelete = false )

Clears the MouseGrabberPool().

Use this method only if it is faster to clear the MouseGrabberPool() and then to add back a few MouseGrabbers than to remove each one independently. Use QGLViewer::setMouseTracking(false) instead if you want to disable mouse grabbing.

When autoDelete is true, the MouseGrabbers of the MouseGrabberPool() are actually deleted (use this only if you're sure of what you do).

Definition at line 79 of file mouseGrabber.cpp.

bool qglviewer::MouseGrabber::grabsMouse ( ) const

inline

Returns true when the MouseGrabber grabs the QGLViewer's mouse events.

This flag is set with setGrabsMouse() by the checkIfGrabsMouse() method.

Definition at line 187 of file mouseGrabber.h.

bool qglviewer::MouseGrabber::isInMouseGrabberPool ( ) const

inline

Returns true if the MouseGrabber is currently in the MouseGrabberPool() list.

Default value is true. When set to false using removeFromMouseGrabberPool(), the QGLViewers no longer checkIfGrabsMouse() on this MouseGrabber. Use addInMouseGrabberPool() to insert it back.

Definition at line 225 of file mouseGrabber.h.

virtual void qglviewer::MouseGrabber::mouseDoubleClickEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)

inlineprotectedvirtual

Callback method called when the MouseGrabber grabsMouse() and a mouse button is double clicked.

See the QGLWidget::mouseDoubleClickEvent() and the QMouseEvent documentations for details.

Reimplemented in qglviewer::ManipulatedFrame.

Definition at line 255 of file mouseGrabber.h.

static const QList<MouseGrabber>& qglviewer::MouseGrabber::MouseGrabberPool ( )

inlinestatic

Returns a list containing pointers to all the active MouseGrabbers.

Used by the QGLViewer to parse all the MouseGrabbers and to check if any of them grabsMouse() using checkIfGrabsMouse().

You should not have to directly use this list. Use removeFromMouseGrabberPool() and addInMouseGrabberPool() to modify this list.

Attention: This method returns a QPtrList<MouseGrabber> with Qt 3 and a QList<MouseGrabber> with Qt 2.

Definition at line 213 of file mouseGrabber.h.

virtual void qglviewer::MouseGrabber::mouseMoveEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)

inlineprotectedvirtual

Callback method called when the MouseGrabber grabsMouse() and the mouse is moved while a button is pressed.

This method will typically update the state of the MouseGrabber from the mouse displacement. See the mousePressEvent() documentation for details.

Reimplemented in qglviewer::ManipulatedFrame, and qglviewer::ManipulatedCameraFrame.

Definition at line 263 of file mouseGrabber.h.

virtual void qglviewer::MouseGrabber::mousePressEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)

inlineprotectedvirtual

Callback method called when the MouseGrabber grabsMouse() and a mouse button is pressed.

The MouseGrabber will typically start an action or change its state when a mouse button is pressed. mouseMoveEvent() (called at each mouse displacement) will then update the MouseGrabber accordingly and mouseReleaseEvent() (called when the mouse button is released) will terminate this action.

Use the event QMouseEvent::state() and QMouseEvent::button() to test the keyboard and button state and possibly change the MouseGrabber behavior accordingly.

See the detailed description section and the mouseGrabber example for examples.

See the QGLWidget::mousePressEvent() and the QMouseEvent documentations for details.

Reimplemented in qglviewer::ManipulatedFrame.

Definition at line 251 of file mouseGrabber.h.

virtual void qglviewer::MouseGrabber::mouseReleaseEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)

inlineprotectedvirtual

Mouse release event callback method. See mousePressEvent().

Reimplemented in qglviewer::ManipulatedFrame, and qglviewer::ManipulatedCameraFrame.

Definition at line 257 of file mouseGrabber.h.

MouseGrabber& qglviewer::MouseGrabber::operator= ( const MouseGrabber & )

private

void MouseGrabber::removeFromMouseGrabberPool ( )

Removes the MouseGrabber from the MouseGrabberPool().

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

Definition at line 61 of file mouseGrabber.cpp.

void qglviewer::MouseGrabber::setGrabsMouse ( bool grabs )

inlineprotected

Sets the grabsMouse() flag. Normally used by checkIfGrabsMouse().

Definition at line 191 of file mouseGrabber.h.

virtual void qglviewer::MouseGrabber::wheelEvent	(	QWheelEvent *const	event,
		Camera *const	camera
	)

inlineprotectedvirtual

Callback method called when the MouseGrabber grabsMouse() and the mouse wheel is used.

See the QGLWidget::wheelEvent() and the QWheelEvent documentations for details.

Reimplemented in qglviewer::ManipulatedFrame, and qglviewer::ManipulatedCameraFrame.

Definition at line 267 of file mouseGrabber.h.

Friends And Related Function Documentation

friend class ::QGLViewer

friend

Definition at line 137 of file mouseGrabber.h.

Member Data Documentation

bool qglviewer::MouseGrabber::grabsMouse_

private

Definition at line 276 of file mouseGrabber.h.

QPtrList< MouseGrabber > MouseGrabber::MouseGrabberPool_

staticprivate

Definition at line 282 of file mouseGrabber.h.

The documentation for this class was generated from the following files:

Public Member Functions

Private Member Functions

Private Attributes

Static Private Attributes

Friends

Mouse grabbing detection

MouseGrabber pool

Mouse event handlers

Detailed Description

How does it work ?

Implementation details

Example

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation