vpython.docs/visual/mouse.html at master · vpython/vpython.docs

History

262 lines (256 loc) · 20.9 KB

Raw

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>mouse</title>

<!--

function MM_jumpMenu(targ,selObj,restore){ //v3.0

eval(targ+".location='"+selObj.options[selObj.selectedIndex].value+"'");

if (restore) selObj.selectedIndex=0;

}

//-->

</script>

</head>

<body>

<tr>

If you're new to Python

and VPython: <a href="VisualIntro.html">Introduction</a>

A VPython <a href="VPython_Intro.pdf" target="_blank">tutorial</a>

<a href="primitives.html">Pictures</a> of 3D objects

Choose an object:

<option>Choose an object</option>

<option value="cylinder.html">Overview</option>

<option value="arrow.html">arrow</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="extrusion.html">extrusion</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="sphere.html">sphere</option>

</select>

Work with objects:

<option>Choose an option</option>

<option value="color.html">Color/Opacity</option>

<option value="materials.html">Materials/Textures</option>

<option value="shapes.html">Shapes Library</option>

<option value="paths.html">Paths Library</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="controls.html">Buttons/Sliders</option>

<option value="graph.html">Graphs</option>

<option value="lights.html">Lighting</option>

<option value="files.html">Read/Write Files</option>

<option value="trail.html">Leaving a Trail</option>

<option value="vector.html">Vector Operations </option>

<option value="factorial.html">factorial/combin</option>

</select>

Windows &amp Events:

<option>Choose a topic</option>

<option value="display.html">Windows</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>

</select>

What's new in <a href="new_features.html">Visual 5</a>

<a href="http://vpython.org" target="_blank">VPython web site</a>

<a href="license.txt" target="_blank">Visual license</a>

<a href="http://www.python.org" target="_blank">Python web site</a>

<a href="http://www.python.org/doc/2.5.2/lib/module-math.html" target="_blank">Math module</a> (sqrt etc.)

<a href="http://www.scipy.org/Documentation" target="_blank">Numpy module</a> (arrays) </td>

<h1 class="Heading-1"> Mouse Interactions</h1>

Introduction

Mouse objects are obtained from the mouse attribute of a

display object such as scene. For example,

to obtain mouse input from the default window created by Visual, refer to scene.mouse. For basic examples of mouse handling,

see <a href="mouse_click.html">Click example</a>, <a href="mouse_drag.html">Drag

example</a>, and <a href="#pause">Pausing for either mouse or keyboard input</a>.

A mouse object has a group of attributes corresponding to

the current state of the mouse. It also has functions getevent() and getclick(), 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, getevent() and getclick() will stop program execution until this happens.

Different kinds of mouse

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.

Design for left-button events if possible

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.

Current state of mouse

pos The current 3D position

of the mouse cursor; scene.mouse.pos. Visual

always chooses a point in the plane parallel to the screen and passing through display.center. (See <a href="#alternative">Projecting

mouse information onto a given plane</a> for other options.)

pick The nearest object

in the scene which falls under the cursor, or None. At present curve, label, helix, extrusion, and faces cannot be picked. The picked object is scene.mouse.pick.

pickpos The 3D point on

the surface of the picked object which falls under the cursor, or None; scene.mouse.pickpos.

camera The read-only current

position of the camera as positioned by the user, scene.mouse.camera.

For example, mag(scene.mouse.camera-scene.center) 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 scene.forward and scene.center,

described in <a class="sectref" href="display.html">Controlling Windows</a>.

ray A unit vector pointing

from camera in the direction of the mouse cursor. The points under the mouse

cursor are exactly { camera + t*ray for t>0}.

The camera and ray attributes together define all of the

3D points under the mouse cursor.

project() Projects position

onto a plane. See <a href="#alternative">Projecting mouse position onto a given

plane</a>.

alt = True if the ALT key

is down, otherwise False

ctrl = True if the CTRL key

is down, otherwise False (for a one-button mouse, meaningful only if mouse buttons

up)

shift = True if the SHIFT

key is down, otherwise False (for a one-button mouse, meaningful only if mouse

buttons up)

Getting events

There are five kinds of mouse events: press, click, drag,

drop, and release:

A press event occurs when a mouse button

is depressed.

A click event occurs when all mouse buttons

are released with no movement of the mouse. (This is also a release event.)

Note that a click event happens when the mouse button is released. See <a href="mouse_click.html">Click example</a>.

A drag event occurs when the mouse is moved

slightly after a press event, with mouse buttons still down.

   This can be used to signal the beginning of dragging an

object. See <a href="mouse_drag.html">Drag example</a>.

A drop event occurs when the mouse buttons

are released after a drag event. (This is also a release event.)

A release event occurs when the mouse buttons

are released after a click or drag event.

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 scene.mouse.pos.

Here is how to tell that an event has happened, and to get information about

that event:

events The number of events

(press, click, drag, or drop) which have been queued; e.g. scene.mouse.events.

scene.mouse.events = 0 may be used to discard

all input. No value other than zero can be assigned.

getevent() Obtains the

earliest mouse event and removes it from the input queue. If no events are

waiting in the queue (that is, if scene.mouse.events is zero), getevent() waits until the user enters

a mouse event (press, click, drag, or drop). getevent() returns an object with attributes similar to a mouse object: pos, button, pick, pickpos, camera, ray, project(), alt, ctrl, and shift.

These attributes correspond to the state of the mouse when the event took

place. For example, after executing mm = scene.mouse.getevent() you can look at the various properties of this event, such as mm.pos, mm.pick, mm.drag (see below), etc.

If you are interested in every type of event (press, click,

drag, and drop), you must use events and getevent().

If you are only interested in left click events (left button down and up without

significant mouse movement), you can use clicked and getclick():

clicked The number of left

clicks which have been queued; e.g. scene.mouse.clicked.

This does not include a count of nonclick events (press, drag, or drop).

getclick() 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 scene.mouse.clicked is zero), getclick() waits until the user clicks. Otherwise getclick() is just like getevent().

It is a useful debugging technique to insert scene.mouse.getclick() into your program at a point where you would like to stop temporarily to examine

the scene. Then just click to proceed.

Additional information obtained with

getevent() or getclick()

In addition to the information available with scene.mouse, getevent() and getclick() furnish this additional information:

press = 'left'

for a press event, or 'right'

or 'middle', or None

click = 'left' for

a click event, or 'right' or 'middle', or None. See <a href="mouse_click.html">Click example</a>.

drag = 'left' for

a drag event, or 'right' or 'middle', or None;

in this case pos 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>.

drop = 'left' for

a drop event, or 'right' or 'middle', or None

release = 'left'

following click and drop events, indicating which button was released,

or 'right' or 'middle', or None

button = 'left', 'right', or 'middle'. After executing mm = scene.mouse.getevent(), the expression mm.button == 'left' is true if the left button is currently down.

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 drag or drop is true (in Python, a nonempty string

such as 'left' is true, None is false). Unless you disable user zoom (scene.userzoom

= False), press, click, drag, drop,

and release with the middle button are invisible

to your program. Unless you disable user spin (scene.userspin

= False), press, click, drag, drop,

and release with the right button are invisible

to your program.

<a name="alternative" id="alternative"></a>Projecting

mouse position onto a given plane

Here is a way to get the mouse position relative to a particular

plane in space:

temp = scene.mouse.project(normal=(0,1,0), point=(0,3,0))

if temp: # temp is None if no intersection with plane

ball.pos = temp

This projects the mouse cursor onto a plane that is perpendicular

to the specified normal. If point 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.

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.

You can instead specify a perpendicular distance d from the origin to the plane that is perpendicular to the specified normal.

The example above is equivalent to

temp = scene.mouse.project(normal=(0,1,0), d=3)

<a name="pause" id="pause"></a>Pausing for mouse or keyboard input

Often you want to pause for either mouse or keyboard input. Copy the following function into your program, and then insert pause() wherever you want to pause.

def pause():

while True:

rate(50)

if scene.mouse.events:

m = scene.mouse.getevent()

if m.click == 'left': return

elif scene.kb.keys:

k = scene.kb.getkey()

return

</td>

</tr>

<tr>

</tr>

</table>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

mouse.html

Latest commit

History

mouse.html

File metadata and controls