# TextStim¶

class psychopy.visual.TextStim(win, text='Hello World', font='', pos=0.0, 0.0, depth=0, rgb=None, color=1.0, 1.0, 1.0, colorSpace='rgb', opacity=1.0, contrast=1.0, units='', ori=0.0, height=None, antialias=True, bold=False, italic=False, alignHoriz=None, alignVert=None, alignText='center', anchorHoriz='center', anchorVert='center', fontFiles=(), wrapWidth=None, flipHoriz=False, flipVert=False, languageStyle='LTR', name=None, autoLog=None, autoDraw=False)[source]

Class of text stimuli to be displayed in a Window

Performance OBS: in general, TextStim is slower than many other visual stimuli, i.e. it takes longer to change some attributes. In general, it’s the attributes that affect the shapes of the letters: text, height, font, bold etc. These make the next .draw() slower because that sets the text again. You can make the draw() quick by calling re-setting the text (myTextStim.text = myTextStim.text) when you’ve changed the parameters.

In general, other attributes which merely affect the presentation of unchanged shapes are as fast as usual. This includes pos, opacity etc.

The following attribute can only be set at initialization (see further down for a list of attributes which can be changed after initialization):

languageStyle

Apply settings to correctly display content from some languages that are written right-to-left. Currently there are three (case- insensitive) values for this parameter:

• 'LTR' is the default, for typical left-to-right, Latin-style

languages.

• 'RTL' will correctly display text in right-to-left languages

such as Hebrew. By applying the bidirectional algorithm, it allows mixing portions of left-to-right content (such as numbers or Latin script) within the string.

• 'Arabic' applies the bidirectional algorithm but additionally

will _reshape_ Arabic characters so they appear in the cursive, linked form that depends on neighbouring characters, rather than in their isolated form. May also be applied in other scripts, such as Farsi or Urdu, that use Arabic-style alphabets.

Parameters

property RGB

Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb

Type

DEPRECATED

_calcPosRendered()

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix.

_calcSizeRendered()

DEPRECATED in 1.80.00. This functionality is now handled by _updateVertices() and verticesPix

_getDesiredRGB(rgb, colorSpace, contrast)

Convert color to RGB while adding contrast. Requires self.rgb, self.colorSpace and self.contrast

_getPolyAsRendered()

DEPRECATED. Return a list of vertices as rendered.

_selectWindow(win)

Switch drawing to the specified window. Calls the window’s _setCurrent() method which handles the switch.

_set(attrib, val, op='', log=None)

DEPRECATED since 1.80.04 + 1. Use setAttribute() and val2array() instead.

_setTextShaders(value=None)[source]

Set the text to be rendered using the current font

_updateList()

The user shouldn’t need this method since it gets called after every call to .set() Chooses between using and not using shaders each call.

_updateListShaders()[source]

Only used with pygame text - pyglet handles all from the draw()

_updateVertices()

Sets Stim.verticesPix and ._borderPix from pos, size, ori, flipVert, flipHoriz

alignHoriz

Deprecated in PsychoPy 3.3. Use alignText and anchorHoriz instead

alignText

Aligns the text content within the bounding box (‘left’, ‘right’ or ‘center’) See also anchorX to set alignment of the box itself relative to pos

alignVert

Deprecated in PsychoPy 3.3. Use anchorVert

anchorHoriz

The horizontal alignment (‘left’, ‘right’ or ‘center’)

anchorVert

The vertical alignment (‘top’, ‘bottom’ or ‘center’) of the box relative to the text pos.

antialias

Allow antialiasing the text (True or False). Sets text, slow.

autoDraw

Determines whether the stimulus should be automatically drawn on every frame flip.

Value should be: True or False. You do NOT need to set this on every frame flip!

autoLog

Whether every change in this stimulus should be auto logged.

Value should be: True or False. Set to False if your stimulus is updating frequently (e.g. updating its position every frame) and you want to avoid swamping the log file with messages that aren’t likely to be useful.

bold

Make the text bold (True, False) (better to use a bold font name).

property boundingBox

(read only) attribute representing the bounding box of the text (w,h). This differs from width in that the width represents the width of the margins, which might differ from the width of the text within them.

NOTE: currently always returns the size in pixels (this will change to return in stimulus units)

property color

Alternative way of setting foreColor.

property colorSpace

The name of the color space currently being used

Value should be: a string or None

For strings and hex values this is not needed. If None the default colorSpace for the stimulus is used (defined during initialisation).

Please note that changing colorSpace does not change stimulus parameters. Thus you usually want to specify colorSpace before setting the color. Example:

# A light green text
stim = visual.TextStim(win, 'Color me!',
color=(0, 1, 0), colorSpace='rgb')

# An almost-black text
stim.colorSpace = 'rgb255'

# Make it light green again
stim.color = (128, 255, 128)

contains(x, y=None, units=None)

Returns True if a point x,y is inside the stimulus’ border.

Can accept variety of input options:
• two separate args, x and y

• one arg (list, tuple or array) containing two vals (x,y)

• an object with a getPos() method that returns x,y, such

as a Mouse.

Returns True if the point is within the area defined either by its border attribute (if one defined), or its vertices attribute if there is no .border. This method handles complex shapes, including concavities and self-crossings.

Note that, if your stimulus uses a mask (such as a Gaussian) then this is not accounted for by the contains method; the extent of the stimulus is determined purely by the size, position (pos), and orientation (ori) settings (and by the vertices for shape stimuli).

See Coder demos: shapeContains.py See Coder demos: shapeContains.py

property contrast

A value that is simply multiplied by the color.

Value should be: a float between -1 (negative) and 1 (unchanged).

Operations supported.

Set the contrast of the stimulus, i.e. scales how far the stimulus deviates from the middle grey. You can also use the stimulus opacity to control contrast, but that cannot be negative.

Examples:

stim.contrast =  1.0  # unchanged contrast
stim.contrast =  0.5  # decrease contrast
stim.contrast =  0.0  # uniform, no contrast
stim.contrast = -0.5  # slightly inverted
stim.contrast = -1.0  # totally inverted


Setting contrast outside range -1 to 1 is permitted, but may produce strange results if color values exceeds the monitor limits.:

stim.contrast =  1.2  # increases contrast
stim.contrast = -1.2  # inverts with increased contrast

depth

DEPRECATED, depth is now controlled simply by drawing order.

draw(win=None)[source]

Draw the stimulus in its relevant window. You must call this method after every MyWin.flip() if you want the stimulus to appear on that frame and then update the screen again.

If win is specified then override the normal window of this stimulus.

property flip

1x2 array for flipping vertices along each axis; set as True to flip or False to not flip. If set as a single value, will duplicate across both axes. Accessing the protected attribute (._flip) will give an array of 1s and -1s with which to multiply vertices.

flipHoriz

If set to True then the text will be flipped left-to-right. The flip is relative to the original, not relative to the current state.

flipVert

If set to True then the text will be flipped top-to-bottom. The flip is relative to the original, not relative to the current state.

font

String. Set the font to be used for text rendering. font should be a string specifying the name of the font (in system resources).

fontFiles

A list of additional files if the font is not in the standard system location (include the full path).

OBS: fonts are added every time this value is set. Previous are not deleted.

E.g.:

stim.fontFiles = ['SpringRage.ttf']  # load file(s)
stim.font = 'SpringRage'  # set to font

property foreColor

Foreground color of the stimulus

Value should be one of:

When color is specified using numbers, it is interpreted with respect to the stimulus’ current colorSpace. If color is given as a single value (scalar) then this will be applied to all 3 channels.

Examples

For whatever stim you have:

stim.color = 'white'
stim.color = 'RoyalBlue'  # (the case is actually ignored)
stim.color = '#DDA0DD'  # DDA0DD is hexadecimal for plum
stim.color = [1.0, -1.0, -1.0]  # if stim.colorSpace='rgb':
# a red color in rgb space
stim.color = [0.0, 45.0, 1.0]  # if stim.colorSpace='dkl':
# DKL space with elev=0, azimuth=45
stim.color = [0, 0, 255]  # if stim.colorSpace='rgb255':
# a blue stimulus using rgb255 space
stim.color = 255  # interpreted as (255, 255, 255)
# which is white in rgb255.


Operations work as normal for all numeric colorSpaces (e.g. ‘rgb’, ‘hsv’ and ‘rgb255’) but not for strings, like named and hex. For example, assuming that colorSpace=’rgb’:

stim.color += [1, 1, 1]  # increment all guns by 1 value
stim.color *= -1  # multiply the color by -1 (which in this
# space inverts the contrast)
stim.color *= [0.5, 0, 1]  # decrease red, remove green, keep blue


You can use setColor if you want to set color and colorSpace in one line. These two are equivalent:

stim.setColor((0, 128, 255), 'rgb255')
# ... is equivalent to
stim.colorSpace = 'rgb255'
stim.color = (0, 128, 255)

property foreColorSpace

Deprecated, please use colorSpace to set color space for the entire object.

property foreRGB

Legacy property for setting the foreground color of a stimulus in RGB, instead use obj._foreColor.rgb

Type

DEPRECATED

height

The height of the letters (Float/int or None = set default).

Height includes the entire box that surrounds the letters in the font. The width of the letters is then defined by the font.

Operations supported.

italic

True/False. Make the text italic (better to use a italic font name).

name

The name (str) of the object to be using during logged messages about this stim. If you have multiple stimuli in your experiment this really helps to make sense of log files!

If name = None your stimulus will be called “unnamed <type>”, e.g. visual.TextStim(win) will be called “unnamed TextStim” in the logs.

property opacity

Determines how visible the stimulus is relative to background.

The value should be a single float ranging 1.0 (opaque) to 0.0 (transparent). Operations are supported. Precisely how this is used depends on the Blend Mode.

ori

The orientation of the stimulus (in degrees).

Should be a single value (scalar). Operations are supported.

Orientation convention is like a clock: 0 is vertical, and positive values rotate clockwise. Beyond 360 and below zero values wrap appropriately.

overlaps(polygon)

Returns True if this stimulus intersects another one.

If polygon is another stimulus instance, then the vertices and location of that stimulus will be used as the polygon. Overlap detection is typically very good, but it can fail with very pointy shapes in a crossed-swords configuration.

Note that, if your stimulus uses a mask (such as a Gaussian blob) then this is not accounted for by the overlaps method; the extent of the stimulus is determined purely by the size, pos, and orientation settings (and by the vertices for shape stimuli).

See coder demo, shapeContains.py

property pos

The position of the center of the stimulus in the stimulus units

value should be an x,y-pair. Operations are also supported.

Example:

stim.pos = (0.5, 0)  # Set slightly to the right of center
stim.pos += (0.5, -1)  # Increment pos rightwards and upwards.
Is now (1.0, -1.0)
stim.pos *= 0.2  # Move stim towards the center.
Is now (0.2, -0.2)


Tip: If you need the position of stim in pixels, you can obtain it like this:

from psychopy.tools.monitorunittools import posToPix
posPix = posToPix(stim)

property posPix

This determines the coordinates in pixels of the position for the current stimulus, accounting for pos and units. This property should automatically update if pos is changed

setAutoDraw(value, log=None)

Sets autoDraw. Usually you can use ‘stim.attribute = value’ syntax instead, but use this method to suppress the log message.

setAutoLog(value=True, log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setContrast(newContrast, operation='', log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setDKL(color, operation='')

DEPRECATED since v1.60.05: Please use the color attribute

setDepth(newDepth, operation='', log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setFlip(direction, log=None)[source]

(used by Builder to simplify the dialog)

setFlipHoriz(newVal=True, log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setFlipVert(newVal=True, log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setFont(font, log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setForeColor(color, colorSpace=None, operation='', log=None)

Hard setter for foreColor, allows suppression of the log message, simultaneous colorSpace setting and calls update methods.

setForeRGB(color, operation='', log=None)

DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb

setHeight(height, log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setLMS(color, operation='')

DEPRECATED since v1.60.05: Please use the color attribute

setOpacity(newOpacity, operation='', log=None)

Hard setter for opacity, allows the suppression of log messages and calls the update method

setOri(newOri, operation='', log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setPos(newPos, operation='', log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

setRGB(color, operation='', log=None)

DEPRECATED: Legacy setter for foreground RGB, instead set obj._foreColor.rgb

setSize(newSize, operation='', units=None, log=None)

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message

setText(text=None, log=None)[source]

Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.

property size

The size (width, height) of the stimulus in the stimulus units

Value should be x,y-pair, scalar (applies to both dimensions) or None (resets to default). Operations are supported.

Sizes can be negative (causing a mirror-image reversal) and can extend beyond the window.

Example:

stim.size = 0.8  # Set size to (xsize, ysize) = (0.8, 0.8)
print(stim.size)  # Outputs array([0.8, 0.8])
stim.size += (0.5, -0.5)  # make wider and flatter: (1.3, 0.3)


Tip: if you can see the actual pixel range this corresponds to by looking at stim._sizeRendered

text

The text to be rendered. Use \n to make new lines.

Issues: May be slow, and pyglet has a memory leak when setting text. For these reasons, this function checks so that it only updates the text if it has changed. So scripts can safely set the text on every frame, with no need to check if it has actually altered.

updateColors()

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox

updateOpacity()[source]

Placeholder method to update colours when set externally, for example updating the pallette attribute of a textbox.

property verticesPix

This determines the coordinates of the vertices for the current stimulus in pixels, accounting for size, ori, pos and units

property win

The Window object in which the stimulus will be rendered by default. (required)

Example, drawing same stimulus in two different windows and display simultaneously. Assuming that you have two windows and a stimulus (win1, win2 and stim):

stim.win = win1  # stimulus will be drawn in win1
stim.draw()  # stimulus is now drawn to win1
stim.win = win2  # stimulus will be drawn in win2
stim.draw()  # it is now drawn in win2
win1.flip(waitBlanking=False)  # do not wait for next
# monitor update
win2.flip()  # wait for vertical blanking.


Note that this just changes default window for stimulus.

You could also specify window-to-draw-to when drawing:

stim.draw(win1)
stim.draw(win2)

wrapWidth

Int/float or None (set default). The width the text should run before wrapping.

Operations supported.