Scan a keyboard or keypad device and wait for a trigger key press.
By default the first keyboard device (the one with the lowest device number) is
scanned. If no keyboard is found, the first keypad device is scanned.
Optionally, the device number of any keyboard or keypad may be specified.
The '
KeysUsage' parameter must specify the keycode of a single key to wait for
on OS/X. On Linux and Windows, '
KeysUsage' can be a vector of trigger key codes
and the wait will finish as soon as at least one of the keys in the vector is
pressed.
On Linux and OS/X handling of keyboard triggers is efficient. On MS-Windows,
keyboard triggers are implemented by periodic polling of the keyboard state with
a frequency of approximately 500 Hz. This is a brute-force approach which can
lead to unreliable stimulus presentation timing and trigger timestamping unless
you have a fast (multi-core) machine. It will also draw significant amounts of
electrical power. Therefore use this feature sparingly on MS-Windows and
consider a different operating system.
On MS-Windows, the 'deviceNumber' argument is ignored and the default keyboard
is waited for.