TextInput element

TextInput elements let you to add one- (by default) or multiple-line input boxes to the screen.

Creation:

newTextInput("myTextInput", "some default text")

Example:

newTextInput("feedback", "Leave your feedback comments here.")
    .settings.log()
    .settings.lines(0)
    .settings.size(400, 200)
    .print()
,
newButton("send", "Send")
    .print()
    .wait()

Adds a 400x200px multiple-line input box containg the text Leave your feedback comments here to the screen above a Send button and waits for a click on the button. The text in the box at the end of the trial will be saved in the results file.

Actions

textinput.wait

getTextInput(id).wait()

or getTextInput(id).wait("first")

or getTextInput(id).wait( test )

Waits until the enter/return key is pressed while entering text in the input box. Note that if you have a multiple-line input box, this can also mean insertion of a new line.

If you call wait("first"), then if the enter/return key was already pressed while editing when this command is evaluated, the next commands are evaluated and executed right away. If the enter/return key was not clicked while editing before, the next commands are only evaluated and executed after the enter/return key is clicked while editing.

If you pass a test on an element as an argument, it only evaluates and executes the next commands when the enter/return key is pressed while the test is successful. If the test is not successful, it will be checked again next time the enter/return key is pressed while editing.

newTextInput("poem", "")
    .settings.before( newText("flowers", "Violets are blue, roses are red, ") )
    .print()
    .wait()

Adds a one-line input box to the screen preceded with Violets are blue, roses are red, on its left and waits for a press on the enter/return key.

standard.print

getElement(id).print()

or getElement(id).print(x,y) (limited support in PennController 1.3, general since 1.4)

or getElement(id).print(x,y,canvas) (limited support in PennController 1.3, general since 1.4)

Adds the content of the element to the screen. This has no effect for non-visual elements such as the purely interactive Selector elements.

Since PennController 1.3, you can pass x and y values to print the element at a specific position on the page, or on a Canvas element if you pass one (or the name of a Canvas element) as the third parameter. You can use any CSS coordinate format for x and y, or special string values following the respective formats "left|center|right at ..." and "top|middle|bottom at ...". Note that x and y are not supported for Audio, Canvas, Scale, TextInput, Video and Youtube elements in PennController 1.3 ; note also that elements added with .settings.before and .settings.after mess with proportional coordinates.

standard.refresh

getElement(id).refresh() (since PennController 1.1)

Calls the command print again on the element, while leaving it where it was printed last.

This command is primarily useful if some aesthetic command does not take effect unless print is called afterward, but you do not want to call print because calling it when you need the aesthetic command to take effect would move the element undesirably.

NOTE: PennController 1.1 handles this command incorrectly and it bugs systematically (draft)

Example:

newImage( "smiley" , "ya.png" )
,
newCanvas( "myCanvas" , 100 , 100 )
    .settings.css( "border" , "solid 1px black" )
    .settings.center()
    .settings.add( "center at 50%" , "center at 50%" , getImage("smiley") )
    .print()
,
newButton( "resize" , "Resize the image" )
    .print()
    .wait()
,
getImage( "smiley" )
    .settings.size( 64, 64 )
,
getCanvas("myCanvas")
    .refresh()

Prints the smiley image at the center of the canvas and adds a button below the canvas. After the button is clicked, the smiley is resized to 64×64 and without refresh the smiley would no longer be centrally aligned on canvas. Calling print on the canvas would recenter the image correctly, but it would move the canvas below the button. The solution is therefore to call refresh (or to call the settings command add again on the canvas).

standard.remove

getElement(id).remove()

Removes the element from the screen. This has no effect for non-visual elements such as the purely interactive Selector elements.

Note that this leaves no space where the element previously was on the page (this is really removing the element, not just hiding it).

Example

newButton("clickme", "Click me")
    .print()
    .wait()
    .remove()

Adds a button that says Click me to the screen, and removes it after it is clicked.

standard.setVar

getElement(id).setVar( varName ) (since beta 0.3)

Stores the current value of the element in the Var element named varName (if it exists).

What the current value corresponds to is specific to each element type:

  • For Audio elements, it corresponds to the timestamp of the end of the last playback so far (0 if never played back or playback never eneded).
  • For Button elements, it corresponds to the timestamp of the last click so far (0 if never clicked).
  • For Canvas elements, it corresponds to the number of elements it currently contains.
  • For Function elements, it corresponds to the value returned by the function.
  • For Html elements, it corresponds to whether the element is completely filled.
  • For Image elements, it corresponds to whether the image is currently being displayed.
  • For Key elements, it corresponds to the last key that was pressed so far (empty string if no key has been pressed so far).
  • For Scale elements, it corresponds to the value of the last option that was selected (NaN if no option has been selected so far).
  • For Selector elements, it corresponds to the last element that was selected (null if no element has been selected so far).
  • For Text elements, it corresponds to the current text.
  • For TextInput elements, it corresponds to the text that is currently in the input box.
  • For Timer elements, it corresponds to whether the timer has elapsed.
  • For Tooltip elements, it corresponds to whether the tooltip has been validated.
  • For Var elements, it corresponds to the element’s value.
  • For Video elements, it corresponds to the timestamp of the end of the last playback so far (0 if never played back or playback never eneded).
  • For VoiceRecorder elements, it corresponds to the last recording (undefined if no recording so far).
  • For Youtube elements, it corresponds to whether the video has been played.

Example:

newVar("name")
,
newTextInput("nameInput", "What is your name?")
    .settings.once()
    .print()
    .wait()
    .setVar("name")
,
newText("helloname")
    .settings.before( newText("hello", "Hello ") )
    .settings.text( getVar("name") )
    .print()

Creates a Var element named name and adds a text box in which to enter a name. When the return/enter key is pressed while editing the input box, it disables the box and stores its value in the Var element named name. Then it prints a text reading Hello name, where name corresponds to the value of the Var element.

Settings

textinput.settings.length

getTextInput(id).settings.length( number ) (since beta 0.3)

Limits the maximum number of characters that can be entered in the input box. 0 or lower means no limit (default setting). Note that linebreaks count as characters in the limit (\n and \r).

Example:

newTextInput("haiku", "hatsu shigure\nsaru mo komino o\nhoshige nari")
    .settings.length(45)
    .settings.lines(3)
    .print()

Adds a 3-line input box limited to 45 characters to the screen, containing a haiku (note the \n to insert linebreaks in the text).

textinput.settings.lines

getTextInput(id).settings.lines( number )

Sets the maximum number of lines for the input box (1 by default). As a special case, you set it to 0 to remove the limit constraint.

Example:

newTextInput("haiku", "hatsu shigure\nsaru mo komino o\nhoshige nari")
    .settings.lines(3)
    .print()

Adds a 3-line input box to the screen containing a haiku (note the \n to insert linebreaks in the text).

textinput.settings.log

getTextInput(id).settings.log()

or getTextInput(id).settings.log("final") (since beta 0.3)

or getTextInput(id).settings.log("validate") (since beta 0.3)

or getTextInput(id).settings.log("first") (since beta 0.3)

or getTextInput(id).settings.log("last") (since beta 0.3)

or getTextInput(id).settings.log("all") (since beta 0.3)

or getTextInput(id).settings.log("final", "first", ...) (since beta 0.3)

Will add a line to the result file containing the text in the input box at the moment of the event. By default, leaving the parenthesis blank is equivalent to .settings.log("final", "validate", "first").

  • "final" will add a line reporting the text in the input box at the end of the trial.

  • "validate" will add a line for each press on the enter/return key, reporting the text in the input box at that time and the corresponding timestamp.

  • "first" will add a line for the first key press that happens in the input box (regardless of whether the key press results in inserting or deleting a character or no change).

  • "last" will add a line for the last key press that happens in the input box (same note).

These two are helpful if you want to measure how much time was spent on editing the text, by subtracting first‘s timestamp from last‘s.

  • "all" is a special case: it will record every single key press in the input box (regardless of text modification, see note above). It will add a line reporting how many such events took place, and three more lines: one line reporting all the keys that were pressed, a line reporting the text at the moment of the key press, and a line reporting the timestamps of each key press. This can seriously increase the weight of the result file in cases where the text is long and/or edited a lot. Note that these three lines add an indefinite number of columns (i.e., as many as there were key press events). Keep that in mind when parsing the results file for analyses (e.g., you can use the fill=TRUE and col.names=paste("col", 1:N, sep="_") options in R’s command read.csv, with N corresonding to 12 + the number of key press events).

Example:

newTextInput("feedback", "Leave your feedback comments here.")
    .settings.log()
    .settings.lines(0)
    .settings.size(400, 200)
    .print()
,
newButton("send", "Send")
    .print()
    .wait()

Adds a 400x200px multiple-line input box containg the text Leave your feedback comments here to the screen above a Send button and waits for a click on the button. At least two lines will be added to the results file: one reporting the text in the box at the end of the trial, and one reporting the first key press. Additionally, you will see one line for each time the enter/return key was pressed.

textinput.settings.once

getTextInput(id).settings.once()

Disables the input box after the key enter/return has been pressed for the first time while editing.

newTextInput("poem", "")
    .settings.before( newText("flowers", "Violets are blue, roses are red, ") )
    .settings.once()
    .print()
    .wait()

Adds a one-line input box to the screen preceded with Violets are blue, roses are red, on its left and waits for a press on the enter/return key, after what the text can no longer be edited.

textinput.settings.text

getTextInput(id).settings.text("string") (since beta 0.3)

(Re)sets the text in the input box.

newTextInput("poem", "")
    .settings.before( newText("flowers", "Violets are blue, roses are red, ") )
    .print()
,
newButton("validate", "Validate")
    .print()
    .wait()
    .remove()
,
getTextInput("poem")
    .settings.disable()
    .settings.text("DISABLED")

Adds a one-line input box to the screen preceded with Violets are blue, roses are red, on its left, and a button reading Validate. The input box can no longer be edited after a click, and its text is replaced with “DISABLED”.

standard.settings.after

getElement(id).settings.after( getElement(id) )

Adds some content to the right of the element.

Example:

newImage("bad", "no.png")
,
newImage("good", "ya.png")
,
newText("left label", "Bad")
    .settings.before( getImage("bad") )
,
newText("right label", "Good")
    .settings.after( getImage("good") )
,
newScale("judgment", 5)
    .settings.before( getText("left label") )
    .settings.after( getText("right label") )
    .print()
    .wait()

Creates two image and two text elements and prints a 5-point radio-button scale, with the text Bad preceded by the image no.png on its left, and the text Good followed by the image ya.png on its right.

standard.settings.before

or getElement(id).settings.before( getElement(id) )

Adds some content to the left of the element.

Example:

newImage("bad", "no.png")
,
newImage("good", "ya.png")
,
newText("left label", "Bad")
    .settings.before( getImage("bad") )
,
newText("right label", "Good")
    .settings.after( getImage("good") )
,
newScale("judgment", 5)
    .settings.before( getText("left label") )
    .settings.after( getText("right label") )
    .print()
    .wait()

Creates two image and two text elements and prints a 5-point radio-button scale, with the text Bad preceded by the image no.png on its left, and the text Good followed by the image ya.png on its right.

standard.settings.center

getElement(id).settings.center()

Makes the element appear centered on the horizontal axis.

Example:

newText("helloworld", "Hello world")
    .settings.center()
    .print()

Prints Hello world onto the screen, horizontally centered.

standard.settings.css

getElement(id).settings.css("styleName", "style")

or getElement(id).settings.css({"style name 1": "style 1", "style name 2": "style 2"})

Applies the CSS style(s) to the element.

Example:

newText("frame", "framed")
    .settings.css("border", "solid 1px black")
,
newText("sentence", "The last word of this sentence is ")
    .settings.after( getText("frame") )
    .print()

Prints a text reading The last word of this sentence is framed, with the last word (framed) framed in a box with 1px black borders.

standard.settings.cssContainer

getElement(id).settings.cssContainer("styleName", "style")

or getElement(id).settings.cssContainer({"style name 1": "style 1", "style name 2": "style 2"})

Applies the CSS style(s) to the container’s element.

This will affect both the element itself and any element wrapping it as added via .settings.before or .settings.after.

This command often more closely accomplishes what you want to achieve than the .settings.css command.

Example:

newText("frame", " world")
    .settings.before( newText("Hello ") )
    .settings.css("border", "solid 1px black")
    .settings.cssContainer("border", "solid 1px red")
    .print()

Prints the text world preceded with the text Hello and adds a black frame around world and a red frame around the whole Hello world text.

standard.settings.disable

getElement(id).settings.disable()

Disables any interactive feature of the element.

Note: this does not prevent an element that is part of a Selector element from being selected.

Example:

newAudio("sentence", "test.mp3")
    .print()
    .wait()
,
getAudio("sentence")
    .settings.disable()

Prints buttons to play/pause the audio file test_sentence.ogg, and disables those buttons when the file has played through.

standard.settings.enable

getElement(id).settings.enable()

Enables any interactive feature of the element that was previously disabled.

Example:

newAudio("sentence", "test.mp3")
    .settings.once()
    .print()
,
newKey("secret key", "R")
    .wait()
,
getAudio("sentence")
    .settings.enable()

Prints buttons to play/pause the audio file test_sentence.ogg, and disables those buttons when the file has played through (see audio.settings.once).

standard.settings.hidden

getElement(id).settings.hidden() (since beta 0.3)

Makes the element invisible. Note that when printed, a hidden element still occupies space on the page, but its content is not visible.

Example:

newText("instruction", "Guess what fruit is in the image below")
    .print()
,
newImage("fruit", "pear.png")
    .settings.hidden()
    .print()
,
newButton("reveal", "Reveal fruit")
    .print()
    .wait()
,
getImage("fruit")
    .settings.visible()

Adds some text to the page, a blank space below it and a button below the blank space which, when clicked, reveals an image of a pear.

standard.settings.left

getElement(id).settings.left()

Makes the element appear horizontally aligned to the left (default).

Note: the left means the left of the container of the element, not necessarily the left of the screen.

Example:

newText("helloworld", "Hello world")
    .settings.right()
    .print()
,
newButton("left", "Align text to the left")
    .print()
    .wait()
,
getText("helloworld")
    .settings.left()

Prints Hello world onto the screen, horizontally aligned to the left.

standard.settings.right

getElement(id).settings.right()

Makes the element appear horizontally aligned to the right.

Note: the right means the right of the container of the element, not necessarily the right of the screen.

Example:

newText("sentence", "This is a longer sentence")
    .print()
,
newText("helloworld", "Hello world")
    .settings.right()
    .print()

Prints Hello world onto the screen, horizontally aligned to the right.

standard.settings.selector

getElement(id).settings.selector( selectorName )

or getElement(id).settings.selector( getSelector(selectorName) ) (since beta 0.3)

Since beta 0.3, Selector adds a .settings.selector command to all elements as another method for adding them to a selector.

Example:

newSelector("shapes")
,
newImage("square", "square.png")
    .settings.selector("shapes")
,
newImage("triangle", "triangle.png")
    .settings.selector("shapes")
,
newCanvas("shapes canvas", 825, 400)
    .settings.add(  0, 0, getImage("square") )
    .settings.add(425, 0, getImage("triangle") )
    .print()
,
getSelector("shapes")
    .wait()

Adds two images side by side and waits for a click on either one of them.

standard.settings.size

getElement(id).settings.size(width, height)

Resizes the element to a width of width pixels and a height of height pixels.

Example:

newImage("smiley", "pear.png")
    .settings.size(40, 40)
    .print()

Adds a 40x40px image pear.png onto the screen.

standard.settings.visible

getElement(id).settings.visible() (since beta 0.3)

Makes the element visible (again). This is useful if you previously hid the element with .settings.hidden.

Example:

newText("instruction", "Guess what fruit is in the image below")
    .print()
,
newImage("fruit", "pear.png")
    .settings.hidden()
    .print()
,
newButton("reveal", "Reveal fruit")
    .print()
    .wait()
,
getImage("fruit")
    .settings.visible()

Adds some text to the page, a blank space below it and a button below the blank space which, when clicked, reveals an image of a pear.

Tests

textinput.test.text

getTextInput(id).test.text("string")

or getScale(id).test.text( /RegExp/ )

Tests for a match with the text in the input box.

Example:

newTextInput("haiku", "hatsu shigure\nsaru mo komino o\nhoshige nari")
    .settings.lines(3)
    .print()
,
newButton("save", "Save")
    .print()
    .wait( getTextInput("haiku").test.text(/^.+[\r\n].+[\r\n].+$/) )

Adds a 3-line input box to the screen containing a haiku (note the \n to insert linebreaks in the text) above a Save button and waits for a click on the button. The click is validated only if, at the moment of the click, the text in the input box contains three lines of text.

standard.test.printed

getElement(id).test.printed() (since beta 0.3)

Tests whether the element was printed onto the page (and has not been removed since then).

Example:

newText("instructions", "Click on Top/Bottom to NOT print its word")
    .print()
,
newButton("top", "Top")
    .settings.callback( getButton("top").remove() ) 
    .print()
,
newButton("bottom", "Bottom")
    .settings.callback( getButton("bottom").remove() )
    .print()
,
newButton("print", "Print the buttons' words")
    .print()
    .wait()
    .remove()
,
getButton("top")
    .test.printed()
    .success( newText("top word", "hello").print() )
,
getButton("bottom")
    .test.printed()
    .success( newText("bottom word", "world").print() )

Prints a Top and a Bottom button onto the page, which disappear when clicked. After a click on the print button, the word hello will appear if the top button is still displayed, and the word world will appear if the bottom button is still displayed.