A response handler element that records subject response by typing text in a text box, and optionally saves to a text file. At default the subject can type text of any length and press Enter to record it as a response and end the element. Alternatively you can let the user press Enter for line breaks and any mouse button to record response.

At default if text input is a single number, response value recorded is numeric, else it's a string <cds>"x"<cds>. You can change it to always record strings if you like.

See also keyPress elements.

Psychtoolbox text renderer

By default Psychtoolbox uses its own text renderer plugin. If this fails, it falls back to a more basic text renderer in your operating system and reports so in its messages at experiment startup. In this case you may see problems with text quality, alignment, or boundaries. See Psychtoolbox Screen('DrawText') for general information on text renderers, and DrawTextPlugin help for troubleshooting.

▸ Object ends on its own?

By default yes, when it records one response. You can change number of responses to wait for in property maxNumResponses.

"Ends on its own" means ends automatically at that point. If an element can end on its own, you don't need to set end conditions for it in property end (unless you want it to maybe end earlier).

No—runs until any condition you set in property end.

Input properties

Adjustable properties

You can vary or allow the subject to adjust the following properties of an object of this type when it's running. If you need to make other properties adjustable, you can edit the element type code—see Element Type Programming Manual.

Adjustable properties

Adjustable properties





Default: Arial

A string setting font. See Psychtoolbox Screen('TextFont') for more information on font names.


Default: 0.7 deg

This sets font size by setting line height which the font scales to (deg). This is equivalent to setting height of the "em box" for the font. Typically upper case characters are somewhat smaller than this. If you need more information, see Wikipedia https://en.wikipedia.org/wiki/Point_(typography) for a starting point.


Default: white

A 1×3 RGB vector with numbers between 0–1 setting text color.


Default: 1.3-spaced

A number: 1 = single-spaced, 2 = double, 1.5 = 1 & 1/2, etc. This multiplies line height without affecting font size (set in fontSize above). 1 = each line's baseline is precisely fontSize distance from the next line's baseline.


Default: boxSize = 12 deg width, 8 deg height
Default: margin = 0.4 deg
Default: boxColor = 90% white

boxSize sets text box size which the subject types in. This is a number for a square, or a vector [width height] for a rectangle (deg).

margin sets space between the box and text edges (deg).

boxColor is a 1×3 RGB vector with numbers between 0–1 setting text box color.


Default: pressing Enter registers response

<cd>true<cd>/<cd>false<cd>: At default <cd>true<cd>, the subject presses Enter to submit the text they have typed as a response (and at default maxNumResponses = 1 this ends the element). In this mode the subject can type one line of text (possibly wrapping). Or <cd>false<cd> = pressing Enter starts a new line instead, and clicking any mouse button registers response. In this mode the subject can type multiple lines of text.


Default: record number as string data type

<cd>true<cd>/<cd>false<cd>: <cd>true<cd> = if the subject inputs text that is a single number then response value recorded is numeric data type, not string. The element will also beep and not allow response if the text is not a single number. <cd>false<cd> = record any text, and always as string.


Default: fileName = don't save to file
Default: numberFile = automatically number files
Default: minNumDigitsInFileName = 1

fileName is a string setting name for the text file to save the input text to. If you include a path, it will save there, and make the folder if it doesn't exist. If you don't, it will save in the MATLAB current folder. <cd>[]<cd> = don't save to file.

If you specify fileName to save to file:

numberFile = <cd>true<cd>/<cd>false<cd>: If = <cd>true<cd> (default), the element adds a number to file name starting at 1 and incrementing as needed to not change any existing files. This means if you have multiple textInput elements in an experiment, you can set fileName the same for all of them (e.g. text.txt) and they will write different files numbered in the order they run in (e.g. text1.txt, text2.txt, text3.txt, ...). If you set numberFile = <cd>false<cd> then the element will not add a number and instead will append to any existing file with the specified name.

minNumDigitsInFileName sets the minimum number of digits to use for numbering files. e.g. 3 → text001.txt, text002.txt, text003.txt, ...

See also record properties fileName_r, n_file below.


Default: default device, generally the keyboard

<cd>[]<cd> = default device according to Psychtoolbox, which is generally the keyboard. Usually this is all you need to know.

Optionally you can listen for input from some other keyboard-like device. n_device is HID device number to listen to. You can use Psychtoolbox functions GetKeyboardIndices or PsychHID('Devices') to see available device numbers. A textInput element uses Psychtoolbox KbQueueCreate and n_device goes to the input of that function. See its help if you need more information on device numbers.

Input properties all visual elements have


Input properties all adjuster elements have


Input properties all objects have


Record properties

PsychBench uses record properties to record information during experiments. You can't set record properties but you can see them in experiment results using input property report.


fileName_r is a string recording name of the file written to. This includes number added if numberFile = <cd>true<cd>.

n_file records the number added (numeric) if numberFile = <cd>true<cd>.