<!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>
distrib
>
Mandriva
>
10.0
>
i586
>
media
>
contrib
>
by-pkgid
>
9347541fe87a5ea3f3b8dbc50f660e8e
>
files
>
247
