Mouse binding customization

A mouse click (or a double click) can perform a given atomic action (such as selecting an object) or can be the initiation of a mouse motion (such as moving the camera) that can be transmitted to one of these three entities:

The viewer camera(),
the QGLViewer::manipulatedFrame() or
the QGLViewer::mouseGrabber().

The actual behavior is entirely customizable: QGLViewer provides a list of atomic ClickAction that can be performed when you click, as well as a list of MouseMotion that can be send to the camera or the manipulatedFrame when you move. Any mouse button combination with any Control, Alt, Shift combination can be binded to any of these actions. Several combinations can result in the same action.

The MouseGrabber is specific as its behavior entirely depends on your implementation. See the MouseGrabber documentation page for details.

Customizing your mouse binding

To bind a ClickAction, use setMouseBinding(Qt::ButtonState, ClickAction, doubleClick=false, buttonBefore=Qt::NoButton):

   // Click on the right button to make a selection
   setMouseBinding(Qt::RightButton, SELECT);

   // Pressing the middle button, then double clicking the right button, while pressing Alt shows the entire scene. Cool huh ?
   setMouseBinding(Qt::AltButton | Qt::RightButton, SHOW_ENTIRE_SCENE, true, Qt::MidButton);

To bind a MouseMotion, use setMouseBinding(Qt::ButtonState, MouseHandler, MouseMotion, withConstraint=true):

   // Left and right buttons together make a zoom : emulates a mouse third button if needed.
   setMouseBinding(Qt::LeftButton | Qt::RightButton, CAMERA, ZOOM);

   // Alt + Shift + Left button rotates the manipulatedFrame().
   setMouseBinding(Qt::AltButton | Qt::ShiftButton | Qt::LeftButton, FRAME, ROTATE);

And finally, for the mouse wheel associated action, use setWheelBinding(Qt::ButtonState, MouseHandler, MouseMotion, withConstraint=true):

   // Alt + wheel MOVE_FORWARD.
   setWheelBinding(Qt::AltButton, CAMERA, MOVE_FORWARD);

Note that MouseMotion values should be prefixed by ManipulatedFrame:: (as in ManipulatedFrame::ZOOM) and ClickAction values should be prefixed by QGLViewer:: (as in QGLViewer::SELECT).

The following tables list all the available ClickAction and MouseMotion as well as their associated default bindings.

Click Actions

`ClickAction`	Description	Default binding
`ALIGN_CAMERA`	Align the camera axis with the world coordinate system axis.	Double click left button
`ALIGN_FRAME`	Align the `manipulatedFrame()` axis with the camera.	Control + double click left button
`CENTER_FRAME`	Translates the `manipulatedFrame()` to the center of the screen.	Control + double click right button
`CENTER_SCENE`	Translates the camera so that the `sceneCenter` is in the center of the screen.	Double click right button
`NO_ACTION`	No action, only used as a specific return value in `QGLViewer::clickAtion()`.
`SELECT`	Calls the user-defined `QGLViewer::select()` function.	Shift + Left button
`RAP_FROM_PIXEL`	Set the camera `revolveAroundPoint()` to the point under pixel (if any).	Double click left button with right button pressed
`CENTER_AS_RAP`	Makes the `sceneCenter` the new camera `revolveAroundPoint()`.	Double click right button with left button pressed
`SHOW_ENTIRE_SCENE`	Translates the camera so that the entire scene is visible.	Double click middle button
`ZOOM_ON_PIXEL`	Makes the camera zoom on the pixel under the mouse (if any).	Double click left button with middle button pressed
`ZOOM_OUT`	Makes the camera zoom out to see the entire scene.	Double click middle button with left button pressed

Mouse Action

The list of possible actions that can be applied on the camera() or on the manipulatedFrame() are described by the ManipulatedFrame::MouseMotion. The behavior slightly depends on the actual handler (CAMERA or FRAME).

`MouseMotion`	`Handler`	Description	Default binding
`NO_ACTION`		No action, only used as a specific return value in `QGLViewer::mouseAtion()`.
`ROTATE`	`CAMERA`	Rotates the camera around its `revolveAroundPoint()`.	Left button
`ROTATE`	`FRAME`	Rotates the `manipulatedFrame()` around its position.	Control + Left button
`ZOOM`	`CAMERA`	Makes the camera zoom in/out. Speed depends on distance to the scene.	Middle button
`ZOOM`	`FRAME`	Makes the manipulatedFrame() move closer or further from the camera.	Control + Middle button
`TRANSLATE`	`CAMERA`	Translates in the camera XY plane.	Right button
`TRANSLATE`	`FRAME`	Translates in the camera XY plane.	Control + Right button
`MOVE_FORWARD`	`CAMERA`	Makes the camera go forward at flySpeed() and view direction can be changed.
`LOOK_AROUND`	`CAMERA`	Change the viewing direction. The camera position is not modified.
`MOVE_BACKWARD`	`CAMERA`	Makes the camera go backward at flySpeed() and view direction can be changed.
`SCREEN_ROTATE`	`CAMERA`	Rotates with an axis orthogonal to the screen.	Left and middle buttons
`SCREEN_ROTATE`	`FRAME`	Rotates with an axis orthogonal to the screen.	Control + Left and middle buttons
`SCREEN_ROTATE_BOTTOM`	`CAMERA`	Rotates around a point located in the bottom of the screen, in the middle.
`SCREEN_TRANSLATE`	`CAMERA`	Translates purely horizontally or vertically.	Middle and right buttons
`SCREEN_TRANSLATE`	`FRAME`	Translates purely horizontally or vertically.	Control + Middle and right buttons

The CAMERA and FRAME default bindings are essentially indentical : you simply have to press the Control state key to move the FRAME. This default state key can be modified using setMouseStateKey().

Also note that a double click basically automates the normal mouse action.

Try the simpleViewer and manipulatedFrame examples for an illustration.

Defining new mouse actions

For a more complete redefinition of the mouse behavior, you should overload the QGLViewer::mousePressEvent(QMouseEvent *e), mouseMoveEvent(), mouseDoubleClickEvent() and mouseReleaseEvent() functions. See the QGLViewer::mouseMoveEvent() documentation for details and code samples.

If you implemented a new mouse behavior and you think it can be useful for other applications, send me an e-mail and I'll add in the list.

Last modified on Tuesday, July 22 2003.