libQGLViewer mouse behavior

Home Download Gallery Documentation Developer

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

- To bind a `ClickAction`, use `setMouseBinding(Qt::KeyboardModifiers, Qt::MouseButton, ClickAction, doubleClick=false, buttonsBefore=Qt::NoButton)`:

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

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

- To bind a `MouseAction`, use `setMouseBinding(Qt::KeyboardModifiers, Qt::MouseButton, MouseHandler, MouseAction, withConstraint=true)` (same function name as above, but different parameters):

      // Control, Shift and Left buttons together make a camera zoom.
      setMouseBinding(Qt::ControlModifier | Qt::ShiftModifier, Qt::LeftButton, CAMERA, ZOOM);

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

- And finally, for the mouse wheel associated action, use `setWheelBinding(Qt::KeyboardModifiers, MouseHandler, MouseAction, withConstraint=true)`:

      // Alt + wheel moves the camera forward.
      setWheelBinding(Qt::ALT, CAMERA, MOVE_FORWARD);

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.

Last modified on #DATE#.