TextBox2

Attributes

TextBox2(win, text[, font, pos, units, ...])

The following `set______()` attributes all have equivalent `get______()` attributes:

TextBox2.text
TextBox2.alignment
TextBox2.hasFocus
TextBox2.overlaps(polygon[, tight])	Returns True if this stimulus intersects another one.
TextBox2.contains(x[, y, units, tight])	Returns True if a point x,y is inside the stimulus' border.
TextBox2.clear()	Resets the TextBox2 to a blank string
TextBox2.reset()	Resets the TextBox2 to hold whatever it was given on initialisation
TextBox2.font
TextBox2.height
TextBox2.anchor
TextBox2.editable	Determines whether or not the TextBox2 instance can receive typed text
TextBox2.padding
TextBox2.size	The (requested) size of the TextBox (w,h) in whatever units the stimulus is using
TextBox2.pos	The position of the center of the TextBox in the stimulus units
TextBox2.units
TextBox2.draw()	Draw the text to the back buffer

Details

class psychopy.visual.textbox2.TextBox2(win, text, font='Noto Sans', pos=(0, 0), units=None, letterHeight=None, ori=0, size=None, color=(1.0, 1.0, 1.0), colorSpace='rgb', fillColor=None, fillColorSpace=None, borderWidth=2, borderColor=None, borderColorSpace=None, contrast=1, opacity=None, bold=False, italic=False, placeholder='Type here...', lineSpacing=1.0, letterSpacing=None, padding=None, speechPoint=None, anchor='center', alignment='left', flipHoriz=False, flipVert=False, languageStyle='LTR', editable=False, overflow='visible', lineBreaking='default', draggable=False, name='', autoLog=None, autoDraw=False, depth=0, onTextCallback=None, clickable=True)

Parameters:

• win (Window) – The window this stimulus is associated with.

• text (str) – The text to display in the TextBox.

• font

• pos

• units

• letterHeight

• size (Specifying None gets the default size for this type of unit.) – Specifying [None, None] gets a TextBox that’s expandable in both dimensions. Specifying [0.75, None] gets a textbox that expands in the length but fixed at 0.75 units in the width

• color

• colorSpace

• contrast

• opacity

• bold

• italic

• lineSpacing

• padding

• speechPoint (list, tuple, np.ndarray or None) – Location of the end of a speech bubble tail on the textbox, in the same units as this textbox. If the point sits within the textbox, the tail will be inverted. Use None for no tail.

• anchor

• alignment

• fillColor

• borderWidth

• borderColor

• flipHoriz

• flipVert

• editable

• lineBreaking (Specifying 'default', text will be broken at a set of) – characters defined in the module. Specifying ‘uax14’, text will be broken in accordance with UAX#14 (Unicode Line Breaking Algorithm).

• draggable (bool) – Can this stimulus be dragged by a mouse click?

• name

• autoLog

property RGB

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

Type:

DEPRECATED

_addRenderOnlyChar(i, x, y, vertices, glyph, alphaCorrection=1)

Add a character at index i which is drawn but not actually part of the text

_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

_drawLegacyGL()

Legacy draw routine for older GL versions.

_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.

_layout()

Layout the text, calculating the vertex locations

_onCursorKeys(key)

Called by the window when cursor/del/backspace… are received

_onMouse()

Called by the window when the mouse is inside the stimulus.

_onText(chr)

Called by the window when characters are received

_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.

_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.

_updateVertices()

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

addCharAtCaret(char)

Allows a character to be added programmatically at the current caret

property alignment

alphaThreshold

Threshold for alpha values.

If the alpha value of a pixel is below this threshold, the pixel will be rejected (not drawn). This can be useful for creating a mask from an image with an alpha channel. The default value is 0.0, which means that no thresholding will be applied.

property anchor

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.

property backColor

Alternative way of setting fillColor

property backColorSpace

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

property backRGB

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

Type:

DEPRECATED

property backgroundColor

Alternative way of setting fillColor

property borderColor

property borderColorSpace

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

property borderRGB

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

Type:

DEPRECATED

borderWidth

clear()

Resets the TextBox2 to a blank string

clickable

Whether the stimulus can be clicked on.

If set to True, the stimulus will be checked for mouse clicks and the _onMouse method will be called if the stimulus is clicked.

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, tight=False)

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

containsPointer()

Check if the mouse is within the stimulus boundaries.

Returns:

Whether the mouse is within the stimulus.

Return type:

bool

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

deleteCaretLeft()

Deletes 1 character to the left of the caret

deleteCaretRight()

Deletes 1 character to the right of the caret

depth

DEPRECATED, depth is now controlled simply by drawing order.

doDragging()

If this stimulus is draggable, do the necessary actions on a frame flip to drag it.

doPointerActions()

Handle mouse interaction with the stimulus.

This method should be called each frame to update the stimulus based on mouse interactions.

draggable

Can this stimulus be dragged by a mouse click?

draw()

Draw the text to the back buffer

property editable

Determines whether or not the TextBox2 instance can receive typed text

property fillColor

Set the fill color for the shape.

property fillColorSpace

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

property fillRGB

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

Type:

DEPRECATED

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.

property flipHoriz

property flipVert

font

property fontColor

Alternative way of setting foreColor.

property fontMGR

property foreColor

Foreground color of the stimulus

Value should be one of:

• string: to specify a Colors by name. Any of the standard html/X11 color names <http://www.w3schools.com/html/html_colornames.asp> can be used.

• Colors by hex value

• numerically: (scalar or triplet) for DKL, RGB or

  other Color spaces. For these, operations are supported.

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

getAlignment()

getAlphaThreshold()

getAnchor()

getAutoDraw()

getAutoLog()

getBackColor()

getBackColorSpace()

getBackRGB()

getBackgroundColor()

getBorderColor()

getBorderColorSpace()

getBorderRGB()

getBorderWidth()

getCharAtPos(pos)

Get the character index at a given position.

This can be used to determine what character is under the specified position in the stimulus.

Parameters:

pos (list, tuple) – Position in stimulus units.

Returns:

Index of character at the given position. Returns None if no character is at the given position or if the position is outside the stimulus bounds.

Return type:

int or None

getClickable()

getColor()

getColorSpace()

getContrast()

getDepth()

getDraggable()

getEditable()

getFillColor()

getFillColorSpace()

getFillRGB()

getFlip()

getFlipHoriz()

getFlipVert()

getFont()

getFontColor()

getFontMGR()

getForeColor()

getForeColorSpace()

getForeRGB()

getHasFocus()

getHeight()

getLanguageStyle()

getLetterHeight()

getLetterHeightPix()

getLetterSpacing()

getLineColor()

getLineColorSpace()

getLineRGB()

getLineWidth()

getName()

getOpacity()

getOri()

getOverflow()

getPadding()

getPalette()

getPallette()

getPlaceholder()

getPos()

getRGB()

getSize()

getSpeechPoint()

getText()

Returns the current text in the box, including formatting tokens.

getUnits()

getVertices()

getVerticesPix()

getVisibleText()

Returns the current visible text in the box

getWidth()

getWin()

get_borderPix()

property hasFocus

property height

isDragging = False

property languageStyle

How is text laid out? Left to right (LTR), right to left (RTL) or using Arabic layout rules?

property letterHeight

property letterHeightPix

Convenience function to get self._letterHeight.pix and be guaranteed a return that is a single integer

letterSpacing

Distance between letters, relative to the current font’s default. Set as None or 1 to use font default unchanged.

property lineColor

Alternative way of setting borderColor.

property lineColorSpace

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

property lineRGB

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

Type:

DEPRECATED

lineWidth

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

overflow

overlaps(polygon, tight=False)

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).

Parameters

See coder demo, shapeContains.py

property padding

property palette

Describes the current visual properties of the TextBox in a dict

property pallette

Disambiguation for palette.

placeholder

Text to display when textbox is editable and has no content.

property pos

The position of the center of the TextBox 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:

myTextbox._pos.pix

reset()

Resets the TextBox2 to hold whatever it was given on initialisation

setAlignment(value, log=None, operation=False, stealth=False)

setAlphaThreshold(value, log=None)

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

setAnchor(value, log=None)

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.

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

setBackColorSpace(value, log=None, operation=False, stealth=False)

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

DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb

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

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

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

setBorderColorSpace(value, log=None, operation=False, stealth=False)

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

DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb

setBorderWidth(newWidth, operation='', log=None)

setClickable(value, log=None, operation=False, stealth=False)

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

setColorSpace(value, log=None, operation=False, stealth=False)

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

setDraggable(value, log=None, operation=False, stealth=False)

setEditable(value, log=None, operation=False, stealth=False)

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

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

setFillColorSpace(value, log=None, operation=False, stealth=False)

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

DEPRECATED: Legacy setter for fill RGB, instead set obj._fillColor.rgb

setFlip(value, log=None, operation=False, stealth=False)

setFlipHoriz(value, log=None, operation=False, stealth=False)

setFlipVert(value, log=None, operation=False, stealth=False)

setFont(font, log=None)

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

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

setFontMGR(value, log=None, operation=False, stealth=False)

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

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

setForeColorSpace(value, log=None, operation=False, stealth=False)

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

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

setHasFocus(value, log=None, operation=False, stealth=False)

setHeight(height, log=None)

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

setLanguageStyle(value, log=None, operation=False, stealth=False)

setLetterHeight(value, log=None)

setLetterSpacing(value, log=None, operation=False, stealth=False)

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

setLineColorSpace(value, log=None, operation=False, stealth=False)

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

DEPRECATED: Legacy setter for border RGB, instead set obj._borderColor.rgb

setLineWidth(newWidth, operation='', log=None)

setName(value, log=None, operation=False, stealth=False)

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

setOverflow(value, log=None, operation=False, stealth=False)

setPadding(value, log=None, operation=False, stealth=False)

setPalette(value, log=None, operation=False, stealth=False)

setPallette(value, log=None, operation=False, stealth=False)

setPlaceholder(value, log=False)

Set text to display when textbox is editable and has no content.

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

setSpeechPoint(value, log=None)

setText(text=None, log=None)

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

setUnits(value, log=None, operation=False, stealth=False)

setVertices(value, log=None, operation=False, stealth=False)

setWidth(value, log=None, operation=False, stealth=False)

setWin(value, log=None, operation=False, stealth=False)

property size

The (requested) size of the TextBox (w,h) in whatever units the stimulus is using

This determines the outer extent of the area.

If the width is set to None then the text will continue extending and not wrap. If the height is set to None then the text will continue to grow downwards as needed.

speechPoint

property text

property units

updateColors()

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

updateOpacity()

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

property vertices

property verticesPix

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

property visibleText

Returns the current visible text in the box

property width

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)

Back to top