ManipulatedFrame Class Reference

A Frame that can be rotated and translated with the mouse. More...

#include <manipulatedFrame.h>

Inherits SpinningFrame, and MouseGrabber.

Inherited by ManipulatedCameraFrame.

List of all members.

Manipulation sensitivity

float rotationSensitivity () const
float translationSensitivity () const
float spinningSensitivity () const
float wheelSensitivity () const
void setRotationSensitivity (const float s)
void setTranslationSensitivity (const float s)
void setSpinningSensitivity (const float s)
void setWheelSensitivity (const float s)

Current state

bool isManipulated () const

XML representation

virtual QDomElement domElement (const QString &name, QDomDocument &doc) const
virtual void initFromDOMElement (const QDomElement &de)

Mouse event handlers

virtual void mousePressEvent (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 camera)

Mouse Grabber implementation

void checkIfGrabsMouse (int x, int y, const Camera *const camera)

Signals

void manipulated ()

Public Member Functions

 ManipulatedFrame ()
virtual ~ManipulatedFrame ()


Detailed Description

A Frame that can be rotated and translated with the mouse.

A ManipulatedFrame is a local coordinate system (a Frame) that can be moved in the 3D scene using the mouse. The ManipulatedFrame converts the mouse motion in a translation and orientation update. You can then use the ManipulatedFrame to move an object or a point in the scene.

A ManipulatedFrame is attached to a QGLViewer using QGLViewer::setManipulatedFrame():

  init() { setManipulatedFrame( new ManipulatedFrame() ); }

  draw()
  {
    glPushMatrix();
    glMultMatrixd(manipulatedFrame()->matrix());
    // draw the manipulated object here
    glPopMatrix();
  }
You have to press the QGLViewer::FRAME state key (default is Control) to move the QGLViewer::manipulatedFrame().

The manipulatedFrame example details a complete application. See the mouse page for a description of the mouse button bindings.

Inherited functionalities

A ManipulatedFrame is an overloaded instance of a Frame. The powerful coordinate system transformation functions (Frame::coordinatesOf(), Frame::transformOf(), ...) can hence be applied to a ManipulatedFrame.

A ManipulatedFrame is also a SpinningFrame, and you can make the ManipulatedFrame spin is you release the rotation mouse button while moving the mouse fast enough (see spinningSensitivity()).

Finally, a ManipulatedFrame is a MouseGrabber. If the mouse cursor gets within a distance of 10 pixels from the projected position of the ManipulatedFrame, the ManipulatedFrame becomes the new QGLViewer::mouseGrabber(). It can then be manipulated directly, without any specific state key, object selection or GUI intervention. This is very convenient to directly move some objects of the scene (typically a light). See the mouseGrabber example as an illustration. Note that QWidget::setMouseTracking() needs to be enabled in order to use this feature (see the MouseGrabber documentation).

Advanced functionalities

A QGLViewer can handle at most one ManipulatedFrame at a time. If you want to move several objects in the scene, you simply have to keep a list of the different ManipulatedFrames, and to activate the right one (using setManipulatedFrame()), for instance according to an object selection (see the luxo example).

When the ManipulatedFrame is being manipulated using the mouse (mouse pressed and not yet released), isManipulated() returns true, and it might be checked for a specific action (as in QGLViewer::fastDraw()).

The ManipulatedFrame also emits a manipulated() signal each time its state is modified with the mouse. This signal is automatically connected to the viewer's updateGL() slot, when the ManipulatedFrame is attached to a viewer using QGLViewer::setManipulatedFrame(). See the manipulated() documentation for details.

Combined with the object selection (see the select example), the MouseGrabber properties and a dynamic update of the scene, the ManipulatedFrame introduces a great reactivity in your applications.


Constructor & Destructor Documentation

ManipulatedFrame  ) 
 

Creates a default manipulatedFrame. Translation is (0,0,0), with an identity rotation (0,0,0,1).

virtual ~ManipulatedFrame  )  [inline, virtual]
 

Virtual destructor. Empty.


Member Function Documentation

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

Default implementation of the MouseGrabber main function. MouseGrabber::grabsMouse() is set to true when the mouse is within a 10 pixels region around the Camera::projectedCoordinatesOf() position().

See the mouseGrabber example for an illustration.

Implements MouseGrabber.

QDomElement domElement const QString &  name,
QDomDocument &  doc
const [virtual]
 

Creates an XML QDomElement that represents the ManipulatedFrame. Add to SpinningFrame::domElement() the ManipulatedFrame specific informations. name is the name of the QDomElement tag. You need to provide the QDomDocument doc that will hold the resulting element.

See also Camera::domElement(), KeyFrameInterpolator::domElement()...

Use initFromDOMElement() to restore the ManipulatedFrame state from the resulting domElement.

Reimplemented from SpinningFrame.

Reimplemented in ManipulatedCameraFrame.

void initFromDOMElement const QDomElement &  de  )  [virtual]
 

Restore the ManipulatedFrame state from a QDomElement created by domElement(). See also Frame::initFromDOMElement().

Reimplemented from SpinningFrame.

Reimplemented in ManipulatedCameraFrame.

bool isManipulated  )  const
 

True when the ManipulatedFrame is being manipulated with the mouse. Can be used to manually simulate the QGLViewer::fastDraw() function. Used by QGLViewer.

void manipulated  )  [signal]
 

This signal is emitted whenever the frame is manipulated (i.e. rotated or translated) using the mouse. Connect this signal to any object that should be notified.

Note that this signal is automatically connected to the viewer's updateGL() slot, when the ManipulatedFrame is attached to a viewer using QGLViewer::setManipulatedFrame(), which is probably all you need.

However, when you have several viewers that display the same scene, it may be interesting to update all the viewers when a ManipulatedFrame (hence an object) is manipulated in any of these viewers. Simply use this code to achieve this behavior:

    QGLViewer::connectSignalToAllViewers(myManipulatedFrame, SIGNAL(manipulated()));

See also the KeyFrameInterpolator::interpolated() and SpinningFrame::spinned() signals documentations.

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

Move the manipulated frame according to the mouse motion. The camera is given as an argument so that its parameters (width and height of the window, fieldOfView) are available in order to fit the mouse motion and the display. Emits manipulated().

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

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

The mouse behavior depends on which button is pressed. See the QGLViewer mouse page for details.

Reimplemented from MouseGrabber.

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

When the user releases the mouse button, the manipulatedFrame action is stopped.

If the action was a rotation, a continuous spinning is possible if the speed of the cursor is larger than spinningSensitivity() when the button is released. Press the rotate button again to stop the spinning.

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

float rotationSensitivity  )  const [inline]
 

Returns the current rotationSensitivity() as defined by setRotationSensitivity(). Default value is 1.0

void setRotationSensitivity const float  s  )  [inline, slot]
 

Defines the influence of a mouse displacement on the frame rotation (default value is 1.0). See rotationSensitivity().

void setSpinningSensitivity const float  s  )  [inline, slot]
 

Defines the spinningSensitivity(). Default value is 0.3 (pixels per milliseconds).

void setTranslationSensitivity const float  s  )  [inline, slot]
 

Defines the influence of a mouse displacement on the frame translation. Default value is 1.0. See translationSensitivity().

void setWheelSensitivity const float  s  )  [inline, slot]
 

Defines the wheelSensitivity(). Default value is 1.0.

float spinningSensitivity  )  const [inline]
 

Returns the minimum mouse speed required to make the Frame spin when the mouse button is released. Mouse speed is expressed in pixels per milliseconds. Default value is 0.3 (300 pixels per second). Use setSpinningSensitivity() to tune this value. A higher value will make auto spinning more difficult (a value of 100.0 means forbid spinning in practice).

float translationSensitivity  )  const [inline]
 

Returns the current translationSensitivity() as defined by setTranslationSensitivity() (default value is 1.0).

Note:
You should not have to modify this value as the frame translation is computed so that the frame exactly matches the mouse trajectory, which is an intuitive behavior.

When the manipulated frame is used to move a Camera (see the ManipulatedCameraFrame class documentation), after zooming on a small region of your scene, the camera may translate too fast. For a camera, it is the Camera::revolveAroundPoint() that exactly matches the mouse displacement. Hence, instead of changing the translationSensitivity() to solve the problem, you simply have to (temporarily) set the Camera::revolveAroundPoint() to a point of the small region of your scene (see the mouse page for the RAP_FROM_PIXEL mouse binding, default is a double click on left button while pressing right button).

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

Using the wheel is equivalent to a ZOOM action. See QGLViewer::setWheelBinding() and setWheelSensitivity().

Depending on your system configuration, you may have to actually press the wheel while wheeling.

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

float wheelSensitivity  )  const [inline]
 

Current wheel sensitivity. Default value is 1.0. Defined using setWheelSensitivity().

A higher value will make the wheel action more effective (usually means a faster zoom).


Generated on Wed Jul 7 12:17:47 2004 for libQGLViewer by doxygen 1.3.4