class Keyboard

The Keyboard class is used to collect keyboard responses. You generally create a Keyboard object with the Keyboard() factory function, as described in the section Creating a Keyboard.

Example

# Wait for a 'z' or 'x' key with a timeout of 3000 ms
my_keyboard = Keyboard(keylist=['z', 'x'], timeout=3000)
start_time = clock.time()
key, end_time = my_keyboard.get_key()
response = key
response_time = end_time - start_time

Things to know

Creating a Keyboard

You generally create a Keyboard with the Keyboard() factory function:

my_keyboard = Keyboard()

Optionally, you can pass Response keywords to Keyboard() to set the default behavior:

my_keyboard = Keyboard(timeout=2000)

Key names

• Key names may differ between backends.
• Keys can be identified either by character or name, and are case-insensitive. For example:
• The key 'a' is represented by 'a' and 'A'
• The up arrow is represented by 'up' and 'UP'
• The '/' key is represented by '/', 'slash', and 'SLASH'
• The spacebar is represented by 'space' and 'SPACE'
• To find out the name of key, you can:
• Click on the 'list available keys' button of the keyboard_response item.
• Collect a key press with a keyboard_response item, and display the key name through a feedback item with the text 'You pressed [response]' in it.

Response keywords

Functions that accept **resp_args take the following keyword arguments:

• timeout specifies a timeout value in milliseconds, or is set to None to disable the timeout.
• keylist specifies a list of keys that are accepted, or is set to None accept all keys.

# Get a left or right arrow press with a timeout of 3000 ms
my_keyboard = Keyboard()
key, time = my_keyboard.get_key(keylist=[u'left', u'right'], timeout=3000)

Response keywords only affect the current operation (except when passed to Keyboard()). To change the behavior for all subsequent operations, set the response properties directly:

# Get two key A or B presses with a 5000 ms timeout
my_keyboard = Keyboard()
my_keyboard.keylist = [u'a', u'b']
my_keyboard.timeout = 5000
key1, time1 = my_keyboard.get_key()
key2, time2 = my_keyboard.get_key()

Or pass the response options to [keyboard.init][init]:

# Get two key A or B presses with a 5000 ms timeout
my_keyboard = Keyboard(keylist=[u'a', u'b'], timeout=5000)
key1, time1 = my_keyboard.get_key()
key2, time2 = my_keyboard.get_key()

flush()

Clears all pending keyboard input, not limited to the keyboard.

Returns

• True if a key had been pressed (i.e., if there was something to flush) and False otherwise.

get_key(*arglist, **kwdict)

Collects a single key press.

Parameters

• **resp_args: Optional response keywords (timeout and keylist) that will be used for this call to Keyboard.get_key(). This does not affect subsequent operations.

Returns

• A (key, timestamp) tuple. key is None if a timeout occurs.

Example

my_keyboard = Keyboard()
response, timestamp = my_keyboard.get_key(timeout=5000)
if response is None:
        print(u'A timeout occurred!')

get_key_release(*arglist, **kwdict)

New in v3.2.0

Collects a single key release.

Important: This function currently assumes a QWERTY keyboard layout (unlike Keyboard.get_key()). This means that the returned key may be incorrect on non-QWERTY keyboard layouts. In addition, this function is not implemented for the psycho backend.

Parameters

• **resp_args: Optional response keywords (timeout and keylist) that will be used for this call to Keyboard.get_key_release(). This does not affect subsequent operations.

Returns

• A (key, timestamp) tuple. key is None if a timeout occurs.

Example

my_keyboard = Keyboard()
response, timestamp = my_keyboard.get_key_release(timeout=5000)
if response is None:
        print(u'A timeout occurred!')

get_mods()

Returns a list of keyboard moderators (e.g., shift, alt, etc.) that are currently pressed.

Returns

• A list of keyboard moderators. An empty list is returned if no moderators are pressed.

Example

my_keyboard = Keyboard()
moderators = my_keyboard.get_mods()
if u'shift' in moderators:
        print(u'The shift-key is down!')

show_virtual_keyboard(visible=True)

Shows or hides a virtual keyboard if this is supported by the back-end. This function is only necessary if you want the virtual keyboard to remain visible while collecting multicharacter responses. Otherwise, Keyboard.get_key() will implicitly show and hide the keyboard for a single-character response.

This function does nothing for back-ends that do not support virtual keyboards.

Parameters

• visible: True if the keyboard should be shown, False otherwise.

Example

my_keyboard = Keyboard()
my_keyboard.show_virtual_keyboard(True)
response1, timestamp2 = my_keyboard.get_key()
response2, timestamp2 = my_keyboard.get_key()
my_keyboard.show_virtual_keyboard(False)

synonyms(key)

Gives a list of synonyms for a key, either codes or names. Synonyms include all variables as types and as Unicode strings (if applicable).

Returns

• A list of synonyms

valid_keys()

Tries to guess which key names are accepted by the back-end. For internal use.

Returns

• A list of valid key names.