Table Of Contents

Previous topic

ioHub Devices and Device Events

Next topic

Mouse Device and Events

This Page

Quick links

Keyboard Device

The iohub Keyboard device provides methods to:
  • 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.
class psychopy.iohub.client.keyboard.Keyboard(ioclient, dev_cls_name, dev_config)

The Keyboard device provides access to KeyboardPress and KeyboardRelease events as well as the current keyboard state.

state

Returns all currently pressed keys as a dictionary of key : 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.

Returns:dict
reporting

Specifies if the 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
getKeys(keys=None, chars=None, mods=None, duration=None, etype=None, clear=True)

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.

Parameters:
  • 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.
Returns:

tuple of KeyboardEvent instances, or ()

getPresses(keys=None, chars=None, mods=None, clear=True)

See the getKeys() method documentation.

This method is identical, but only returns KeyboardPress events.

getReleases(keys=None, chars=None, mods=None, duration=None, clear=True)

See the getKeys() method documentation.

This method is identical, but only returns KeyboardRelease events.

waitForKeys(maxWait=None, keys=None, chars=None, mods=None, duration=None, etype=None, clear=True, checkInterval=0.002)

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.

Parameters:
  • 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.
Returns:

tuple of KeyboardEvent instances, or ()

waitForPresses(maxWait=None, keys=None, chars=None, mods=None, duration=None, clear=True, checkInterval=0.002)

See the waitForKeys() method documentation.

This method is identical, but only returns KeyboardPress events.

getName()

Gets the name given to the device in the ioHub configuration file. ( the device: name: property )

Args:
None
Returns:
(str): the user defined label / name of the device
waitForReleases(maxWait=None, keys=None, chars=None, mods=None, duration=None, clear=True, checkInterval=0.002)

See the waitForKeys() method documentation.

This method is identical, but only returns KeyboardRelease events.

Keyboard Events

The Keyboard device can return two types of events, which represent key press and key release actions on the keyboard.

KeyboardPress Event

class psychopy.iohub.client.keyboard.KeyboardPress(ioe_array)

An iohub Keyboard device key press event.

char

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.

Returns:unicode, ‘’ if no char value is available for the event.
device

The ioHubDeviceView that is associated with the event, i.e. the iohub device view for the device that generated the event.

Returns:ioHubDeviceView
modifiers

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.

Returns:tuple
time

The time stamp of the event. Uses the same time base that is used by psychopy.core.getTime()

Returns:float
type

The event type string constant.

Returns:str

KeyboardRelease Event

class psychopy.iohub.client.keyboard.KeyboardRelease(ioe_array)

An iohub Keyboard device key release event.

duration

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.

Returns:float
pressEventID

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.

Returns:unsigned int
char

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.

Returns:unicode, ‘’ if no char value is available for the event.
device

The ioHubDeviceView that is associated with the event, i.e. the iohub device view for the device that generated the event.

Returns:ioHubDeviceView
id

The unique id for the event; in some cases used to track associated events.

Returns:int
modifiers

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.

Returns:tuple
time

The time stamp of the event. Uses the same time base that is used by psychopy.core.getTime()

Returns:float
type

The event type string constant.

Returns:str