A ManipulatedFrame is a Frame that can be rotated and translated using the mouse. More...

Inheritance diagram for ManipulatedFrame:

Signals
void	manipulated ()
	This signal is emitted when ever the ManipulatedFrame is manipulated (i.e.
void	spun ()
	This signal is emitted when the ManipulatedFrame isSpinning().
Public Member Functions
	ManipulatedFrame ()
	Default constructor.
	ManipulatedFrame (const ManipulatedFrame &mf)
	Copy constructor.
virtual	~ManipulatedFrame ()
	Virtual destructor.
ManipulatedFrame &	operator= (const ManipulatedFrame &mf)
	Equal operator.
Protected Member Functions
void	computeMouseSpeed (const QMouseEvent *const e)
	Updates mouse speed, measured in pixels/milliseconds.
Quaternion	deformedBallQuaternion (int x, int y, float cx, float cy, const Camera *const camera)
	Returns a quaternion computed according to the mouse motion.
int	mouseOriginalDirection (const QMouseEvent *const e)
	Return 1 if mouse motion was started horizontally and -1 if it was more vertical.
virtual void	startAction (int ma, bool withConstraint=true)
	Protected internal method used to handle mouse events.
Protected Attributes
int	action_
QPoint	pressPos_
Constraint *	previousConstraint_
QPoint	prevPos_
Friends
class	::QGLViewer
class	Camera
Manipulation sensitivity
float	rotationSensitivity () const
	Returns the influence of a mouse displacement on the ManipulatedFrame rotation.
float	translationSensitivity () const
	Returns the influence of a mouse displacement on the ManipulatedFrame translation.
float	spinningSensitivity () const
	Returns the minimum mouse speed required (at button release) to make the ManipulatedFrame spin().
float	wheelSensitivity () const
	Returns the mouse wheel sensitivity.
void	setRotationSensitivity (float sensitivity)
	Defines the rotationSensitivity().
void	setTranslationSensitivity (float sensitivity)
	Defines the translationSensitivity().
void	setSpinningSensitivity (float sensitivity)
	Defines the spinningSensitivity(), in pixels per milliseconds.
void	setWheelSensitivity (float sensitivity)
	Defines the wheelSensitivity().
Spinning
bool	isSpinning () const
	Returns `true` when the ManipulatedFrame is spinning.
Quaternion	spinningQuaternion () const
	Returns the incremental rotation that is applied by spin() to the ManipulatedFrame orientation when it isSpinning().
void	setSpinningQuaternion (const Quaternion &spinningQuaternion)
	Defines the spinningQuaternion().
virtual void	startSpinning (int updateInterval)
	Starts the spinning of the ManipulatedFrame.
virtual void	stopSpinning ()
	Stops the spinning motion started using startSpinning().
virtual void	spin ()
	Rotates the ManipulatedFrame by its spinningQuaternion().
Mouse event handlers
virtual void	mousePressEvent (QMouseEvent const event, Camera const camera)
	Initiates the ManipulatedFrame mouse manipulation.
virtual void	mouseMoveEvent (QMouseEvent const event, Camera const camera)
	Modifies the ManipulatedFrame according to the mouse motion.
virtual void	mouseReleaseEvent (QMouseEvent const event, Camera const camera)
	Stops the ManipulatedFrame mouse manipulation.
virtual void	mouseDoubleClickEvent (QMouseEvent const event, Camera const camera)
	Overloading of MouseGrabber::mouseDoubleClickEvent().
virtual void	wheelEvent (QWheelEvent const event, Camera const camera)
	Overloading of MouseGrabber::wheelEvent().
Current state
bool	isManipulated () const
	Returns `true` when the ManipulatedFrame is being manipulated with the mouse.
MouseGrabber implementation
virtual void	checkIfGrabsMouse (int x, int y, const Camera *const camera)
	Implementation of the MouseGrabber main method.
XML representation
virtual QDomElement	domElement (const QString &name, QDomDocument &document) const
	Returns an XML `QDomElement` that represents the ManipulatedFrame.
virtual void	initFromDOMElement (const QDomElement &element)
	Restores the ManipulatedFrame state from a `QDomElement` created by domElement().

Detailed Description

A ManipulatedFrame is a Frame that can be rotated and translated using the mouse.

It converts the mouse motion into a translation and an orientation updates. A ManipulatedFrame is used to move an object in the scene. Combined with object selection, its MouseGrabber properties and a dynamic update of the scene, the ManipulatedFrame introduces a great reactivity in your applications.

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();
  }

See the manipulatedFrame example for a complete application.

Mouse events are normally sent to the QGLViewer::camera(). You have to press the QGLViewer::FRAME state key (default is Control) to move the QGLViewer::manipulatedFrame() instead. See the mouse page for a description of 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 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 in 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 QGLViewer::setManipulatedFrame()) when needed. This can for instance be done according to an object selection: see the luxo example for an illustration.

When the ManipulatedFrame is being manipulated using the mouse (mouse pressed and not yet released), isManipulated() returns true. This might be used to trigger a specific action or display (as is done with QGLViewer::fastDraw()).

The ManipulatedFrame also emits a manipulated() signal each time its state is modified by the mouse. This signal is automatically connected to the QGLViewer::updateGL() slot when the ManipulatedFrame is attached to a viewer using QGLViewer::setManipulatedFrame().

You can make the ManipulatedFrame spin() if you release the rotation mouse button while moving the mouse fast enough (see spinningSensitivity()). See also translationSensitivity() and rotationSensitivity() for sensitivity tuning.

Definition at line 100 of file manipulatedFrame.h.

Constructor & Destructor Documentation

ManipulatedFrame ( )

Default constructor.

The translation is set to (0,0,0), with an identity rotation (0,0,0,1) (see Frame constructor for details).

The different sensitivities are set to their default values (see rotationSensitivity(), translationSensitivity(), spinningSensitivity() and wheelSensitivity()).

Definition at line 44 of file manipulatedFrame.cpp.

References ManipulatedFrame::setRotationSensitivity(), ManipulatedFrame::setSpinningSensitivity(), ManipulatedFrame::setTranslationSensitivity(), and ManipulatedFrame::setWheelSensitivity().

virtual ~ManipulatedFrame ( ) [inline, virtual]

Virtual destructor.

Empty.

Definition at line 112 of file manipulatedFrame.h.

ManipulatedFrame ( const ManipulatedFrame & mf )

Copy constructor.

Performs a deep copy of all attributes using operator=().

Definition at line 77 of file manipulatedFrame.cpp.

Member Function Documentation

void checkIfGrabsMouse	(	int	x,
		int	y,
		const Camera *const	camera
	)		`[virtual]`

Implementation of the MouseGrabber main method.

The ManipulatedFrame grabsMouse() when the mouse is within a 10 pixels region around its Camera::projectedCoordinatesOf() position().

See the mouseGrabber example for an illustration.

Implements MouseGrabber.

Definition at line 91 of file manipulatedFrame.cpp.

References Frame::position(), Camera::projectedCoordinatesOf(), and MouseGrabber::setGrabsMouse().

void computeMouseSpeed ( const QMouseEvent *const e ) [protected]

Updates mouse speed, measured in pixels/milliseconds.

Should be called by any method which wants to use mouse speed. Currently used to trigger spinning in mouseReleaseEvent().

Definition at line 237 of file manipulatedFrame.cpp.

Referenced by ManipulatedFrame::mouseMoveEvent(), and ManipulatedCameraFrame::mouseMoveEvent().

Quaternion deformedBallQuaternion	(	int	x,
		int	y,
		float	cx,
		float	cy,
		const Camera *const	camera
	)		`[protected]`

Returns a quaternion computed according to the mouse motion.

Mouse positions are projected on a deformed ball, centered on (cx,cy).

Definition at line 517 of file manipulatedFrame.cpp.

References ManipulatedFrame::rotationSensitivity(), Camera::screenHeight(), Camera::screenWidth(), and Vec::squaredNorm().

Referenced by ManipulatedFrame::mouseMoveEvent(), and ManipulatedCameraFrame::mouseMoveEvent().

QDomElement domElement	(	const QString &	name,
		QDomDocument &	document
	)		const `[virtual]`

Returns an XML QDomElement that represents the ManipulatedFrame.

Adds to the Frame::domElement() the ManipulatedFrame specific informations in a ManipulatedParameters child QDomElement.

name is the name of the QDomElement tag. doc is the QDomDocument factory used to create QDomElement.

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

See Vec::domElement() for a complete example. See also Quaternion::domElement(), Camera::domElement()...

Reimplemented from Frame.

Reimplemented in ManipulatedCameraFrame.

Definition at line 114 of file manipulatedFrame.cpp.

References ManipulatedFrame::rotationSensitivity(), ManipulatedFrame::spinningSensitivity(), ManipulatedFrame::translationSensitivity(), and ManipulatedFrame::wheelSensitivity().

void initFromDOMElement ( const QDomElement & element ) [virtual, slot]

Restores the ManipulatedFrame state from a QDomElement created by domElement().

Fields that are not described in element are set to their default values (see ManipulatedFrame()).

First calls Frame::initFromDOMElement() and then initializes ManipulatedFrame specific parameters. Note that constraint() and referenceFrame() are not restored and are left unchanged.

See Vec::initFromDOMElement() for a complete code example.

Reimplemented from Frame.

Reimplemented in ManipulatedCameraFrame.

Definition at line 135 of file manipulatedFrame.cpp.

References ManipulatedFrame::setRotationSensitivity(), ManipulatedFrame::setSpinningSensitivity(), ManipulatedFrame::setTranslationSensitivity(), ManipulatedFrame::setWheelSensitivity(), and ManipulatedFrame::stopSpinning().

bool isManipulated ( ) const

Returns true when the ManipulatedFrame is being manipulated with the mouse.

Can be used to change the display of the manipulated object during manipulation.

When Camera::frame() of the QGLViewer::camera() isManipulated(), QGLViewer::fastDraw() is used in place of QGLViewer::draw() for scene rendering. A simplified drawing will then allow for interactive camera displacements.

Definition at line 170 of file manipulatedFrame.cpp.

bool isSpinning ( ) const [inline]

Returns true when the ManipulatedFrame is spinning.

During spinning, spin() rotates the ManipulatedFrame by its spinningQuaternion() at a frequency defined when the ManipulatedFrame startSpinning().

Use startSpinning() and stopSpinning() to change this state. Default value is false.

Definition at line 215 of file manipulatedFrame.h.

void manipulated ( ) [signal]

This signal is emitted when ever the ManipulatedFrame 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 QGLViewer::updateGL() slot, when the ManipulatedFrame is attached to a viewer using QGLViewer::setManipulatedFrame(), which is probably all you need.

Use the QGLViewer::QGLViewerPool() if you need to connect this signal to all the viewers.

See also the spun(), modified(), interpolated() and KeyFrameInterpolator::interpolated() signals' documentations.

Referenced by ManipulatedFrame::mouseMoveEvent(), ManipulatedCameraFrame::mouseMoveEvent(), ManipulatedFrame::wheelEvent(), and ManipulatedCameraFrame::wheelEvent().

void mouseDoubleClickEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)		`[protected, virtual]`

Overloading of MouseGrabber::mouseDoubleClickEvent().

Left button double click aligns the ManipulatedFrame with the camera axis (see alignWithFrame() and QGLViewer::ALIGN_FRAME). Right button projects the ManipulatedFrame on the camera view direction.

Reimplemented from MouseGrabber.

Definition at line 454 of file manipulatedFrame.cpp.

References Frame::alignWithFrame(), Camera::frame(), Camera::position(), Frame::projectOnLine(), and Camera::viewDirection().

void mouseMoveEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)		`[protected, virtual]`

Modifies the ManipulatedFrame according to the mouse motion.

Actual behavior depends on mouse bindings. See the QGLViewer::MouseAction enum and the QGLViewer mouse page for details.

The camera is used to fit the mouse motion with the display parameters (see Camera::screenWidth(), Camera::screenHeight(), Camera::fieldOfView()).

Emits the manipulated() signal.

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

Definition at line 304 of file manipulatedFrame.cpp.

References ManipulatedFrame::computeMouseSpeed(), Frame::coordinatesOf(), ManipulatedFrame::deformedBallQuaternion(), Camera::fieldOfView(), Camera::frame(), Camera::getOrthoWidthHeight(), Frame::inverseTransformOf(), ManipulatedFrame::manipulated(), ManipulatedFrame::mouseOriginalDirection(), Frame::orientation(), Camera::position(), Frame::position(), Camera::projectedCoordinatesOf(), Frame::referenceFrame(), Quaternion::rotate(), Camera::screenHeight(), Camera::screenWidth(), ManipulatedFrame::setSpinningQuaternion(), Vec::setValue(), ManipulatedFrame::spin(), Frame::transformOf(), Frame::translate(), ManipulatedFrame::translationSensitivity(), and Camera::type().

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).

Definition at line 251 of file manipulatedFrame.cpp.

Referenced by ManipulatedFrame::mouseMoveEvent(), and ManipulatedCameraFrame::mouseMoveEvent().

void mousePressEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)		`[protected, virtual]`

Initiates the ManipulatedFrame mouse manipulation.

Overloading of MouseGrabber::mousePressEvent(). See also mouseMoveEvent() and mouseReleaseEvent().

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

Reimplemented from MouseGrabber.

Definition at line 278 of file manipulatedFrame.cpp.

References MouseGrabber::grabsMouse().

Referenced by QGLViewer::mousePressEvent().

void mouseReleaseEvent	(	QMouseEvent *const	event,
		Camera *const	camera
	)		`[protected, virtual]`

Stops the ManipulatedFrame mouse manipulation.

Overloading of MouseGrabber::mouseReleaseEvent().

If the action was a QGLViewer::ROTATE QGLViewer::MouseAction, a continuous spinning is possible if the speed of the mouse cursor is larger than spinningSensitivity() when the button is released. Press the rotate button again to stop spinning. See startSpinning() and isSpinning().

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

Definition at line 433 of file manipulatedFrame.cpp.

References Frame::setConstraint(), ManipulatedFrame::spinningSensitivity(), and ManipulatedFrame::startSpinning().

ManipulatedFrame & operator= ( const ManipulatedFrame & mf )

Equal operator.

Calls Frame::operator=() and then copy attributes.

Definition at line 60 of file manipulatedFrame.cpp.

References ManipulatedFrame::rotationSensitivity(), ManipulatedFrame::setRotationSensitivity(), ManipulatedFrame::setSpinningSensitivity(), ManipulatedFrame::setTranslationSensitivity(), ManipulatedFrame::setWheelSensitivity(), ManipulatedFrame::spinningSensitivity(), ManipulatedFrame::translationSensitivity(), and ManipulatedFrame::wheelSensitivity().

float rotationSensitivity ( ) const [inline]

Returns the influence of a mouse displacement on the ManipulatedFrame rotation.

Default value is 1.0. With an identical mouse displacement, a higher value will generate a larger rotation (and inversely for lower values). A 0.0 value will forbid ManipulatedFrame mouse rotation (see also constraint()).

Definition at line 163 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::deformedBallQuaternion(), ManipulatedFrame::domElement(), and ManipulatedFrame::operator=().

void setRotationSensitivity ( float sensitivity ) [inline, slot]

Defines the rotationSensitivity().

Definition at line 147 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::initFromDOMElement(), ManipulatedFrame::ManipulatedFrame(), and ManipulatedFrame::operator=().

void setSpinningQuaternion ( const Quaternion & spinningQuaternion ) [inline, slot]

Defines the spinningQuaternion().

Its axis is defined in the ManipulatedFrame coordinate system.

Definition at line 228 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::mouseMoveEvent(), and ManipulatedCameraFrame::mouseMoveEvent().

void setSpinningSensitivity ( float sensitivity ) [inline, slot]

Defines the spinningSensitivity(), in pixels per milliseconds.

Definition at line 151 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::initFromDOMElement(), ManipulatedFrame::ManipulatedFrame(), and ManipulatedFrame::operator=().

void setTranslationSensitivity ( float sensitivity ) [inline, slot]

Defines the translationSensitivity().

Definition at line 149 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::initFromDOMElement(), ManipulatedFrame::ManipulatedFrame(), and ManipulatedFrame::operator=().

void setWheelSensitivity ( float sensitivity ) [inline, slot]

Defines the wheelSensitivity().

Definition at line 153 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::initFromDOMElement(), ManipulatedFrame::ManipulatedFrame(), and ManipulatedFrame::operator=().

void spin ( ) [protected, virtual, slot]

Rotates the ManipulatedFrame by its spinningQuaternion().

Called by a timer when the ManipulatedFrame isSpinning().

Reimplemented in ManipulatedCameraFrame.

Definition at line 187 of file manipulatedFrame.cpp.

References Frame::rotate(), and ManipulatedFrame::spinningQuaternion().

Referenced by ManipulatedFrame::mouseMoveEvent().

Quaternion spinningQuaternion ( ) const [inline]

Returns the incremental rotation that is applied by spin() to the ManipulatedFrame orientation when it isSpinning().

Default value is a null rotation (identity Quaternion). Use setSpinningQuaternion() to change this value.

The spinningQuaternion() axis is defined in the ManipulatedFrame coordinate system. You can use Frame::transformOfFrom() to convert this axis from an other Frame coordinate system.

Definition at line 224 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::spin(), and ManipulatedCameraFrame::spin().

float spinningSensitivity ( ) const [inline]

Returns the minimum mouse speed required (at button release) to make the ManipulatedFrame spin().

See spin(), spinningQuaternion() and startSpinning() for details.

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 spinning more difficult (a value of 100.0 forbids spinning in practice).

Definition at line 194 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::domElement(), ManipulatedFrame::mouseReleaseEvent(), and ManipulatedFrame::operator=().

void spun ( ) [signal]

This signal is emitted when the ManipulatedFrame isSpinning().

Note that for the QGLViewer::manipulatedFrame(), this signal is automatically connected to the QGLViewer::updateGL() slot.

Connect this signal to any object that should be notified. Use the QGLViewer::QGLViewerPool() if you need to connect this signal to all the viewers.

See also the manipulated(), modified(), interpolated() and KeyFrameInterpolator::interpolated() signals' documentations.

void startAction	(	int	ma,
		bool	withConstraint = `true`
	)		`[protected, virtual]`

Protected internal method used to handle mouse events.

Reimplemented in ManipulatedCameraFrame.

Definition at line 204 of file manipulatedFrame.cpp.

References Frame::constraint(), Frame::setConstraint(), and ManipulatedFrame::stopSpinning().

Referenced by QGLViewer::mousePressEvent(), and QGLViewer::wheelEvent().

void startSpinning ( int updateInterval ) [virtual, slot]

Starts the spinning of the ManipulatedFrame.

This method starts a timer that will call spin() every updateInterval milliseconds. The ManipulatedFrame isSpinning() until you call stopSpinning().

Definition at line 179 of file manipulatedFrame.cpp.

Referenced by ManipulatedFrame::mouseReleaseEvent().

virtual void stopSpinning ( ) [inline, virtual, slot]

Stops the spinning motion started using startSpinning().

isSpinning() will return false after this call.

Definition at line 232 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::initFromDOMElement(), and ManipulatedFrame::startAction().

float translationSensitivity ( ) const [inline]

Returns the influence of a mouse displacement on the ManipulatedFrame translation.

Default value is 1.0. You should not have to modify this value, since with 1.0 the ManipulatedFrame precisely stays under the mouse cursor.

With an identical mouse displacement, a higher value will generate a larger translation (and inversely for lower values). A 0.0 value will forbid ManipulatedFrame mouse translation (see also constraint()).

Note:: When the ManipulatedFrame 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(), solve the problem by (temporarily) setting the Camera::revolveAroundPoint() to a point on the zoomed region (see the QGLViewer::RAP_FROM_PIXEL mouse binding in the mouse page).

Definition at line 182 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::domElement(), ManipulatedFrame::mouseMoveEvent(), ManipulatedCameraFrame::mouseMoveEvent(), and ManipulatedFrame::operator=().

void wheelEvent	(	QWheelEvent *const	event,
		Camera *const	camera
	)		`[protected, virtual]`

Overloading of MouseGrabber::wheelEvent().

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

Reimplemented from MouseGrabber.

Reimplemented in ManipulatedCameraFrame.

Definition at line 473 of file manipulatedFrame.cpp.

References Camera::frame(), ManipulatedFrame::manipulated(), Frame::orientation(), Frame::position(), Camera::position(), Frame::referenceFrame(), Quaternion::rotate(), Frame::setConstraint(), Frame::transformOf(), Frame::translate(), and ManipulatedFrame::wheelSensitivity().

Referenced by QGLViewer::wheelEvent().

float wheelSensitivity ( ) const [inline]

Returns the mouse wheel sensitivity.

Default value is 1.0. A higher value will make the wheel action more efficient (usually meaning a faster zoom). Use a negative value to invert the zoom in and out directions.

Definition at line 202 of file manipulatedFrame.h.

Referenced by ManipulatedFrame::domElement(), ManipulatedFrame::operator=(), ManipulatedFrame::wheelEvent(), and ManipulatedCameraFrame::wheelEvent().

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

worldsim/3rdParts/qglviewer/manipulatedFrame.h
worldsim/3rdParts/qglviewer/manipulatedFrame.cpp

WorldSim - 0.6.0

ManipulatedFrame Class Reference

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Manipulation sensitivity

Spinning

Mouse event handlers

Current state

MouseGrabber implementation

XML representation

Detailed Description

Inherited functionalities

Advanced functionalities

Constructor & Destructor Documentation

Member Function Documentation