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, device_class_name, device_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 non None or empty list kwargs passed to the method filter the possible events that can be returned using the keyboard event field with the associated name.

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 – Filter returned events using a list of key constant strings. Only events with a .key value that is within the keys list will be returned.
• chars – Filter returned events using a list of event char values. Only events with a .char value that is within the chars list will be returned.
• mods – Filter returned events using a list of modifier constant strings. Only events that have a modifier matching atleast one of the values in the mods list will be returned.
• duration – Applied to KeyboardRelease events only. If the duration kwarg value > 0, then events where event.duration > duration are returned. If the duration kwarg value < 0.0, then events where event.duration < -(duration) are returned.
• keys – Filter returned events based on one of the two Keyboard event type constants (Keyboard.KEY_PRESS, Keyboard.KEY_RELEASE).
• etype – True (default) means the keyboard event buffer is cleared after this method is called. If False, the keyboard event buffer is not changed.

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 using any non None kwargs values in the same way as the getKeys() method. See getKeys() for a description of the arguments shared between the two methods.

As soon as at least one matching KeyboardEvent occur prior to maxWait, the matching events are returned as a tuple.

Parameters:

• maxWait – Specifies the maximum time (in seconds) that the method will block for. If 0, waitForKeys() is identical to getKeys(). If None, the methods blocks indefinately.
• checkInterval – Specifies the number of seconds.msecs 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.

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.

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’ (the alt keys are also labelled as ‘option’ keys on Apple Keyboards)
• ‘lcmd’, ‘rcmd’ (The cmd keys 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, in the same time base that is used by psychopy.core.getTime()

Returns:float

type

The string type constant for the event.

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.

id

The unique id for the event; sometimes 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’ (the alt keys are also labelled as ‘option’ keys on Apple Keyboards)
• ‘lcmd’, ‘rcmd’ (The cmd keys 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, in the same time base that is used by psychopy.core.getTime()

Returns:float

type

The string type constant for the event.

Returns:str