OpenSesame
Rapunzel Code Editor
DataMatrix
Support forum
Python Tutorials
MindProbe
OpenSesame videos
Python videos
Supported by Supported by

Keyboard functions

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()
var.response = key
var.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-insentive. 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.__init__][init]). 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()

function Keyboard.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.

  • Type: bool

function Keyboard.get_key(**resp_args)

Collects a single key press.

Example:

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

Keyword dict:

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

  • Type: tuple

function Keyboard.get_key_release(**resp_args)

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.

Example:

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

Keyword dict:

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

  • Type: tuple

function Keyboard.get_mods()

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

Example:

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

Returns:

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

  • Type: list

function Keyboard.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 shown and hide the keyboard for a single-character response.

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

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)

Keywords:

  • visible -- True if the keyboard should be shown, False otherwise.
    • Type: bool
    • Default: True
Supported by Supported by