<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> <title>libQGLViewer mouse behavior</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link href="qglviewer.css" rel="stylesheet" type="text/css" /> <link rel="shortcut icon" href="images/qglviewer.ico" type="image/x-icon" /> <link rel="icon" href="images/qglviewer.icon.png" type="image/png" /> </head> <body> <div class="banner"> <a class="qindex highlight" href="index.html">Home</a> <a class="qindex" href="download.html">Download</a> <a class="qindex" href="examples/index.html">Examples</a> <a class="qindex" href="refManual/hierarchy.html">Documentation</a> <a class="qindex" href="developer.html">Developer</a> </div> <h1>Mouse binding customization</h1> <h2>Principles</h2> A mouse click can either perform a given atomic <i>click action</i> (such as selecting an object) or can be the initiation of a <i>mouse action</i> (such as moving the camera). This action is then transmitted to the <code>camera()</code>, the <code>manipulatedFrame()</code> or the <code>mouseGrabber()</code>. <p> The actual behavior is entirely customizable: the <code>ClickAction</code> (triggered when you click) and the <code>MouseAction</code> (activated when you click then drag) can be binded to any mouse button(s) with any <code>Control, Alt, Shift</code> modifier key combination. </p> <p> Default bindings are described below. To sum up, the <code>camera()</code> is the default mouse event receiver while the <code>manipulatedFrame()</code> is used when the <code>Ctrl</code> key is pressed. <br/> The <code>MouseGrabber</code> is specific since its behavior entirely depends on your implementation. See the <a href="refManual/classqglviewer_1_1MouseGrabber.html">MouseGrabber documentation</a> for details. </p> <h2>Customizing your mouse binding</h2> The following functions are illustrated in the <a href="examples/keyboardAndMouse.html">keyboardAndMouse</a> example. <ul> <li> To bind a <code>ClickAction</code>, use <code>setMouseBinding(uint, ClickAction, doubleClick=false, buttonsBefore=Qt::NoButton)</code>: <pre> // 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::ALT + Qt::RightButton, SHOW_ENTIRE_SCENE, true, Qt::MidButton); </pre> </li> <li> To bind a <code>MouseAction</code>, use <code>setMouseBinding(int, MouseHandler, MouseAction, withConstraint=true)</code> (same function name as above, but different parameters): <pre> // Left and right buttons together make a camera zoom : emulates a mouse third button if needed. setMouseBinding(Qt::LeftButton + Qt::RightButton, CAMERA, ZOOM); // Alt + Shift + Left button rotates the manipulatedFrame(). setMouseBinding(Qt::ALT + Qt::SHIFT + Qt::LeftButton, FRAME, ROTATE); </pre> </li> <li> And finally, for the mouse wheel associated action, use <code>setWheelBinding(Qt::KeyboardModifiers, MouseHandler, MouseAction, withConstraint=true)</code>: <pre> // Alt + wheel moves the camera forward. setWheelBinding(Qt::ALT, CAMERA, MOVE_FORWARD); </pre> </li> </ul> <p> The following tables list all the available <code>ClickAction</code> and <code>MouseAction</code> as well as their default associated bindings. Note that the current bindings are always available in the <code>Mouse</code> tab of the help window (press <code>H</code> for help). </p> <center> <table bgcolor="#E0C0F0" border="2" cellspacing="0" cellpadding="5"> <tr bgcolor="#9999CC"> <td><code><b>ClickAction</b></code></td> <td><b>Description</b></td> <td><b>Default binding</b></td> </tr> <tr> <td><code><b>ALIGN_CAMERA</b></code></td> <td>Align the camera axis with the world coordinate system axis.</td> <td>Double click left button</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>ALIGN_FRAME</b></code></td> <td>Align the <code>manipulatedFrame()</code> axis with the camera.</td> <td>Control + double click left button</td> </tr> <tr> <td><code><b>CENTER_FRAME</b></code></td> <td>Translates the <code>manipulatedFrame()</code> to the center of the screen.</td> <td>Control + double click right button</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>CENTER_SCENE</b></code></td> <td>Translates the camera so that the <code>sceneCenter</code> is in the center of the screen.</td> <td>Double click right button</td> </tr> <tr> <td><code><b>NO_CLICK_ACTION</b></code></td> <td>No action, only used as a specific return value in <code>QGLViewer::clickAction()</code>.</td> <td> </td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>SELECT</b></code></td> <td>Calls the <code>QGLViewer::select()</code> function.</td> <td>Shift + Left button</td> </tr> <tr> <td><code><b>RAP_FROM_PIXEL</b></code></td> <td>Set the camera <code>revolveAroundPoint()</code> to the point under pixel (if any).</td> <td>Double click left button with right button pressed</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>RAP_IS_CENTER</b></code></td> <td>Makes the <code>sceneCenter</code> the new camera <code>revolveAroundPoint()</code>.</td> <td>Double click right button with left button pressed</td> </tr> <tr> <td><code><b>SHOW_ENTIRE_SCENE</b></code></td> <td>Translates the camera so that the entire scene is visible.</td> <td>Double click middle button</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>ZOOM_ON_PIXEL</b></code></td> <td>Makes the camera zoom on the pixel under the mouse (if any).</td> <td>Double click left button with middle button pressed</td> </tr> <tr> <td><code><b>ZOOM_TO_FIT</b></code></td> <td>Makes the camera zoom to see the entire scene.</td> <td>Double click right button with middle button pressed</td> </tr> </table> </center> <br /> <br /> <center> <table bgcolor="#E0C0F0" border="2" cellspacing="0" cellpadding="5"> <tr bgcolor="#9999CC"> <td><code><b>MouseAction</b></code></td> <td><code><b>Handler</b></code></td> <td><b>Description</b></td> <td><b>Default binding</b></td> </tr> <tr> <td><code><b>NO_MOUSE_ACTION</b></code></td> <td> </td> <td>No action, only used as a specific return value in <code>QGLViewer::mouseAction()</code>.</td> <td> </td> </tr> <tr bgcolor="#C0C0F0"> <td rowspan="2"><code><b>ROTATE</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Rotates the camera around its <code>revolveAroundPoint()</code>.</td> <td>Left button</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>FRAME</b></code></td> <td>Rotates the <code>manipulatedFrame()</code> around its origin.</td> <td>Control + Left button</td> </tr> <tr> <td rowspan="2"><code><b>ZOOM</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Makes the camera zoom in/out. Speed depends on distance to the scene center.</td> <td>Middle button</td> </tr> <tr> <td><code><b>FRAME</b></code></td> <td>Makes the manipulatedFrame() move closer or further from the camera.</td> <td>Control + Middle button</td> </tr> <tr bgcolor="#C0C0F0"> <td rowspan="2"><code><b>TRANSLATE</b></code></td> <td><code><b>CAMERA</b></code></td> <td rowspan="2">Translates in the camera XY plane.</td> <td>Right button</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>FRAME</b></code></td> <td>Control + Right button</td> </tr> <tr> <td><code><b>MOVE_FORWARD</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Makes the camera go forward at <code>flySpeed()</code> and view direction can be changed.</td> <td> </td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>MOVE_BACKWARD</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Same as <code>MOVE_FORWARD</code> but backward.</td> <td> </td> </tr> <tr> <td><code><b>DRIVE</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Mouse up/down goes forward/backward proportionally to <code>flySpeed()</code> while left/right turns.</td> <td> </td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>LOOK_AROUND</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Change the viewing direction. The camera position is not modified.</td> <td> </td> </tr> <tr> <td><code><b>ROLL</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Rolls camera according to horizontal mouse displacement.</td> <td>Left and middle buttons (fly mode only)</td> </tr> <tr bgcolor="#C0C0F0"> <td rowspan="2"><code><b>SCREEN_ROTATE</b></code></td> <td><code><b>CAMERA</b></code></td> <td rowspan="2">Rotates around an axis orthogonal to the screen.</td> <td>Left and middle buttons</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>FRAME</b></code></td> <td>Control + Left and middle buttons</td> </tr> <tr> <td rowspan="2"><code><b>SCREEN_TRANSLATE</b></code></td> <td><code><b>CAMERA</b></code></td> <td rowspan="2">Translates purely horizontally or vertically wrt screen.</td> <td>Middle and right buttons</td> </tr> <tr> <td><code><b>FRAME</b></code></td> <td>Control + Middle and right buttons</td> </tr> <tr bgcolor="#C0C0F0"> <td><code><b>ZOOM_ON_REGION</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Draws a rectangular region on screen and zooms on it.</td> <td>Shift + Middle button</td> </tr> </table> </center> <p> The <code><b>CAMERA</b></code> and <code><b>FRAME</b></code> default bindings are essentially identical: You simply have to press the <code>Control</code> keyboard modifier to move the <code><b>FRAME</b></code> instead of the <code><b>CAMERA</b></code>. This modifier key can be modified using <code>setHandlerKeyboardModifiers()</code>. </p> Also note that a double click basically automates the normal mouse action. <p> <code>MOVE_FORWARD</code>, <code>MOVE_BACKWARD</code>, <code>LOOK_AROUND</code> and <code>ROLL</code> are specific to the <code><b>CAMERA</b></code> fly mode. Press <code>Space</code> to switch between revolve and fly camera modes. </p> Try the <a href="examples/simpleViewer.html">simpleViewer</a> and <a href="examples/manipulatedFrame.html">manipulatedFrame</a> examples for an illustration. <a name="newBindings"></a> <h2>Defining new mouse bindings</h2> If you want to implement a new mouse behavior, simply overload the <code>mousePressEvent(), mouseMoveEvent(), mouseDoubleClickEvent()</code> and <code>mouseReleaseEvent()</code> callback methods in your <code>QGLViewer</code> derived class. See the <code>QGLViewer::mouseMoveEvent()</code> documentation for details. <p> Use <code>QGLViewer::setMouseBindingDescription()</code> to add an entry in the help window <code>Mouse</code> tab that describes your new mouse binding. </p> <p> See the <a href="examples/keyboardAndMouse.html">keyboardAndMouse</a> example for a practical implementation. </p> <p> If you implemented a new mouse behavior and you think it can be useful for other applications, send me an <a href="mailto:contact@libqglviewer.com">e-mail</a> and I will add it in the standard list. </p> <p> <a href="http://validator.w3.org/check/referer"><img src="images/xhtml.png" alt="Valid XHTML 1.0!" height="31" width="88"/></a> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="images/css.gif" alt="Valid CSS!" width="88" height="31"/></a> <i>Last modified on Monday, December 06, 2010.</i> </p> </body></html>