Mouse binding customization

Principles

A mouse click can either perform a given atomic click action (such as selecting an object) or can be the initiation of a mouse action (such as moving the camera). This action is then transmitted to the camera(), the manipulatedFrame() or the mouseGrabber().

The actual behavior is entirely customizable: the ClickAction (triggered when you click) and the MouseAction (activated when you click then drag) can be binded to any mouse button(s) with any Control, Alt, Shift modifier key combination.

Default bindings are described below. To sum up, the camera() is the default mouse event receiver while the manipulatedFrame() is used when the Ctrl key is pressed.
The MouseGrabber is specific since its behavior entirely depends on your implementation. See the MouseGrabber documentation for details.

Customizing your mouse binding

The following functions are illustrated in the keyboardAndMouse example.

The following tables list all the available ClickAction and MouseAction as well as their default associated bindings. Note that the current bindings are always available in the Mouse tab of the help window (press H for help).

On Mac OS X, following Qt's convention, the Control modifier corresponds to the command key, and Meta is the control key.

ClickAction bindings

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_CLICK_ACTION No action, only used as a specific return value in QGLViewer::clickAction().  
SELECT Calls the QGLViewer::select() function. Shift + Left button
RAP_FROM_PIXEL Set the camera pivotPoint() to the point under pixel.
If no point is found, resets the pivotPoint() to sceneCenter .
Shift + right button
RAP_IS_CENTER Makes the sceneCenter the new camera pivotPoint().  
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). Z + left button
ZOOM_TO_FIT Makes the camera zoom to see the entire scene. Z + right button

MouseAction bindings

MouseAction Handler Description Default binding
NO_MOUSE_ACTION   No action, only used as a specific return value in QGLViewer::mouseAction().  
ROTATE CAMERA Rotates the camera around its pivotPoint(). Left button
FRAME Rotates the manipulatedFrame() around its origin. Control + Left button
ZOOM CAMERA Makes the camera zoom in/out. Speed depends on distance to the scene center. Middle button
FRAME Makes the manipulatedFrame() move closer or further from the camera. Control + Middle button
TRANSLATE CAMERA Translates in the camera XY plane. Right button
FRAME Control + Right button
MOVE_FORWARD CAMERA Makes the camera go forward at flySpeed() and view direction can be changed.  
MOVE_BACKWARD CAMERA Same as MOVE_FORWARD but backward.  
DRIVE CAMERA Mouse up/down goes forward/backward proportionally to flySpeed() while left/right turns.  
LOOK_AROUND CAMERA Change the viewing direction. The camera position is not modified.  
ROLL CAMERA Rolls camera according to horizontal mouse displacement.  
SCREEN_ROTATE CAMERA Rotates around an axis orthogonal to the screen. R + left button
FRAME Control + R + left button
SCREEN_TRANSLATE CAMERA Translates purely horizontally or vertically wrt screen.  
FRAME  
ZOOM_ON_REGION CAMERA Draws a rectangular region on screen and zooms on it. Shift + middle button

As you can see, the CAMERA and FRAME default bindings are essentially identical: You simply have to press the Control keyboard modifier to move the FRAME instead of the CAMERA. This modifier key can be modified using setHandlerKeyboardModifiers().

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

MOVE_FORWARD, MOVE_BACKWARD, LOOK_AROUND and ROLL are specific to the CAMERA fly mode. Press Space to switch between revolve and fly camera modes.

Try the simpleViewer and manipulatedFrame examples for an illustration.

Defining new mouse bindings

If you want to implement a new mouse behavior, simply overload the mousePressEvent(), mouseMoveEvent(), mouseDoubleClickEvent() and mouseReleaseEvent() callback methods in your QGLViewer derived class. See the QGLViewer::mouseMoveEvent() documentation for details.

Use QGLViewer::setMouseBindingDescription() to add an entry in the help window Mouse tab that describes your new mouse binding.

See the keyboardAndMouse example for a practical implementation.

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

Valid XHTML 1.0! Valid CSS! Last modified on Monday, November 13, 2017.