<!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=iso-8859-1" /> <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> <table class="banner"> <tr> <td align="center"><a class="qindex" href="index.html"><b>Home</b></a></td> <td align="center"><a class="qindex" href="refManual/hierarchy.html"><b>Documentation</b></a></td> <td align="center"><a class="qindex" href="download.html"><b>Download</b></a></td> <td align="center"><a class="qindex" href="examples/index.html"><b>Screenshots</b></a></td> <td align="center"><a class="qindex" href="developer.html"><b>Developer</b></a></td> </tr> </table> <h1>Mouse binding customization</h1> <h2>Principles</h2> A mouse click (or a double click) can 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) that can be transmitted to one of these three entities: <ul> <li>The <code>QGLViewer::camera()</code>, </li> <li>the <code>QGLViewer::manipulatedFrame()</code> or</li> <li>the <code>QGLViewer::mouseGrabber()</code>.</li> </ul> <p> The actual behavior is entirely customizable: QGLViewer provides a list of atomic <code>ClickAction</code> that can be performed when you click, as well as a list of <code>MouseAction</code> that can be send to the <code>camera</code> or the <code>manipulatedFrame</code> when you move. Any mouse button combination with any <code>Control, Alt, Shift</code> combination can be binded to any of these actions. Several combinations can result in the same action. </p><p> The <code>MouseGrabber</code> is specific as its behavior entirely depends on your implementation. See the <a href="refManual/classqglviewer_1_1MouseGrabber.html">MouseGrabber documentation page</a> for details. </p> <h2>Customizing your mouse binding</h2> <p> The following functions are illustrated in the <a href="examples/keyboardAndMouse.html">keyboardAndMouse</a> example. </p> To bind a <code>ClickAction</code>, use <code>setMouseBinding(Qt::ButtonState, ClickAction, doubleClick=false, buttonBefore=Qt::NoButton)</code>. Example : <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::AltButton | Qt::RightButton, SHOW_ENTIRE_SCENE, true, Qt::MidButton); </pre> To bind a <code>MouseAction</code>, use <code>setMouseBinding(Qt::ButtonState, MouseHandler, MouseAction, withConstraint=true)</code>. As in : <pre> // 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); </pre> And finally, for the mouse wheel associated action, use <code>setWheelBinding(Qt::ButtonState, MouseHandler, MouseAction, withConstraint=true)</code>: <pre> // Alt + wheel MOVE_FORWARD. setWheelBinding(Qt::AltButton, CAMERA, MOVE_FORWARD); </pre> <p> The following tables list all the available <code>ClickAction</code> and <code>MouseAction</code> as well as their associated default bindings. </p> <h2>Click Actions</h2> <center> <table bgcolor="#DDBBEE" border="2" cellspacing="0" cellpadding="5"> <tr bgcolor="#BBBBFF"> <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="#BBBBFF"> <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="#BBBBFF"> <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::clickAtion()</code>.</td> <td> </td> </tr> <tr bgcolor="#BBBBFF"> <td><code><b>SELECT</b></code></td> <td>Calls the user-defined <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="#BBBBFF"> <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="#BBBBFF"> <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 out to see the entire scene.</td> <td>Double click right button with middle button pressed</td> </tr> </table> </center> Note that Qt, until version 3.1, has a bug that prevents multiple button actions. <h2>Mouse Actions</h2> The list of possible actions that can be applied on the <code>camera()</code> or on the <code>manipulatedFrame()</code> are described by a <code>QGLViewer::MouseAction</code>. The behavior slightly depends on the actual handler (<code><b>CAMERA</b></code> or <code><b>FRAME</b></code>). <center> <table bgcolor="#DDBBEE" border="2" cellspacing="0" cellpadding="5"> <tr bgcolor="#BBBBFF"> <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::mouseAtion()</code>.</td> <td> </td> </tr> <tr bgcolor="#BBBBFF"> <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="#BBBBFF"> <td><code><b>FRAME</b></code></td> <td>Rotates the <code>manipulatedFrame()</code> around its position.</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.</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="#BBBBFF"> <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="#BBBBFF"> <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 flySpeed() and view direction can be changed.</td> <td> </td> </tr> <tr bgcolor="#BBBBFF"> <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>MOVE_BACKWARD</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Makes the camera go backward at flySpeed() and view direction can be changed.</td> <td> </td> </tr> <tr bgcolor="#BBBBFF"> <td rowspan="2"><code><b>SCREEN_ROTATE</b></code></td> <td><code><b>CAMERA</b></code></td> <td rowspan="2">Rotates with an axis orthogonal to the screen.</td> <td>Left and middle buttons</td> </tr> <tr bgcolor="#BBBBFF"> <td><code><b>FRAME</b></code></td> <td>Control + Left and middle buttons</td> </tr> <tr> <td><code><b>SCREEN_ROTATE_BOTTOM</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Rotates around a point located in the bottom of the screen, in the middle.</td> <td> </td> </tr> <tr bgcolor="#BBBBFF"> <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.</td> <td>Middle and right buttons</td> </tr> <tr bgcolor="#BBBBFF"> <td><code><b>FRAME</b></code></td> <td>Control + Middle and right buttons</td> </tr> <tr> <td><code><b>ZOOM_ON_REGION</b></code></td> <td><code><b>CAMERA</b></code></td> <td>Draws a rectangular region on screen and zoom on it.</td> <td>Shift + Middle button</td> </tr> </table> </center> The <code><b>CAMERA</b></code> and <code><b>FRAME</b></code> default bindings are essentially indentical : you simply have to press the <code>Control</code> state key to move the <code><b>FRAME</b></code>. This default state key can be modified using <code>setMouseStateKey()</code>. <p> Also note that a double click basically automates the normal mouse action. </p> <p> Try the <a href="examples/simpleViewer.html">simpleViewer</a> and <a href="examples/manipulatedFrame.html">manipulatedFrame</a> examples for an illustration. </p> <h2>Defining new mouse actions</h2> For a more complete redefinition of the mouse behavior, you should overload the <code>QGLViewer::mousePressEvent(QMouseEvent *e), mouseMoveEvent(), mouseDoubleClickEvent()</code> and <code>mouseReleaseEvent()</code> functions. See the <code>QGLViewer::mouseMoveEvent()</code> documentation and the <a href="examples/keyboardAndMouse.html">keyboardAndMouse</a> example for details and code samples. <p> If you implemented a new mouse behavior and you think it can be useful for other applications, send me an <a href="mailto:Gilles.Debunne at imag dot fr?Subject=QGLViewer">e-mail</a> and I'll 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" border="0"/></a> <a href="http://jigsaw.w3.org/css-validator/check/referer"><img src="images/css.png" alt="Valid CSS!" width="88" height="31" border="0"/></a> <i>Last modified on Thursday, February 5, 2004.</i> </p> </body></html>