Main Page   Class Hierarchy   Compound List   All functions   Search  

ManipulatedFrame Class Reference

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

Inherits SpinningFrame, and MouseGrabber.

Inherited by ManipulatedCameraFrame.

List of all members.

Intrinsic parameters

float rotationSensitivity () const
float translationSensitivity () const
float spinningSensitivity () const
void setRotationSensitivity (const float s)
void setTranslationSensitivity (const float s)
void setSpinningSensitivity (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 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 camera)

Mouse Grabber implementation

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

Signals

void manipulated ()

Public Methods

 ManipulatedFrame ()
virtual ~ManipulatedFrame ()

Protected Types

enum  Action {
  ROTATION, ZOOM, TRANSLATION, SCREEN_ROT, SCREEN_TRANS, WHEEL,
  NO_ACTION
}

Protected Methods

Quaternion quaternionFromDeformedBall (const int x, const int y, const float cx, const float cy, const Camera *const camera)
void computeMouseSpeed (const QMouseEvent *const e)
int mouseOriginalDirection (const QMouseEvent *const e)

Protected Attributes

Action action_
int prevX_
int prevY_


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 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 gets within a distance of 5 pixels from the projected position of the ManipulatedFrame, the ManipulatedFrame becomes the new QGLViewer::mouseGrabber(). It can then be manipulated directly, without selection or a specific state key. Note that QWidget::setMouseTracking() needs to be enabled in order to use this feature (see the MouseGrabber documentation). See the mouseGrabber example an illustration.

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, for instance according to an object selection (see the luxo example).

When manipulated with the mouse, the isManipulated() function returns true, and it might be checked for a specific action. The ManipulatedFrame also emits a manipulated() signal when manipulated. This signal is automatically connected to all the viewer's updateGL() functions. 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.


Member Enumeration Documentation

enum Action [protected]
 

Enumeration values:
ROTATION 
ZOOM 
TRANSLATION 
SCREEN_ROT 
SCREEN_TRANS 
WHEEL 
NO_ACTION 


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 5 pixels region around the Camera::projectedCoordinatesOf() position().

Implements MouseGrabber.

void computeMouseSpeed const QMouseEvent *const    e [protected]
 

Updates mouse speed, measured in pixels/msecs. Should be called by any function which wants to use mouse speed. Currently used to start spinning in mouseReleaseEvent().

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.

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 [inline]
 

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 using the mouse. Connect this signal to any object that must be notified.

Note that when a ManipulatedFrame is created, this signal is automatically connected to all the viewers' updateGL() functions (see QGLViewer::connectSignalToAllViewers()), so that the QGLViewers' displays are automatically updated.

This signal connection technique is actually used for all the Frames that may be updated in your application. The KeyFrameInterpolator::interpolated() and the SpinningFrame::spinned() signals are also connected to all the viewers' updateGL() functions when they are created. In certain cases, this automatic display update may generate too many updates. Simply disconnect one of the signals to prevent this:

    QGLViewer::disconnectSignalToAllViewers(pointerToTheManipulatedFrame, SIGNAL(manipulated()));
    

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

A double click (dispatched by QGLViewer::mouseDoubleClickEvent() moves the ManipulatedFrame according to the camera:

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

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.

int mouseOriginalDirection const QMouseEvent *const    e [protected]
 

Return 1 if mouse motion was started horizontally and -1 if it was more vertical. Returns 0 if this could not be determined yet (perfect diagonal motion, rare).

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.

Reimplemented in ManipulatedCameraFrame.

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.

Quaternion quaternionFromDeformedBall const int    x,
const int    y,
const float    cx,
const float    cy,
const Camera *const    camera
[protected]
 

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. Defined with setRotationSensitivity().

void setSpinningSensitivity const float    s [inline, slot]
 

Defines the spinningSensitivity().

void setTranslationSensitivity const float    s [inline, slot]
 

Defines the influence of a mouse displacement on the frame translation. Default value is 1.0. Defined with setTranslationSensitivity().

Note:
You should not have to modify this value as the frame translation is computed so that the frame intuitively exactly matches the mouse trajectory.

When the manipulated frame is used to move a Camera, you may be worried when you are looking at a small region of your scene, which translate too fast on the screen when you move the camera.

For a camera, it is the Camera::revolveAroundPoint() that exactly matches the mouse displacement. Instead of changing the translationSensitivity(), you may prefer to temporarily set the Camera::revolveAroundPoint() to a point of the small region of your scene (see the mouse page for the mouse binding).

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. Setting to 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

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

Using the wheel is equivalent to the use of the mouse middle button. See mousePressEvent() for details. Depending on your system configuration, you may have to actually press the wheel while wheeling.

Reimplemented from MouseGrabber.


Member Data Documentation

Action action_ [protected]
 

int prevX_ [protected]
 

int prevY_ [protected]
 


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