expyriment.stimuli.TextBox

class expyriment.stimuli.TextBox(text, size, position=None, text_font=None, text_size=None, text_bold=None, text_italic=None, text_underline=None, text_justification=None, text_colour=None, background_colour=None)

A class implementing a text box with wrapped text.

This wraps a given multiline string into a formatted mutliline text box, strips of leading and trailing lines and gets rid of additional whitespaces at beginning of lines (indentation).

Methods

__init__(text, size, position=None, text_font=None, text_size=None, text_bold=None, text_italic=None, text_underline=None, text_justification=None, text_colour=None, background_colour=None)

Create a text box.

Parameters :

text : str

text to wrap

size : (int, int)

size of the text box

position : (int, int), optional

position of the stimulus

text_font : str, optional

text font to use as a name or as a path to a font file

text_size : int, optional

size of the text

text_bold : bool, optional

font should be bold

text_italic : bool, optional

font should be italic

text_underline : bool, optional

font should get an underline

text_justification : int, optional

text justification, 0 (left), 1 (center), 2 (right)

text_colour : (int, int, int), optional

colour of the text

background_colour : (int, int, int), optional

background colour

Notes

text_font can be both, a name or path to a font file! When text_font is a name, Expyriment will try to find a font that best matches the given name. If no matching font can be found, or if the given font file cannot be found, the Pygame system default will be used. In any case the value of the attribute text_font will always resemble the font that is actually in use!

absolute_position

Getter for absolute_position.

add_noise(grain_size, percentage, colour)

Add visual noise on top of the stimulus.

This function might take very long for large stimuli.

Parameters :

grain_size : int

size of the grains for the noise

percentage : int

percentage of covered area

colour : (int, int, int)

colour (RGB) of the noise

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

background_colour

Getter for background_colour.

blur(level)

Blur the stimulus.

This blurs the stimulus, by scaling it down and up by the factor of ‘level’.

Parameters :

level : int

level of bluring

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

clear_surface()

Clear the stimulus surface.

Surfaces are automatically created after any surface operation (presenting, plotting, rotating, scaling, flipping etc.) and preloading. If the stimulus was preloaded, this method unloads the stimulus. This method is functionally equivalent with unload(keep_surface=False).

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

compress()

“Compress the stimulus.

This will create a temporary file on the disk where the surface of the stimululs is written to. The surface will now be read from the disk to free memory. Compressed stimuli cannot do surface operations! Preloading comressed stimuli is possible and highly recommended. Depending on the size of the stimulus, this method may take some time to compute!

Returns :

time : int

the time it took to execute this method

copy()

Deep copy of the visual stimulus.

Returns :copy : deep copy of self

Notes

Depending on the size of the stimulus, this method may take some time to compute!

decompress()

Decompress the stimulus.

This will decompress the stimulus. The surface will now be read from memory again. Depending on the size of the stimulus, this method may take some time to compute!

Returns :

time : int

the time it took to execute this method

distance(other)

Surface center distance.

This method computes the distance between the surface center of this and another visual stimulus.

Parameters :

other : stimulus

the other visual stimulus

Returns :

dist : float

distance between surface centers

flip(booleans)

Flip the stimulus.

This is a surface operation. After this, a surface will be present!

Parameters :

booleans : (bool, bool)

booleans to flip or not

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

format_block(block)

Format the given block of text.

This function is trimming leading and trailing empty lines and any leading whitespace that is common to all lines.

Parameters :

block : str

block of text to be formatted

has_surface

Getter for has_surface.

id

Getter for id.

inside_stimulus(stimulus, mode='visible')

Check if stimulus is inside another stimulus.

Parameters :

stimulus : expyriment stimulus

the other stimulus

mode : mode (str), optional

“visible”: based on non-transparent pixels or “rectangle”: based on pixels in pygame surface (default = visible”)

Returns :

out : bool

Notes

Depending on the size of the stimulus, this method may take some time to compute!

is_compressed

Getter for is_compressed.

is_preloaded

Getter for is_preloaded.

logging

Getter for logging.

move(offset)

Moves the stimulus in 2D space.

When using OpenGL, this can take longer then 1ms!

Parameters :

offset : list, optional

translation along x and y axis

Returns :

time : int

the time it took to execute this method

overlapping_with_position(position, mode='visible', use_absolute_position=True)

Check if stimulus is overlapping with a certain position.

Parameters :

position : (int, int)

position to check for overlapping

mode : mode (str), optional

“visible”: based on non-transparent pixels or “rectangle”: based on pixels in pygame surface (default = visible”)

use_absolute_position : bool, optional

use absolute_position of stimulus (default) instead of position

Returns :

overlapping : bool

Notes

Depending on the size of the stimulus, this method may take some time to compute!

overlapping_with_stimulus(stimulus, mode='visible', use_absolute_position=True)

Check if stimulus is overlapping with another stimulus.

Parameters :

stimulus : expyriment stimulus

the other stimulus

mode : mode (str), optional

“visible”: based on non-transparent pixels or “surface”: based on pixels in pygame surface (default = visible”)

use_absolute_position : bool, optional

use absolute_position of stimuli (default) instead of position

Returns :

overlapping : bool

are stimuli overlapping or not

overlap : (int, int)

the overlap (x, y) in pixels. If mode is ‘surface’, the argument will always be None.

Notes

Depending on the size of the stimulus, this method may take some time to compute!

picture()

Return the stimulus as Picture stimulus.

This will create a temporary file on the hard disk where the image is saved to.

Notes

Depending on the size of the stimulus, this method may take some time to compute!

plot(stimulus)

Plot the stimulus on the surface of another stimulus.

Use this to plot more than one stimulus and to present them at the same time afterwards by presenting the stimulus on which they were plotted on.

Parameters :

stimulus : expyriment stimulus

stimulus to whose surface should be plotted

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

position

Getter for position.

preload(inhibit_ogl_compress=False)

Preload the stimulus to memory.

This will prepare the stimulus for a fast presentation. In OpenGL mode this method creates an OpenGL texture based on the surface of the stimulus. When OpenGL is switched off, this method will create a surface if it doesn’t exists yet. If stimuli are not preloaded manually, this will happen automatically during presentation. However, stimulus presentation will take some time then!

Always preload your stimuli when a timing acurate presentation is needed!

Parameters :

inhibit_ogl_compress : bool, optional

inhibits OpenGL stimuli to be automatically compressed (default=False)

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

present(clear=True, update=True)

Present the stimulus on the screen.

This clears and updates the screen automatically. When not preloaded, depending on the size of the stimulus, this method can take some time to compute!

Parameters :

clear : bool, optional

if True the screen will be cleared automatically (default = True)

update : bool, optional

if False the screen will be not be updated automatically (default = True)

Returns :

time : int

the time it took to execute this method

render_textrect(string, font, rect, text_colour, background_colour, justification=0)

Return a surface with reformatted string.

The given text string is reformatted to fit within the given rect, word-wrapping as necessary. The text will be anti-aliased. Returns a surface.

Parameters :

string : str

text you wish to render, ‘

‘ begins a new line :

font : pygame.Font object, optional

Font object

rect : bool

rectstyle giving the size of requested surface

text_colour : (int, int, int)

text colour

background_colour : (int, int, int)

background colour

justification : int, optional

0 (Left), 1 (center), 2 (right) (int) (default = 0)

rotate(degree)

Rotate the stimulus.

This is a surface operation. After this, a surface will be present! Rotating goes along with a quality loss. Thus, rotating an already rotated stimulus is not a good idea.

Parameters :

degree : int

degree to rotate counterclockwise

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

save(filename)

Save the stimulus as image.

Parameters :

filename : str

name of the file to write (possible extensions are BMP, TGA, PNG, or JPEG with TGA being the default)

Notes

Depending on the size of the stimulus, this method may take some time to compute!

scale(factors)

Scale the stimulus.

This is a surface operation. After this, a surface will be present! Negative scaling values will flip the stimulus. Scaling goes along with a quality loss. Thus, scaling an already scaled stimulus is not a good idea.

Parameters :

factors : (int, int) or (float, float)

tuple representing the x and y factors to scale or a single number. In the case of a single number x and y scaling will be the identical (i.e., proportional scaling)

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

scramble(grain_size)

Scramble the stimulus.

Attention: If the surface size is not a multiple of the grain size, you may loose some pixels on the edge.

Parameters :

grain_size : int or (int, int)

size of a grain (use tuple of integers for different width & height)

Returns :

time : int

the time it took to execute this method

Notes

Depending on the size of the stimulus, this method may take some time to compute!

set_logging(onoff)

Set logging of this object on or off

Parameters :

onoff : bool

set logging on (True) or off (False)

Notes

See also design.experiment.set_log_level fur further information about event logging.

size

Getter for size.

surface_size

Getter for surface_size.

text

Getter for text.

text_bold

Getter for text_bold.

text_colour

Getter for text_colour.

text_font

Getter for text_font.

text_italic

Getter for text_italic.

text_justification

Getter for text_justification.

text_size

Getter for text_size.

text_underline

Getter for text_underline.

unload(keep_surface=False)

Unload the stimulus from memory.

This will unload preloaded stimuli. In OpenGL mode, this method will remove the reference to the OpenGL texture and the surface (when ‘keep_surface’ is False). When OpenGL is switched off, the reference to the surface will be removed (when ‘keep_surface’ is False).

Parameters :

keep_surface : bool, optional

keep the surface after unload (default=False)

Returns :

time : int

the time it took to execute this method

See also

clear_surface.

Notes

Depending on the size of the stimulus, this method may take some time to compute!