>Psychtoolbox>PsychBasic

function ListenChar([listenFlag])

Tell the Psychtoolbox function “GetChar” to start or stop listening for
keyboard input. By default ListenChar enables listening when no argument is
supplied. Passing 0 will turn off character listening and reset the
buffer which holds the captured characters. Passing a value of 1 or not
passing any value will enable listening. Passing a value of 2 will enable
listening, additionally any output of keypresses to Matlabs or Octaves
windows is suppressed. Use this with care, if your script aborts with an
error, Matlab or Octave may be left with a dead keyboard until the user
presses CTRL+C to re-enable keyboard input. ‘listenFlag’ 2 is silently
ignored on Matlab in -nojvm mode under MS-Windows.

Passing the listenFlag -1 will only suppress keypresses into Matlabs or
Octaves command window, but not collect characters for use with CharAvail
or GetChar. This allows concurrent use of ListenChar for character suppression
while at the same time using keyboard queues for character and key input.
Reenabling keypresses into Matlab and Octave is only possible via a call
with listenFlag 0 if suppression was enabled with listenFlag -1. Use of
listenFlag -1 does not block keyboard queues, so if you want to get keyboard
input, the better way might be to use keyboard queues (see KbEventAvail,
KbEventGet and KbEventFlush)) for input and ListenChar(-1) and ListenChar(0)
to suppress characters into the Matlab/Octave command window or console.

This function isn’t entirely necessary to turn on listening as calling
GetChar, CharAvail, or FlushEvents will trigger listening on. However,
it is the only method by which to disable listening or switch between
suppression of keyboard input to Matlab and unsuppressed mode.

Please note that the commands ListenChar, CharAvail and GetChar are
subject to various constraints and limitations, depending on the
operating system you use, if you use Matlab in Java or -nojvm mode, if
you use Octave, if you have Screen() onscreen windows open or not, or if
you use KbQueueXXX functions in parallel or not. Therefore use of these
functions can be troublesome for any but the most simple usages. Use of
KbCheck, KbWait, KbStroke/Press/ReleaseWait is often simpler if you are
just after keyboard input. Use of KbQueue functions, e.g., KbQueueCheck,
KbQueueWait, KbTriggerWait is better suited for background keystroke
collection. Use of KbEventAvail and KbEventGet is often more convenient,
more flexible and subject to less restrictions and gotchas than use of
GetChar et al.

Some of the restrictions and caveats:

1. Works very well with Matlab and its Java based GUI enabled on Linux (on
   desktop GUI’s other than KDE) and macOS, as well as on WindowsXP and earlier
   versions of Windows.

2. When used on Windows Vista or later (Vista, Windows-7, …, Windows-10)
   with Matlab’s Java GUI, you cannot use any KbQueue functions at the same
   time, ie., KbQueueCreate/Start/Stop/Check/Wait as well as KbWaitTrigger,
   KbEventFlush, KbEventAvail, and KbEventGet are off limits after any call
   to ListenChar, ListenChar(1), ListenChar(2), FlushEvents, CharAvail or
   GetChar. You would need to call ListenChar(0) before you could call
   KbQueueCreate and then use those functions. Vice versa, after a call to
   KbQueueCreate, CharAvail, FlushEvents, and GetChar are dysfunctional and
   ListenChar may be limited. You need to call KbQueueRelease before you can
   use them again. Use of other devices, e.g., mouse or joystick, is not
   prohibited during use of GetChar et al.

3. If you use Matlab in “matlab -nojvm” mode without its GUI, or if you
   use GNU/Octave instead of Matlab, the same restrictions as in 2. apply -
   no parallel use of the default keyboards KbQueue. KbQueues can be used
   for other input devices and on Linux and OSX for keyboards other than the
   default keyboard.

The only feature that works in parallel with KbQueues on the default keyboard
is the suppression of spilling of keystroke characters into the Matlab or
Octave window during ListenChar(2) - at least on Linux and OSX. On
Windows this can’t be prevented at all in “matlab -nojvm” mode. However,
if you switch to ListenChar(2) mode, you cannot break out of it by
pressing CTRL+C on Linux if the keyboard queue that is in parallel use
didn’t get KbQueueStart called, ie. if it is stopped. On OSX with a
stopped Keyboard queue, neither CTRL+C nor stopping a runaway script
works.

1. On Linux, as a exception, some GetChar, CharAvail functionality may
   still work in case 3. under certain conditions, e.g., if you don’t use
   ListenChar(2) and your Matlab/Octave is not in interactive mode.

Also, GetChar can only collect keystrokes from multiple connected
keyboards in case 1. In all other cases, it can only collect keystrokes,
or respond to press of CTRL+C, for the default keyboard device. It will
ignore other connected keyboards.

Another limitation in cases 2 and 3 is that international keyboards with non-US
layout and non-ASCII/Latin-1 characters may need special treatment and Octave
may have some trouble processing such characters. See “help KbEventGet” for a
detailed explanation.

Basically: Mixing GetChar et al. and modern KbQueue functions is usually
not advisable, or if needed, great care must be taken to sidestep all the
mentioned limitations. Also the KbQueue functions usually have better
timing precision and allow to flexibly address multiple keyboards
separately at least on Linux and OSX.

For further explanation see help for “GetChar”.

_________________________________________________________________________

See also: GetChar