Keyboard Interactions

The simplest keyboard interaction is to wait for the user to press a key before proceeding in the program. Suppose the 3D display is in scene, the default window created by VPython. Here is a way to wait for a keypress:

key
= scene.kb.getkey() # wait for and get keyboard info

If len(key) == 1, the input is a single printable character
such as 'b' or 'B' or new line ('\n') or tab ('\t'). Otherwise key is a multicharacter
string such as 'escape' or 'backspace' or 'f3'. For such inputs, the ctrl,
alt, and shift keys are prepended to the key name. For example, if you hold
down the shift key and press F3, key will be the character string 'shift+f3',
which you can test for explicitly. If you hold down all three modifier keys,
you get 'ctrl+alt+shift+f3'; the order is always ctrl, alt, shift.

There are two different ways to get a keyboard event, "polling" and "callback". In polling, you continually check scene.kb.keys to see whether any events are waiting to be processed, and you use scene.kb.getkey() to get the next event to process. Prior to VPython 6, this was the only way you could handle mouse or keyboard events.

If you use the callback method, you specify a function to be executed when a specific type of event occurs, and the function is sent the event information when the specified type of event occurs. For many purposes this is a better way to handle keyboard and mouse events, and we will discuss it first. Programs that use polling will continue to work, but you cannot mix polling and callback approaches: you must use one or the other in a program.

Handling events with callbacks

Here is a test routine using callbacks that lets you type text into a label.

We define a "function" named "keyInput". Then we "bind" this function to 'keydown' events occurring in the display named "scene". Whenever VPython detects that a 'keydown' event has occurred, VPython calls the bound function, which in this case adds the input to the text of the label object.

Note that evt.ctrl, evt.alt, and evt.shift are True if the corresponding key is down at the time of the event. On the Macintosh, evt.cmd is True if the Command key is down.

This operation is called a "callback" because with scene.bind you register with VPython that you want to be called back any time there is a 'keydown' event. Here are the built-in events that you can specify in a bind operation:

The event 'keydown' or 'keyup' occurs when you press or release a key on the keyboard. The events 'click', 'mousedown', 'mousemove', and 'mouseup' are discussed in the mouse section. A 'redraw' event occurs just before the 3D scene is redrawn on the screen, and a 'draw_complete' event occurs just after the redrawing (these event have rather technical uses such as timing how often redrawings occur, or how much time they take).

You can bind more than one event to a function. The following will cause the callback function to be executed whether you click with the mouse or press a key on the keyboard:

scene.bind('click keydown', myFunction)

With the following statement, click event will no longer be sent to myFunction:

scene.unbind('click', myFunction)

The example program eventHandlers.py illustrates the callback method for handling many kinds of events.

Handling events with polling

The following information on how to handle events using polling is still valid, but you are encouraged to consider using the more powerful callback approach when writing new programs. Remember that you cannot mix the two schemes. You can use either callback or polling in a program, but not both.

Here is a test routine using polling that lets you type text into a label. If scene.kb.keys is nonzero,
one or more keyboard events have been stored, waiting to be processed. If one or more events are available, you can execute key=scene.kb.getkey() to obtain the oldest keyboard input
and remove it from the input queue.