When to use it

When you want people to enter a word or a list of words.

You can also do this with readkeys (see below), but textbox has some advantages over readkeys.

You can also use the textbox for presenting long texts which then get automatically wrapped. You can use the lock function to make sure people cannot type in it.

What it does

When you use textbox, a rectangle is drawn on the experiment screen in which participants can enter words. You can set:

  • the size of the rectangle in which people can enter text

  • the color of the text and the color of the rectangle

  • the size of the text and the font of the text (arial, times, or courier)

How is it different from readkeys

  • readkeys was developed for PsyToolkit in the past and is older.

  • readkeys ends on pressing the Enter (also known as Return) key

  • readkeys cannot handle special characters, such as non-Latin characters

  • only textbox creates an HTML textarea overlay on top of the experiment, this allows for entry of any special character

  • unlike readkeys, textbox does not wait, you need to let it follow by a readmouse command to let the participant complete the text entry (see example below)

Tip

When people get a textbox on the screen, they will probably use the mouse to enter text in it. If you have a readmouse command to complete the text entry, this might end the textentry before you want to. Make sure that the readmouse command following the textbox uses a range option. This ensures that people need to use the mouse after textentry on a very specific range of rectangles or other stimuli to complete.

If you do not understand it, just try it out and see what happens with or without range.

Example 1

In the following example, the participant needs to enter words followed by enter. The textbox instruction draws a 700 by 500 pixels with a blue background and with white text on it. The text that will appear in it will have size 24 in font Arial.

The textbox is followed by a readkey. If you set the time to 999999 it basically waits for 999 seconds, which is quite long for an experiment.

task test
  keys enter
  show text "Enter words followed by Enter" 0 -280
  textbox new 0 0 700 500 white blue 24 arial
  textbox 1 focus
  readkey 1 999999
  set %mytext textbox
  textbox 1 clear
  save %mytext

block x
  tasklist
    test 1
  end

Example 2

In the following example, we have almost the same textbox as in Example 1, but just a bit smaller and now with a green button underneath which the participant needs to click to go on.

Further, we use the split function to split the typed words into an array.

task test
  show text "Enter words and click green rectangle when done" 0 -280
  show rectangle 300 250 140 80 green # button
  show text "Click me" 300 250
  textbox new 0 0 790 400 white blue 24 arial
  textbox 1 focus
  readmouse l 2 99999 range 2 2
  set %my_input textbox
  set %%my_list split %my_input
  textbox 1 clear
  save %%my_list

block x
  tasklist
    test 1
  end

Example 3

In the following example, we show text with a textbox. The textbox color and shape has already been explained in the above examples.

New here is that you show how to fill a textbox with the content of a textvariable. And how to erase the content. And to completely clear the textbox from the screen at the end.

clear is for removing the textbox, erase only erases its content. 
task test
  keys b
  set %mysentence "Can you please be so friendly to press the key b from the keyboard?"
  set %anothertext "Thank you!"
  textbox new 0 0 500 400 white blue 24 arial
  textbox 1 lock
  textbox 1 text %mysentence
  readkey 1 99999
  textbox 1 text %anothertext
  delay 1000
  textbox 1 erase
  delay 1000
  textbox 1 clear

block x
  tasklist
    test 1
  end