Shows some text until the subject presses any key or clicks any mouse button. Commonly used for introduction, instructions, breaks, outro, etc. You can also show multiple "pages" of text with the subject pressing/clicking between each one. For most cases all you need to do is set property text.

Generally text cannot change while it is showing. However, it is dynamic enough to be able to show values it can obtain at experiment startup, e.g. trial number for the trial it will run in (useful if you want to show trial number during the experiment).

dialogue elements combine functionality from text, keyPress, and mouseClick elements for convenience. If you need text, key press, or mouse click functionality alone and more flexible, use those element types instead.

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.

If an element will end automatically, you don't need to set an end time or condition in property end. However, you can if you want to add other end conditions that could occur earlier.

text

Default: none

text is a string that is text to show. Or for multiple lines you can use an array of strings. You can also use <cds><n><cds> or character code <cd>10<cd> in the text (see also property wrapWidth below). You can also show multiple "pages" of text with the subject pressing/clicking between each one by putting this string array in an outer cell array.

You can include the following anywhere in the text for line breaks and formatting changes:

<cd><b>           <cd> – bold
<cd><i>           <cd> – italic
<cd><u>           <cd> – underline (only on some systems and text renderers)
<cd><r>           <cd> – regular (end bold/italic/underline)
<cd><font = name> <cd> – font name, e.g. <cd><font = Arial><cd>
<cd><size = n>    <cd> – font size, e.g. <cd><size = 0.8><cd>. Units are whatever you use for property fontSize below (default deg).
<cd><color = RGB> <cd> – color. RGB = a 1×3 RGB vector with numbers between 0–1, e.g. <cd><color = [1 0 0]><cd>.

You can also include <cd><pb:trial.n><cd> to tell it to show trial number for the trial the text will run in—useful if you want to show trial number during the experiment.

wrapWidth

Default: wrap lines at 60 characters

Number of characters to wrap lines at. <cd>inf<cd> = don't wrap, but in text above you can still use an array of strings, <cd><n><cd>, or <cd>char(10)<cd> to wrap lines manually.

fontName

Default: Arial

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

fontSize

Default: 0.7 deg

This sets font height (deg). Specifically it sets height of the "em box" for the font. Typically upper case characters are a little smaller than this. If you need more information, see Wikipedia https://en.wikipedia.org/wiki/Point_(typography) for a starting point.

style

Default: regular

A string <cds>"r"<cds> = regular, <cds>"b"<cds> = bold, <cds>"i"<cds> = italic, or <cds>"u"<cds> = underline.

color

Default: white

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

alignment

Default: center text horizontally

A string <cds>"l"<cds> = left or <cds>"c"<cds> = center to horizontally align lines.

lineSpacing

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.

boxSize
margin
boxColor
vertAlignment

Default: boxSize = no text box
Default: margin = 0.5 deg
Default: boxColor = 90% white
Default: vertAlignment = center text vertically in box

You can show the text in a colored text box. If showing multiple pages of text, they appear in the same box.

boxSize sets text box size. This is a number for a square, or a vector [width height] for a rectangle (deg). Or a string <cds>"f"<cds> = fit box to text (largest text if multiple pages). 0 = no box.

margin sets space between the box and text edges (deg). This applies if you align text left or top, or fit the box to the text.

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

vertAlignment is a string <cds>"t"<cds> = top or <cds>"c"<cds> = center to vertically align text in the box.

listenKeyNames

Default: listen to all keys

An array of strings that are names of keys to listen to. All other keys are ignored. Key names are common across operating systems. To get them you can use the tool showKey at the MATLAB command line (type help showKey for usage, but basically press a key to see its name or use inputs to see all key names).

Or you can set this property to a vector of numbers that are key numbers. These are the same as used by Psychtoolbox functions like KbCheck. Note key numbers are different across operating systems. Again you can use showKey to see numbers.

ignoreKeyNames

Default: don't ignore any keys

Like listenKeyNames above except keys to ignore. You can leave listenKeyNames at default and set this property to listen to all keys except the ones you list here.

n_keyDevice

Default: listen to all attached keyboards

If you want to narrow down which keyboard device to listen to, you can set a HID device number here. Use Psychtoolbox functions GetKeyboardIndices or PsychHID('Devices') to see available device numbers.

showMouseCursor

Default: don't show mouse cursor

<cd>true<cd>/<cd>false<cd>: show the mouse cursor when the element is running (if not already showing). Note either way the element accepts mouse clicks. See also screen object property showMouseCursor.

position
nn_eyes
rotation
colorMask
alpha
intensity
contrastMult
drawCodeVars