>Psychtoolbox>PsychOneliners

[string,terminatorChar] = GetEchoString(window,msg,x,y,[textColor],[bgColor],[useKbCheck=0],[deviceIndex],[untilTime=inf],[KbCheck args…]);

Get a string typed at the keyboard. Entry is terminated by <return> or
<enter>.

Typed characters are displayed in the window. The delete or backspace key
is handled correctly, ie., it erases the last typed character. Useful for
i/o in a Screen window.

‘window’ = Window to draw to. ‘msg’ = A message string displayed to
prompt for input. ‘x’, ‘y’ = Start position of message prompt.
‘textColor’ = Color to use for drawing the text. ‘bgColor’ = Background
color for text. By default, the background is transparent. If a non-empty
‘bgColor’ is specified it will be used. The current alpha blending
setting will affect the appearance of the text if ‘bgColor’ is specified!
Please note that if ‘bgColor’ is not specified, this means mistyped text
can’t be visually deleted/undone by use of the backspace key.

If the optional flag ‘useKbCheck’ is set to 1 then KbCheck is used - with
potential optional additional ‘KbCheck args…’ for getting the string
from the keyboard. Otherwise GetChar is used. ‘useKbCheck’ == 1 is
restricted to standard alpha-numeric keys (characters, letters and a few
special symbols). It can’t handle all possible characters and doesn’t
work with non-US keyboard mappings. Its advantage is that it works
reliably on configurations where GetChar may fail, e.g., on MS-Vista and
Windows-7.

If ‘useKbCheck’ == 1, then ‘deviceIndex’ optionally allows to select the
deviceIndex of the keyboard to use, and ‘untilTime’ allows to specify a
response deadline. If the user doesn’t press ENTER until ‘untilTime’, the
function will time out and return with a empty ‘string’ as result. Further
optional arguments will be passed on to the function GetKbChar().

See also: GetNumber, GetString, GetEchoNumber, GetKbChar