MultiTextBox class

A text box that can present one or more values during a trial, e.g., to shown an RSVP. You can easily configure the onset and offset time of each of the values to present.

Each value to present is implemented as a separate Expyriment TextBox, which means that:

  • You can set the graphical properties (font, size, position, etc.) to have a common value for all presented texts, or a separate value per text.
  • Changing from one text to another is not time-consuming, and can be safely done in mid-trial. The only time-consuming operation is when you initialize the stimuli (which should be done at the beginning of the trial)

A MultiTextBox is not by itself a stimulus (e.g., it does not have a present() method). The stimulus-like methods can be accessed via stimulus.

Using this class:

This class is used in slightly different ways depending on whether or not you use an EventManager in your application.

Using MultiTextBox with an EventManager

Using MultiTextBox without an EventManager

  • On the beginning of each trial, update the visual properties of the textbox (text, font, size, position, etc.). You do not need to configure the events.
  • After these properties were set, call init_for_trial().
  • To start showing the stimuli, call start_showing().
  • Call update_display() periodically - preferably once per frame.

Other features

callback functions: (available also for MultiStimulus)

You can ask the MultiTextBox class to invoke a function of your choice whenever a text is displayed or hidden. Register your function with register_onset_offset_callback_func()

Methods and properties:

class trajtracker.stimuli.MultiTextBox(texts=None, text_font='Arial', text_size=26, text_bold=False, text_italic=False, text_underline=False, text_justification=1, text_colour=(255, 255, 255), background_colour=(0, 0, 0), size=None, position=(0, 0), onset_time=None, duration=None, last_stimulus_remains=False, onset_event=None, terminate_event=<trajtracker.events._Event.Event object>)
__init__(texts=None, text_font='Arial', text_size=26, text_bold=False, text_italic=False, text_underline=False, text_justification=1, text_colour=(255, 255, 255), background_colour=(0, 0, 0), size=None, position=(0, 0), onset_time=None, duration=None, last_stimulus_remains=False, onset_event=None, terminate_event=<trajtracker.events._Event.Event object>)
background_colour

The background color TextBox. This can be either a single tuple (RGB) or a list of tuples, one per shown text

duration

The duration of showing each stimulus.

A stimulus disappears when the duration expired or when a terminate_event was dispatched.

Type:list/tuple of numbers
get_stimulus_desc(stimulus_num)

Get one of the stimuli (= the text presented)

Parameters:stimulus_num – The index of the text to return
Returns:str
init_for_trial()

Initialize when a trial starts.

Do not use this function if you are working with the events mechanism.

last_stimulus_remains

Whether the last stimulus presented in the sequence should remain on screen (True), or has a limited duration similarly to the previous stimuli (False)

log_level

Logging level of this object: trajtracker.log_none, log_error (default), log_warn, log_info, log_debug, log_trace

onset_event

The event which serves as a reference point for displaying stimul. All onset_time’s are indicated relatively to this event.

Note: This property is relevant only when working with events (with an EventManager)

onset_time

The onset time of each stimulus, relatively to the onset_event.

Type:list/tuple of numbers
position

The position of the stimuli to show (x,y). This can be either a single tuple or a list of tuples, one per shown value

register_onset_offset_callback_func(func)

Register a function that should be called when a stimulus is shown/hidden

Parameters:func –

The function, which gets 4 parameters:

  1. The MultiStimulus/MultiTextBox object
  2. The stimulus/text number (0=first)
  3. Whether the stimulus is presented (True) or hidden (False)
  4. The time when the corresponding present() function returned
size

The size of the TextBox (width,height). This can be either a single tuple or a list of tuples, one per shown text

start_showing(time)

When working without events: this sets time=0 for the texts to show (i.e., the onset_time are relatively to this time point).

This function will also invoke update_display().

Do not use this function if you are working with the events mechanism.

Parameters:time – The time in the current session/trial. This must be synchronized with the “time” argument of update_display()
stim_visibility

Return an array of booleans, indicating whether each stimulus is presently visible or not. The array has as many elements as text

stimulus

A single stimulus that represents all the stimuli in this MultiTextBox

Type:StimulusContainer
terminate_event

An event that terminates the display of stimuli, including the display of stimuli that are still scheduled to appear. Default: TRIAL_ENDED.

You can set to None to disable termination; however, note that in this case you might get strange behavior if the next trial starts while the stimuli are still being shown. To prevent this, you’ll have to take care yourself of cleaning up pending operations from the event manager.

Note: This property is relevant only when working with events (and with an EventManager)

text_bold

Whether the text is bold (bool) This can be either a single value or a list of values, one per shown text

text_colour

The color of the text to show. This can be either a single tuple (RGB) or a list of tuples, one per shown text

text_font

The font name (str) This can be either a single value or a list of values, one per shown text

text_italic

Whether the text is in italic font (bool) This can be either a single value or a list of values, one per shown text

text_justification

The horizontal justification of the text. 0=left, 1=center, 2=right. This can be either a single value or a list of values, one per shown text

text_size

The font size (int) This can be either a single value or a list of values, one per shown text

text_underline

Whether the text is underlined (bool) This can be either a single value or a list of values, one per shown text

texts

The texts to show (a list of strings)

trial_configured_event

An event indicating the time when the per-trial information was configured. By default, this is the TRIAL_INIITALIZED event.

Note:

  • This property is relevant only when working with events (and with an EventManager)
  • The property cannot be changed after the object was registered to an EventManager
unregister_onset_offset_callback_func(func)

Unegister a callback function previously registered with unregister_onset_offset_callback_func()

Parameters:func – The function
update_display(time)

Set relevant stimuli as visible/invisible.

Do not use this function if you are working with the events mechanism.

Parameters:time – The time in the current session/trial. This must be synchronized with the “time” argument of start_showing()