GetChar

Psychtoolbox › PsychBasic

[ch, when] = GetChar([getExtendedData], [getRawCode])

Wait for a typed character and return it. If a character was typed
before calling GetChar then GetChar will return that character immediatly.
Characters flushed by FlushEvents are all ignored by GetChar. Characters
are returned in the first return argument "ch".

CAUTION: Do not rely on the keypress timestamps returned by GetChar
without fully reading and understanding this help text. Run your own
timing tests on GetChar and KbCheck to verify that the timing is good
enough and avoid GetChar for timed keypresses if possible at all. Use
KbWait and KbCheck instead.

The main purpose of GetChar is to reliably collect keyboard input in the
background while your experiment script is occupied with performing other
operations, e.g., Matlab computations, sound output or visual stimulus
drawing. After an initial call to ListenChar, the operating system will
record all keyboard input into an internal queue. GetChar removes
characters from that queue, one character per invocation of GetChar. You
can empty that queue any time by calling FlushEvents('keyDown').

If you want to check the current state of the keyboard, e.g., for triggering
immediate actions in response to a key press, waiting for a subjects
response, synchronizing to keytriggers (e.g., fMRI machines) or if you
require high timing precision then use KbCheck instead of GetChar.

GetChar works on all platforms with Matlab and Java enabled. It works
also on M$-Windows in "matlab -nojvm" mode. It does not work on MacOS-X or
Linux in "matlab -nojvm" mode and it also doesn't work under GNU/Octave.

"when" is a struct. It returns the time of the keypress, the "adb"
address of the input device, and the state of all the modifier keys
(shift, control, command, option, alphaLock) and the mouse button. If you
have multiple keyboards connected, "address" may allow you to distinguish
which is responsible for the key press. "when.secs" is an estimate,
of what GetSecs would have been. Since it's derived from a timebase
different from the timebase of GetSecs, times returned by GetSecs are not
directly comparable to when.secs.

By setting getExtendedData to 0, all extended timing/modifier information
will not be collected and "when" will be returned empty. This speeds up
calls to this function. If ommitted or set to 1, the "when" data structure
is filled. getRawCode set to 1 will set "ch" to be the integer ascii code
of the available character. If ommitted or set to 0, "ch" will be in
char format. When running under Windows in "matlab -nojvm" mode, "when"
will be returned empty.

GetChar and CharAvail are character-oriented (and slow), whereas KbCheck
and KbWait are keypress-oriented (and fast). If only a meta key (like
<option> or <shift>) was hit, KbCheck will return true, because a key was
pressed, but CharAvail will return false, because no character was
generated. See KbCheck.

CharAvail and GetChar use the system event queue to retrieve the character
generated, not the raw key press(es) per se. If the user presses "a",
GetChar returns 'a', but if the user presses option-e followed by "a",
this selects an accented a, "?", which is treated by GetChar as a single
character, even though it took the user three keypresses (counting the
option key) to produce it.

There can be some delay between when the key is pressed and when CharAvail
or GetChar detects it, due to internal processing overhead in Matlabs Java
implementation. GetChar internally collects timestamps in the timebase
used by Matlabs Java implementation, whereas other Psychtoolbox timing functions
(GetSecs, Screen('Flip'), KbCheck, KbWait, ...) use time reported by some
high precision system timer. The "when.secs" time reported by GetChar is
converted from Java timebase to Psychtoolboxs timebase. Due to conversion
errors mostly out of our control, the reported values can be off by
multiple dozen or even hundreds of milliseconds from what KbWait, KbCheck
or GetSecs would report. Example: A high-end Pentium-4 3.2 Ghz system
running Windows-XP has been measured to be off by 40 to 70 milliseconds.

Some Java implementations are also known to have problems/bugs in
timestamping keyboard presses properly and each Matlab version on each
operating system is bundled with a different Java version, so some Matlab
versions may be reliable with respect to GetChars timing, whereas others
are not.


> If precise timing of the keypress is important, use KbCheck or
KbWait for consistent results!

OS X / Windows / Linux with Matlab and Java enabled

JAVA PATH: The GetChar implementation is based on Java. Therefore, the
Psychtoolbox subfolder PsychJava must be added to Matlabs static
classpath. Normally this is done by the Psychtoolbox installer by editing
the Matlab file "classpath.txt" (enter which('classpath.txt') to find the
location of that file). If the installer fails to edit the file properly,
you'll need to perform that step manually by following the instructions
of the installer. See 'help PsychJavaTrouble' for more infos on this.

KEYSTROKES IN THE BACKGROUND: Under OS 9, keyboard input is automatically
directed to the Getchar queue while a script or function executes in
MATLAB. Therefore, your script may do work and then call GetChar to read
keys pressed while the script worked. OS X is the same, except that, to
detect keypresses made before the GetChar call, you must have called
"ListenChar" earlier. ListenChar redirects keystrokes to the GetChar
queue. Calling ListenChar at the begining of your OS X script should
cause GetChar to behave identically to OS 9 GetChar with respect to
background keystroke collection.

KEYSTROKES IN MATLAB WINDOW: By default, all keystrokes are also sent to
Matlabs window, generating some ugly clutter. You can suppress this by
calling ListenChar(2), so your Matlab console stays nice and clean. Don't
forget to call ListenChar(1) or ListenChar(0) though before the end of
your script. If Matlab returns to its command prompt without reenabling
keyboard input via ListenChar(0) or ListenChar(1), Matlab will be left
with a dead keyboard until you press the CTRL+C key combo.

OTHER "when" RETURN ARGUMENT FIELDS: Owing to differences in what
accessory information the underlying operating systems provides about
keystrokes, "when' return argument fields differs between OS 9 and OS X.
GetChar sets fields for which it returns no value to the value 'Nan'.

See also: ListenChar, CharAvail, FlushEvents, TestGetChar, KbCheck,
KbWait