/usr/share/doc/python-visual/html/mouse.html is in python-visual 1:5.12-1.3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 | <!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"><!-- InstanceBegin template="/visual/Templates/template.dwt" codeOutsideHTMLIsLocked="false" -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- InstanceBeginEditable name="doctitle" -->
<title>mouse</title>
<!-- InstanceEndEditable -->
<!-- InstanceBeginEditable name="head" -->
<link href="VisualRef.css" rel="stylesheet" type="text/css" />
<!-- InstanceEndEditable -->
<script type="text/javascript">
<!--
function MM_jumpMenu(targ,selObj,restore){ //v3.0
eval(targ+".location='"+selObj.options[selObj.selectedIndex].value+"'");
if (restore) selObj.selectedIndex=0;
}
//-->
</script>
<link href="VisualRef.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table width="800" border="0" cellpadding="0" cellspacing="0">
<!--DWLayoutDefaultTable-->
<tr>
<td width="10" valign="top" bgcolor="#FFFFFF"><!--DWLayoutEmptyCell--> </td>
<td width="10" height="272" valign="top" bgcolor="#DDDDDD"><p> </p> </td>
<td width="173" valign="top" bgcolor="#DDDDDD"><p class="Normal"><a href="index.html">Home</a></p>
<p class="Normal">If you're new to Python <br />
and VPython: <a href="VisualIntro.html">Introduction</a></p>
<p class="Normal">A VPython <a href="VPython_Intro.pdf" target="_blank">tutorial</a></p>
<p class="Normal"><a href="primitives.html">Pictures</a> of 3D objects</p>
<p class="Normal">Choose a 3D object:</p>
<select name="jumpMenu4" id="jumpMenu4" onchange="MM_jumpMenu('parent',this,0)">
<option>Choose an object</option>
<option value="cylinder.html">Overview</option>
<option value="arrow.html">arrow</option>
<option value="box.html">box</option>
<option value="cone.html">cone</option>
<option value="convex.html">convex</option>
<option value="curve.html">curve</option>
<option value="cylinder.html">cylinder</option>
<option value="ellipsoid.html">ellipsoid</option>
<option value="faces.html">faces</option>
<option value="frame.html">frame</option>
<option value="helix.html">helix</option>
<option value="label.html">label</option>
<option value="lights.html">lights</option>
<option value="points.html">points</option>
<option value="pyramid.html">pyramid</option>
<option value="ring.html">ring</option>
<option value="sphere.html">sphere</option>
</select>
<p class="Normal">Work with 3D objects:</p>
<select name="jumpMenu4" id="jumpMenu5" onchange="MM_jumpMenu('parent',this,0)">
<option>Choose an option</option>
<option value="color.html">Color & Opacity</option>
<option value="lights.html">Lighting</option>
<option value="materials.html">Materials & Textures</option>
<option value="defaults.html">Defaults</option>
<option value="rate.html">Animation Speed</option>
<option value="rotation.html">Rotations</option>
<option value="options.html">Additional Options</option>
<option value="delete.html">Delete an Object</option>
<option value="float.html">3/4 = 0?</option>
</select>
<p class="Normal">Windows, Events, & Files:</p>
<select name="jumpMenu4" id="jumpMenu6" onchange="MM_jumpMenu('parent',this,0)">
<option>Choose a topic</option>
<option value="display.html">Windows</option>
<option value="lights.html">Lighting</option>
<option value="mouse.html">Mouse Events</option>
<option value="mouse_click.html"> Mouse Click</option>
<option value="mouse_drag.html"> Mouse Drag</option>
<option value="keyboard.html">Keyboard Events</option>
<option value="controls.html">Buttons and Sliders</option>
<option value="files.html">Reading/Writing Files</option>
</select>
<p class="Normal"><a href="vector.html">Vector operations </a></p>
<p class="Normal"><a href="graph.html">Graphs</a></p>
<p class="Normal"><a href="factorial.html">factorial/combin</a></p>
<p class="Normal">What's new in <a href="new_features.html">Visual 5</a></p>
<p class="Normal"><a href="http://vpython.org" target="_blank">VPython web site</a><br />
<a href="license.txt" target="_blank">Visual license</a><br />
<a href="http://www.python.org" target="_blank">Python web site</a> <br />
<a href="http://www.python.org/doc/2.5.2/lib/module-math.html" target="_blank">Math module</a> (sqrt etc.)<br />
<a href="http://www.scipy.org/Documentation" target="_blank">Numpy module</a> (arrays) </p></td>
<td width="21" valign="top" bgcolor="#FFFFFF"><!--DWLayoutEmptyCell--> </td>
<td width="586" rowspan="2" valign="top"><!-- InstanceBeginEditable name="content" -->
<h1 class="Heading-1"> <font color="#0000A0">Mouse Interactions</font></h1>
<p class="Normal"><strong><font color="#0000A0">Introduction</font></strong></p>
<p class="Normal"> Mouse objects are obtained from the mouse attribute of a
display object such as <span class="attribute">scene</span>. For example,
to obtain mouse input from the default window created by Visual, refer to <span class="attribute">scene.mouse</span>. For basic examples of mouse handling,
see <a href="mouse_click.html">Click example</a> and <a href="mouse_drag.html">Drag
example</a>.</p>
<p class="Normal"> A mouse object has a group of attributes corresponding to
the current state of the mouse. It also has functions <span class="attribute">getevent()</span> and <span class="attribute">getclick()</span>, which return an object with
similar attributes corresponding to the state of the mouse when the user last
did something with the mouse buttons. If the user has not already done something
with the mouse buttons, <span class="attribute">getevent()</span> and <span class="attribute">getclick()</span> will stop program execution until this happens.</p>
<p class="Normal"><strong><font color="#0000A0">Different kinds of mouse</font></strong></p>
<p class="Normal">The mouse routines can handle a three-button mouse,
with "left",
"right", and "middle" buttons. For systems with
a two-button mouse, the "middle" button consists of the
left and right buttons pressed together. For systems with a one button
mouse, the right button is invoked by holding down the Command key,
and the middle button is invoked by holding down the Option key. </p>
<p class="Normal"><strong><font color="#0000A0">Design for left-button events if possible</font></strong></p>
<p class="Normal">Visual 5 provides the basic mouse event functionality that was present in Visual 3 for handling events from right and middle buttons when userspin or userzoom is disabled, out of concern for supporting old programs. However, it has become evident that there are limitations to this approach which could preclude some kinds of mouse handling that people might want to do in the future. For example, you might want to allow userspin with right drags yet also pick up right clicks. For that reason it is conceivable that future developments in this area might break existing programs, and therefore for maximum forward compatibility it is prudent to use only left-button interactions in new programs.</p>
<p class="Normal"><strong> <font color="#0000A0">Current state of mouse</font></strong></p>
<p class="attributes"> <span class="attribute">pos</span> The current 3D position
of the mouse cursor; <span class="attribute">scene.mouse.pos</span>. Visual
always chooses a point in the plane parallel to the screen and passing through <span class="attribute">display.center</span>. (See <a href="#alternative">Projecting
mouse information onto a given plane</a> for other options.)</p>
<p class="attributes"><span class="attribute">button</span> = None (no buttons
pressed), 'left', 'right', 'middle', or 'wheel' (scroll wheel pressed on some
Windows mouses). Example: <span class="attribute">scene.mouse.button == 'left'</span> is true if the left button is currently down.</p>
<p class="attributes"> <span class="attribute">pick</span> The nearest object
in the scene which falls under the cursor, or None. At present label and helix cannot be picked. The picked object is <span class="attribute">scene.mouse.pick</span>.</p>
<p class="attributes"> <span class="attribute">pickpos</span> The 3D point on
the surface of the picked object which falls under the cursor, or None; <span class="attribute">scene.mouse.pickpos</span>.</p>
<p class="attributes"> <span class="attribute">camera</span> The read-only current
position of the camera as positioned by the user, <span class="attribute">scene.mouse.camera</span><font color="#000000">.
For example, <span class="attribute">mag(scene.mouse.camera-scene.center)</span> is the distance from the center of the scene to the current position of the
camera. If you want to set the camera position and direction by program, use <span class="attribute">scene.forward</span> and <span class="attribute">scene.center</span>,
described in <a class="sectref" href="display.html">Controlling Windows</a>.</font> </p>
<p class="attributes"> <span class="attribute">ray</span> A unit vector pointing
from camera in the direction of the mouse cursor. The points under the mouse
cursor are exactly {<span class="attribute"> camera + t*ray</span> for <span class="attribute">t>0</span>}.</p>
<p class="attributes"> The <span class="attribute">camera</span> and <span class="attribute">ray</span> attributes together define all of the
3D points under the mouse cursor.</p>
<p class="attributes"><span class="attribute">project()</span> Projects position
onto a plane. See <a href="#alternative">Projecting mouse position onto a given
plane</a>. </p>
<p class="attributes"><span class="attribute">alt</span> = True if the ALT key
is down, otherwise False</p>
<p class="attributes"><span class="attribute">ctrl</span> = True if the CTRL key
is down, otherwise False (for a one-button mouse, meaningful only if mouse buttons
up)</p>
<p class="attributes"><span class="attribute">shift</span> = True if the SHIFT
key is down, otherwise False (for a one-button mouse, meaningful only if mouse
buttons up)</p>
<p class="Normal"></p>
<p class="Normal"><strong><font color="#0000A0">Getting events</font></strong></p>
<p class="Normal">There are five kinds of mouse events: press, click, drag,
drop, and release:</p>
<p class="Normal"> A press event occurs when a mouse button
is depressed.</p>
<p class="Normal"> A click event occurs when all mouse buttons
are released with no movement of the mouse. (This is also a release event.)<br />
Note that a click event happens when the mouse button is <i>released</i>. See <a href="mouse_click.html">Click example</a>.</p>
<p class="Normal"> A drag event occurs when the mouse is moved
slightly after a press event, with mouse buttons still down.<br />
This can be used to signal the beginning of dragging an
object. See <a href="mouse_drag.html">Drag example</a>.</p>
<p class="Normal"> A drop event occurs when the mouse buttons
are released after a drag event. (This is also a release event.)</p>
<p class="Normal"> A release event occurs when the mouse buttons
are released after a click or drag event. </p>
<p class="Normal">Between a drag event (start of dragging) and a drop event
(end of dragging), there are no mouse events but you can examine the continuously
updated position of the mouse indicated by <span class="attribute">scene.mouse.pos</span>.
Here is how to tell that an event has happened, and to get information about
that event:</p>
<p class="attributes"><span class="attribute">events</span> The number of events
(press, click, drag, or drop) which have been queued; e.g. <span class="attribute"> scene.mouse.events</span>.<br />
<span class="attribute">scene.mouse.events = 0 </span>may be used to discard
all input. No value other than zero can be assigned.</p>
<p class="attributes"> <span class="attribute">getevent()</span> Obtains the
earliest mouse event and removes it from the input queue. If no events are
waiting in the queue (that is, if <span class="attribute">scene.mouse.events</span> is zero), <span class="attribute">getevent()</span> waits until the user enters
a mouse event (press, click, drag, or drop). <span class="attribute">getevent()</span> returns an object with attributes similar to a mouse object: <span class="attribute">pos</span>, <span class="attribute">button, pick</span>, <span class="attribute">pickpos</span>, <span class="attribute">camera</span>, <span class="attribute">ray</span>, <span class="attribute">project()</span>, <span class="attribute">alt</span>, <span class="attribute">ctrl,</span> and <span class="attribute">shift</span>.
These attributes correspond to the state of the mouse when the event took
place. For example, after executing <span class="attribute">mm = scene.mouse.getevent()</span> you can look at the various properties of this event, such as <span class="attribute">mm.pos</span>, <span class="attribute">mm.pick</span>, <span class="attribute">mm.drag</span> (see below), etc. </p>
<p class="Normal">If you are interested in every type of event (press, click,
drag, and drop), you must use <span class="attribute">events</span> and <span class="attribute">getevent()</span>.
If you are only interested in left click events (left button down and up without
significant mouse movement), you can use <span class="attribute">clicked</span> and <span class="attribute">getclick()</span>:</p>
<p class="attributes"><span class="attribute">clicked</span> The number of left
clicks which have been queued; e.g. <span class="attribute"> scene.mouse.clicked</span>.<br />
This does not include a count of nonclick events (press, drag, or drop).</p>
<p class="attributes"><span class="attribute">getclick()</span> Obtains the
earliest mouse left click event (pressing the left button and releasing it
in nearly the same position) and removes it from the input queue, discarding
any earlier press, drag, or drop events. If no clicks are waiting in the queue
(that is, if <span class="attribute">scene.mouse.clicked</span> is zero), <span class="attribute">getclick()</span> waits until the user clicks. Otherwise <span class="attribute">getclick()</span> is just like <span class="attribute">getevent()</span>. </p>
<p class="Normal">It is a useful debugging technique to insert <span class="attribute">scene.mouse.getclick()</span> into your program at a point where you would like to stop temporarily to examine
the scene. Then just click to proceed.</p>
<p class="Normal"><strong><font color="#0000A0">Additional information obtained with
getevent() or getclick()</font></strong></p>
<p class="Normal"> In addition to the information available with <span class="attribute">scene.mouse</span>, <span class="attribute">getevent()</span> and <span class="attribute">getclick()</span> furnish this additional information:</p>
<p class="attributes"><span class="attribute">press</span> = 'left'
for a press event, or 'right'
or 'middle', or None</p>
<p class="attributes"><span class="attribute">click</span> = 'left' for
a click event, or 'right' or 'middle', or None. See <a href="mouse_click.html">Click example</a>.</p>
<p class="attributes"><span class="attribute">drag</span> = 'left' for
a drag event, or 'right' or 'middle', or None;
in this case <span class="attribute">pos</span> <span class="attribute"></span>and other attributes correspond to the state
of the mouse at the time of the original press event, so as not to lose initial
position information. See <a href="mouse_drag.html">Drag example</a>.</p>
<p class="attributes"><span class="attribute">drop</span> = 'left' for
a drop event, or 'right' or 'middle', or None</p>
<p class="attributes"><span class="attribute">release</span> = 'left'
following click and drop events, indicating which button was released,
or 'right' or 'middle', or None</p>
<p class="Normal">Normally, dragging with right or middle button represents
spin or zoom, and is handled automatically by Visual, so you can check for
left-button drag or drop events simply by checking whether <span class="attribute">drag</span> or <span class="attribute">drop</span> is true (in Python, a nonempty string
such as 'left' is true, None is false). Unless you disable user zoom (<span class="attribute">scene.userzoom
= 0</span>), <span class="attribute">press, click</span>, <span class="attribute">drag, drop</span>,
and <span class="attribute">release</span> with the middle button are invisible
to your program. Unless you disable user spin (<span class="attribute">scene.userspin
= 0</span>), <span class="attribute">press, click</span>, <span class="attribute">drag, drop</span>,
and <span class="attribute">release</span> with the right button are invisible
to your program.</p>
<p class="Normal"><font color="#0000A0"><a name="alternative" id="alternative"></a><strong>Projecting
mouse position onto a given plane</strong></font></p>
<p class="Normal"> Here is a way to get the mouse position relative to a particular
plane in space:</p>
<p class="program"> temp = scene.mouse.project(normal=(0,1,0), point=(0,3,0))<br />
if temp: # temp is None if no intersection with plane<br />
ball.pos = temp</p>
<p class="Normal"> This projects the mouse cursor onto a plane that is perpendicular
to the specified normal. If <span class="attribute">point</span> is not
specified, the plane passes through the origin. It returns a 3D position,
or None if the projection of the mouse misses the plane.</p>
<p class="Normal"> In the example shown above, the user of your program will
be able to use the mouse to place balls in a plane parallel to the xy plane,
a height of 3 above the xy plane, no matter how the user has rotated the point
of view.</p>
<p class="Normal">You can instead specify a perpendicular distance <span class="attribute">d</span> from the origin to the plane that is perpendicular to the specified normal.
The example above is equivalent to</p>
<p class="program"> temp = scene.mouse.project(normal=(0,1,0), d=3)</p>
<!-- InstanceEndEditable --></td>
</tr>
<tr>
<td height="16" colspan="4"></td>
</tr>
</table>
</body>
<!-- InstanceEnd --></html>
|