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:
timeoutspecifies a timeout value in milliseconds, or is set toNoneto disable the timeout.keylistspecifies a list of keys that are accepted, or is set toNoneaccept 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] (timeoutandkeylist) 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] (timeoutandkeylist) 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