To handle input from keyboard (supersedes event.getKeys)
The Keyboard class was new in PsychoPy 3.1 and replaces the older event.getKeys() calls.
On 64 bits Python3 installations it provides access to the Psychtoolbox kbQueue series of functions using the same compiled C code (available in python-psychtoolbox lib).
On 32 bit installations and Python2 it reverts to the older
psychopy.event.getKeys()
calls.
The new calls have several advantages:
the polling is performed and timestamped asynchronously with the main thread so that times relate to when the key was pressed, not when the call was made
the polling is direct to the USB HID library in C, which is faster than waiting for the operating system to poll and interpret those same packets
we also detect the KeyUp events and therefore provide the option of returning keypress duration
on Linux and Mac you can also distinguish between different keyboard devices
(see getKeyboards()
)
This library makes use, where possible of the same low-level asynchronous hardware polling as in Psychtoolbox
Example usage
from psychopy.hardware import keyboard
from psychopy import core
kb = keyboard.Keyboard()
# during your trial
kb.clock.reset() # when you want to start the timer from
keys = kb.getKeys(['right', 'left', 'quit'], waitRelease=True)
if 'quit' in keys:
core.quit()
for key in keys:
print(key.name, key.rt, key.duration)
psychopy.hardware.keyboard.
Keyboard
(device=- 1, bufferSize=10000, waitForStart=False, clock=None, backend=None)[source]¶The Keyboard class provides access to the Psychtoolbox KbQueue-based calls on Python3 64-bit with fall-back to event.getKeys on legacy systems.
Create the device (default keyboard or select one)
device (int or dict) – On Linux/Mac this can be a device index
or a dict containing the device info (as from getKeyboards()
)
or -1 for all devices acting as a unified Keyboard
bufferSize (int) – How many keys to store in the buffer (before dropping older ones)
waitForStart (bool (default False)) – Normally we’ll start polling the Keyboard at all times but you could choose not to do that and start/stop manually instead by setting this to True
getKeys
(keyList=None, waitRelease=True, clear=True)[source]¶keyList (list (or other iterable)) – The keys that you want to listen out for. e.g. [‘left’, ‘right’, ‘q’]
waitRelease (bool (default True)) – If True then we won’t report any “incomplete” keypress but all presses will then be given a duration. If False then all keys will be presses will be returned, but only those with a corresponding release will contain a duration value (others will have duration=None
clear (bool (default True)) – If False then keep the keypresses for further calls (leave the buffer untouched)
A list of Keypress
objects
setBackend
(backend)[source]¶Set backend event handler. Returns currently active handler.
backend – ‘iohub’, ‘ptb’, ‘event’, or ‘’
str
waitKeys
(maxWait=inf, keyList=None, waitRelease=True, clear=True)[source]¶Same as ~psychopy.hardware.keyboard.Keyboard.getKeys, but halts everything (including drawing) while awaiting keyboard input.
Maximum number of seconds period and which keys to wait for. Default is float(‘inf’) which simply waits forever.
Allows the user to specify a set of keys to check for. Only keypresses from this set of keys will be removed from the keyboard buffer. If the keyList is None, all keys will be checked and the key buffer will be cleared completely. NB, pygame doesn’t return timestamps (they are always 0)
If True then we won’t report any “incomplete” keypress but all presses will then be given a duration. If False then all keys will be presses will be returned, but only those with a corresponding release will contain a duration value (others will have duration=None
Whether to clear the keyboard event buffer (and discard preceding keypresses) before starting to monitor for new keypresses.
Returns None if times out.
psychopy.hardware.keyboard.
KeyPress
(code, tDown, name=None)[source]¶Class to store key presses, as returned by Keyboard.getKeys()
Unlike keypresses from the old event.getKeys() which returned a list of strings (the names of the keys) we now return several attributes for each key:
.name: the name as a string (matching the previous pyglet name) .rt: the reaction time (relative to last clock reset) .tDown: the time the key went down in absolute time .duration: the duration of the keypress (or None if not released)
Although the keypresses are a class they will test ==, != and in based on their name. So you can still do:
kb = KeyBoard()
# wait for keypresses here
keys = kb.getKeys()
for thisKey in keys:
if thisKey=='q': # it is equivalent to the string 'q'
core.quit()
else:
print(thisKey.name, thisKey.tDown, thisKey.rt)
psychopy.hardware.keyboard.
getKeyboards
()[source]¶Get info about the available keyboards.
Only really useful on Mac/Linux because on these the info can be used to
select a particular physical device when calling Keyboard
. On Win
this function does return information correctly but the :class:Keyboard
can’t make use of it.
USB Info including with name, manufacturer, id, etc for each device
A list of dicts