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)[source]

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

Examples

  1. 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()
    
  2. 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()
    
_syncDeviceState()[source]

An optimized iohub server request that receives all device state and event information in one response.

Returns:

None

getKeys(keys=None, chars=None, ignoreKeys=None, mods=None, duration=None, etype=None, clear=True)[source]

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.

  • 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.

Returns:

tuple of KeyboardEvent instances, or ()

getPresses(keys=None, chars=None, ignoreKeys=None, mods=None, clear=True)[source]

See the getKeys() method documentation.

This method is identical, but only returns KeyboardPress events.

getReleases(keys=None, chars=None, ignoreKeys=None, mods=None, duration=None, clear=True)[source]

See the getKeys() method documentation.

This method is identical, but only returns KeyboardRelease events.

property reporting

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
property state

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

Type:

Returns all currently pressed keys as a dictionary of key

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

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)[source]

See the waitForKeys() method documentation.

This method is identical, but only returns KeyboardPress events.

waitForReleases(maxWait=None, keys=None, chars=None, mods=None, duration=None, clear=True, checkInterval=0.002)[source]

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)[source]

An iohub Keyboard device key press event.

property 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.

property device

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

Returns:

ioHubDeviceView

property 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

property time

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

Returns:

float

property type

The event type string constant.

Returns:

str

KeyboardRelease Event

class psychopy.iohub.client.keyboard.KeyboardRelease(ioe_array)[source]

An iohub Keyboard device key release event.

property 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

property 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

property 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.

property device

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

Returns:

ioHubDeviceView

property 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

property time

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

Returns:

float

property type

The event type string constant.

Returns:

str


Back to top