Check for any new keyboard events that have occurred since the last time keyboard events were checked or cleared.
Wait until a keyboard event occurs.
Clear the device of any unread events.
Get a list of all currently pressed keys.
The Keyboard device provides access to KeyboardPress and KeyboardRelease events as well as the current keyboard state.
Examples
Print all keyboard events received for 5 seconds:
from psychopy.iohub import launchHubServer
from psychopy.core import getTime
# Start the ioHub process. 'io' can now be used during the
# experiment to access iohub devices and read iohub device events.
io = launchHubServer()
keyboard = io.devices.keyboard
# Check for and print any Keyboard events received for 5 seconds.
stime = getTime()
while getTime()-stime < 5.0:
for e in keyboard.getEvents():
print(e)
# Stop the ioHub Server
io.quit()
Wait for a keyboard press event (max of 5 seconds):
from psychopy.iohub import launchHubServer
from psychopy.core import getTime
# Start the ioHub process. 'io' can now be used during the
# experiment to access iohub devices and read iohub device events.
io = launchHubServer()
keyboard = io.devices.keyboard
# Wait for a key keypress event ( max wait of 5 seconds )
presses = keyboard.waitForPresses(maxWait=5.0)
print(presses)
# Stop the ioHub Server
io.quit()
An optimized iohub server request that receives all device state and event information in one response.
None
Return a list of any KeyboardPress or KeyboardRelease events that have occurred since the last time either:
this method was called with the kwarg clear=True (default)
the keyboard.clear() method was called.
Other than the ‘clear’ kwarg, any kwargs that are not None or an empty list are used to filter the possible events that can be returned. If multiple filter criteria are provided, only events that match all specified criteria are returned.
If no KeyboardEvent’s are found that match the filtering criteria, an empty tuple is returned.
Returned events are sorted by time.
keys – Include events where .key in keys.
chars – Include events where .char in chars.
ignoreKeys – Ignore events where .key in ignoreKeys.
mods – Include events where .modifiers include >=1 mods element.
duration – Include KeyboardRelease events where .duration > duration or .duration < -(duration).
etype – Include events that match etype of Keyboard.KEY_PRESS or Keyboard.KEY_RELEASE.
clear – True (default) = clear returned events from event buffer, False = leave the keyboard event buffer unchanged.
tuple of KeyboardEvent instances, or ()
See the getKeys() method documentation.
This method is identical, but only returns KeyboardPress events.
See the getKeys() method documentation.
This method is identical, but only returns KeyboardRelease events.
Specifies if the keyboard device is reporting / recording events.
True: keyboard events are being reported.
False: keyboard events are not being reported.
By default, the Keyboard starts reporting events automatically when the ioHub process is started and continues to do so until the process is stopped.
This property can be used to read or set the device reporting state:
# Read the reporting state of the keyboard.
is_reporting_keyboard_event = keyboard.reporting
# Stop the keyboard from reporting any new events.
keyboard.reporting = False
time values. The key is taken from the originating press event .key field. The time value is time of the key press event.
Note that any pressed, or active, modifier keys are included in the return value.
dict
Returns all currently pressed keys as a dictionary of key
Blocks experiment execution until at least one matching KeyboardEvent occurs, or until maxWait seconds has passed since the method was called.
Keyboard events are filtered the same way as in the getKeys() method.
As soon as at least one matching KeyboardEvent occurs prior to maxWait, the matching events are returned as a tuple.
Returned events are sorted by time.
maxWait – Maximum seconds method waits for >=1 matching event. If <=0.0, method functions the same as getKeys(). If None, the methods blocks indefinitely.
keys – Include events where .key in keys.
chars – Include events where .char in chars.
mods – Include events where .modifiers include >=1 mods element.
duration – Include KeyboardRelease events where .duration > duration or .duration < -(duration).
etype – Include events that match etype of Keyboard.KEY_PRESS or Keyboard.KEY_RELEASE.
clear – True (default) = clear returned events from event buffer, False = leave the keyboard event buffer unchanged.
checkInterval – The time between geyKeys() calls while waiting. The method sleeps between geyKeys() calls, up until checkInterval*2.0 sec prior to the maxWait. After that time, keyboard events are constantly checked until the method times out.
tuple of KeyboardEvent instances, or ()
The Keyboard device can return two types of events, which represent key press and key release actions on the keyboard.
An iohub Keyboard device key press event.
The unicode value of the keyboard event, if available. This field is only populated when the keyboard event results in a character that could be printable.
unicode, ‘’ if no char value is available for the event.
The ioHubDeviceView that is associated with the event, i.e. the iohub device view for the device that generated the event.
ioHubDeviceView
A list of any modifier keys that were pressed when this keyboard event occurred. Each element of the list contains a keyboard modifier string constant. Possible values are:
‘lctrl’, ‘rctrl’
‘lshift’, ‘rshift’
‘lalt’, ‘ralt’ (labelled as ‘option’ keys on Apple Keyboards)
‘lcmd’, ‘rcmd’ (map to the ‘windows’ key(s) on Windows keyboards)
‘menu’
‘capslock’
‘numlock’
‘function’ (OS X only)
‘modhelp’ (OS X only)
If no modifiers were active when the event occurred, an empty list is returned.
tuple
The time stamp of the event. Uses the same time base that is used by psychopy.core.getTime()
float
The event type string constant.
str
An iohub Keyboard device key release event.
The duration (in seconds) of the key press. This is calculated by subtracting the current event.time from the associated keypress.time.
If no matching keypress event was reported prior to this event, then 0.0 is returned. This can happen, for example, when the key was pressed prior to psychopy starting to monitor the device. This condition can also happen when keyboard.reset() method is called between the press and release event times.
float
The event.id of the associated press event.
The key press id is 0 if no associated KeyboardPress event was found. See the duration property documentation for details on when this can occur.
unsigned int
The unicode value of the keyboard event, if available. This field is only populated when the keyboard event results in a character that could be printable.
unicode, ‘’ if no char value is available for the event.
The ioHubDeviceView that is associated with the event, i.e. the iohub device view for the device that generated the event.
ioHubDeviceView
A list of any modifier keys that were pressed when this keyboard event occurred. Each element of the list contains a keyboard modifier string constant. Possible values are:
‘lctrl’, ‘rctrl’
‘lshift’, ‘rshift’
‘lalt’, ‘ralt’ (labelled as ‘option’ keys on Apple Keyboards)
‘lcmd’, ‘rcmd’ (map to the ‘windows’ key(s) on Windows keyboards)
‘menu’
‘capslock’
‘numlock’
‘function’ (OS X only)
‘modhelp’ (OS X only)
If no modifiers were active when the event occurred, an empty list is returned.
tuple
The time stamp of the event. Uses the same time base that is used by psychopy.core.getTime()
float
The event type string constant.
str