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
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"><HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<META NAME="GENERATOR" CONTENT="Adobe FrameMaker 5.5/HTML Export Filter">
<LINK REL="STYLESHEET" HREF="VisualRef.css" CHARSET="ISO-8859-1" TYPE="text/css">
<TITLE> Description of Objects in VPython</TITLE>
</HEAD>
<BODY BGCOLOR="#ffffff">
<DIV CLASS="navigation"><table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="display.html"><img src="icons/previous.gif" border="0" height="32"
alt="Previous Page" width="32"></A></td>
<td><A HREF="index.html"><img src="icons/up.gif" border="0" height="32"
alt="Up One Level" width="32"></A></td>
<td><A HREF="keyboard.html"><img src="icons/next.gif" border="0" height="32"
alt="Next Page" width="32"></A></td>
<td align="center" width="100%">Visual Reference</td>
<td><A HREF="index.html"><img src="icons/contents.gif" border="0" height="32"
alt="Contents" width="32"></A></td>
<td><img src="icons/blank.gif" border="0" height="32"
alt="" width="32"></td>
<td><img src="icons/blank.gif" border="0" height="32"
alt="" width="32"></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" HREF="display.html">Controlling Windows</A>
<b class="navlabel">Up:</b> <a class="sectref" HREF="index.html">Contents</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="keyboard.html">Keyboard Interactions</A>
<br><hr>
</DIV>
<DIV>
<H1 CLASS="Heading-1"> <font color="#0000A0">Mouse Interactions</font></H1>
</DIV>
<DIV>
<P CLASS="Normal"><font color="#0000A0">Introduction</font></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"><font color="#0000A0">Different kinds of mouse</font></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 SHIFT key, and the middle button is invoked by
holding down the CTRL key. </P>
<P CLASS="Normal"> <font color="#0000A0">Current state of mouse</font></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 only spheres,
boxes, cylinders, and convex can 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> = 1 if the ALT key
is down, otherwise 0</p>
<p class="attributes"><span class="attribute">ctrl</span> = 1 if the CTRL key
is down, otherwise 0 (for a one-button mouse, meaningful only if mouse buttons
up)</p>
<p class="attributes"><span class="attribute">shift</span> = 1 if the SHIFT
key is down, otherwise 0 (for a one-button mouse, meaningful only if mouse
buttons up)</p>
<p class="attributes">Note that programs that depend on modifying a mouse event
with CTRL or SHIFT will not work properly with a one-button mouse (e.g. most
Macintosh systems), since CTRL invokes "middle" button, and SHIFT
invokes "right" button.</p>
<p class="Normal"></p>
<P CLASS="Normal"><font color="#0000A0">Getting events</font></P>
<P CLASS="Normal">There are four kinds of mouse events: press, click, drag,
and drop:</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 or very slight movement of the mouse.<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. </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"><font color="#0000A0">Additional information obtained with
getevent() or getclick()</font></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="Normal"></p>
<P CLASS="attributes"><span class="attribute">press</span> = 'left' or 'right'
or 'middle' for a press event, or None</P>
<P CLASS="attributes"><span class="attribute">click</span> = 'left' or 'right'
or 'middle' for a click event, 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_click.html">Click example</a>.</P>
<P CLASS="attributes"><span class="attribute">drag</span> = 'left' or 'right'
or 'middle' for a drag event, 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' or 'right'
or 'middle' for a drop event, or None</P>
<P CLASS="attributes"><span class="attribute">release</span> = 'left' or 'right'
or 'middle' following click and drop events, indicating which button was released,
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">click</span>, <span class="attribute">drag</span>,
and <span class="attribute">drop</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">click</span>, <span class="attribute">drag</span>,
and <span class="attribute">drop</span> with the right button are invisible
to your program.</p>
<p class="Normal"><font color="#0000A0"><a name="alternative"></a>Projecting
mouse position onto a given plane</font></p>
<p class="Normal"> Here is a way to get the mouse position relative to a particular
plane in space:</p>
<h2 class="program0"> temp = scene.mouse.project(normal=(0,1,0), point=(0,3,0))</h2>
<p class="program"> if temp: # temp is None if no intersection with plane</p>
<p class="program"> 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>
<h2 class="program0"> temp = scene.mouse.project(normal=(0,1,0), d=3)</h2>
<p class="Normal"> </p>
</div>
<DIV CLASS="navigation">
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A HREF="display.html"><img src="icons/previous.gif" border="0" height="32"
alt="Previous Page" width="32"></A></td>
<td><A HREF="index.html"><img src="icons/up.gif" border="0" height="32"
alt="Up One Level" width="32"></A></td>
<td><A HREF="keyboard.html"><img src="icons/next.gif" border="0" height="32"
alt="Next Page" width="32"></A></td>
<td align="center" width="100%">Visual Reference</td>
<td><A HREF="index.html"><img src="icons/contents.gif" border="0" height="32"
alt="Contents" width="32"></A></td>
<td><img src="icons/blank.gif" border="0" height="32"
alt="" width="32"></td>
<td><img src="icons/blank.gif" border="0" height="32"
alt="" width="32"></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="display.html">Controlling
Windows</a> <b class="navlabel">Up:</b> <a class="sectref" HREF="index.html">Contents</A>
<b class="navlabel">Next:</b> <a class="sectref" HREF="keyboard.html">Keyboard Interactions</A> <br>
<hr>
</DIV>
</BODY>
</HTML>
|
