Tooltip element

Tooltip elements (since beta 0.3) let you add temporary boxes of text disappearing after validation that can be anchored to other elements.

Creation:

newTooltip("myTooltip", "Hello world!", "Click me")

Creates a tooltip reading Hello world with a button reading Click me! at its bottom-right corner.

Example:

newImage("myImage", "square.png")
    .print()
,
newTooltip("myTooltip", "This is a square")
    .print( getImage("myImage") )

Adds an image to the page and places a box with the text This is a square to its bottom-right corner, which disappears when a validation button (reading OK by default) is clicked.

Actions

tooltip.print

getTooltip(id).print()

or getTooltip(id).print( getElement(id) ) (since beta 0.3)

Adds the tooltip to the page, or attaches it to the referenced element (if any).

newImage("myImage", "square.png")
    .print()
,
newTooltip("myTooltip", "This is a square")
    .print( getImage("myImage") )
    .wait()

Adds an image to the page and places a box with the text This is a square to its bottom-right corner, which disappears when a validation button (reading OK by default) is clicked.

tooltip.wait

getTooltip(id).wait()

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

or getTooltip(id).wait(test) (since beta 0.3)

Waits until the tooltip is validated and disappears before evaluating and executing the next commands.

If you call wait("first"), then if the tooltip has already been validated at least once by the time this command is evaluated, the next commands are evaluated and executed right away. If it was never validated before, the next commands are only evaluated and executed after the tooltip has been validated.

If you pass a test on an element as an argument, it only evaluates and executes the next commands when the tooltip is validated while the test is successful. If the test is not successful, it will be checked again next time the tooltip is validated. Note that failure does not prevent the tooltip from being validated and disappearing. To circumvent this behavior, you can print the tooltip again upon failure (see example).

Example:

newAudio("sentence", "test.mp3")
    .print()
,
newTooltip("playAudio", "Play this audio file before proceeding")
    .print( getAudio("sentence") )
    .wait( 
        getAudio("sentence")
            .test.hasPlayed()
            .failure( getTooltip("playAudio").print(getAudio("sentence")) )
    )
,
newText("confirmation", "Now you can proceed")
    .print()

Adds an interface to play the file test.mp3 to the page and attaches a tooltip reading Play this audio file before proceeding at its bottom-left corner. The confirmation text Now you can proceed will only be added to the page when clicking the tooltip’s validation button (at its bottom-right corner, reading OK by default) after the audio has been played at least once. If the tooltip is validated before the audio has been played (validation having the systematic effect of making the tooltip disappear) the failure command re-attaches the tooltip to the audio interface.

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

tooltip.settings.frame

getTooltip(id).settings.frame()

or getTooltip(id).settings.frame("frame-style frame-width frame-color") (since beta 0.3)

Will add a frame surrounding the element to which the tooltip is attached when it is printed. You can optionally define the aesthetics of the frame by passing a string following the CSS format for borders.

newImage("myImage", "square.png")
    .print()
,
newTooltip("myTooltip", "This is a square")
    .settings.frame()
    .print( getImage("myImage") )
    .wait()

Adds an image to the page, surrounds it by a 1px, dotted, gray frame (by default) and places a box with the text This is a square to its bottom-right corner. Both the frame and the tooltip disappear when the tooltip is validated.

tooltip.settings.key

getTooltip(id).key("keys")

or getTooltip(id).key("keys", "no click")

or getTooltip(id).key(keycode)

or getTooltip(id).key(keycode, "no click") (since beta 0.3)

Makes it possible to validate the tooltip by pressing a key. You can either pass a string of keys, or pass the keycode of a specific key (e.g. 13 for enter/return). If you pass a non-null second parameter (e.g. “no click”) then clicks will have no effect for validation, and if you have not specified a text for the validation button when creating the tooltip, no such button will be displayed at its bottom-right corner.

newImage("myImage", "square.png")
    .print()
,
newTooltip("myTooltip", "Press enter/return when you are done admiring this beautiful square")
    .settings.key(13, "no click")
    .print( getImage("myImage") )
    .wait()

Adds an image to the page and places a box with the text Press enter/return when you are done admiring this beautiful square to its bottom-right corner, containing no validation button. The tooltip will disappear only when the enter/return key (whose keycode is 13) is pressed.

tooltip.settings.label

getTooltip(id).settings.label("text") (since beta 0.3)

Resets the text of the validation button.

Example:

newAudio("sentence", "test.mp3")
    .settings.disable()
    .print()
    .play()
,
newTooltip("instruction", "After the audio is done playing, you can replay it as many times as you want", "Please wait")
    .settings.disable()
    .print( getAudio("sentence") )
,
getAudio("sentence")
    .wait()
    .settings.enable()
,
getTooltip("instruction")
    .settings.label("OK")
    .settings.enable()
    .wait()

Adds a disabled interface to play the audio test.mp3 to the page, starts playing it immediately and attaches a disabled tooltip to its bottom-right corner, with its validation button reading Please wait. After the audio has finished playing, the interface is enabled (so the audio can be replayed at will) as well as the tooltip, whose validation button’s text gets changed for OK.

tooltip.settings.log

getAudio(id).settings.log() (since beta 0.3)

Will add a line in the results file each time the tooltip is validated.

Example:

newAudio("sentence", "test_sentence.ogg")
    .settings.log()
    .wait()
    .print()
,
newTooltip("instructions", "Use this interface to replay the audio as many times as you want")
    .settings.log()
    .print( getAudio("sentence") )
    .wait()

Starts playing the audio file testsentence.ogg_ and, when it has finished playing, adds an interface to replay it at will onto the page and attaches a tooltip at its bottom-right corner. Since .settings.log is called on both the audio and the tooltip, the results file can tell how long of a delay passed between the end of playback and the validation of the tooltip, and whether and how many times the audio was replayed before and after validating the tooltip.

tooltip.settings.position

getTooltip(id).settings.position("position") (since beta 0.3)

Defines the relative position of the tooltip when it is attached to an element (bottom-right by default).

If position contains top, the bottom edge of the tooltip will be aligned with the top edge of the element to which it is attached. If it contains middle, the vertical middle axis of the tooltip will be aligned with that of the element to which it is attached. If it contains bottom, the top edge of the tooltip will be aligned with the bottom edge of the element to which it is attached.

If position contains left, the right edge of the tooltip will be aligned with the left edge of the element to which it is attached. If it contains center, the horizontal middle axis of the tooltip will be aligned with that of the element to which it is attached. If it contains right, the left edge of the tooltip will be aligned with the right edge of the element to which it is attached.

You can use CSS to define margins to adjust the alignment of tooltips.

Example:

newImage("myImage", "square.png")
    .print()
,
newTooltip("myTooltip", "This is a square")
    .settings.position("top center")
    .print( getImage("myImage") )
    .wait()

Adds an image to the page and places a tooltip reading This is a square above the image, horizontally centered to its middle axis.

tooltip.settings.text

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

Resets the text of the tooltip.

newAudio("sentence", "test.mp3")
    .settings.log()
    .print()
,
newTooltip("instructions", "Use this interface to play and replay the audio as many times as you want")
    .print( getAudio("sentence") )
,
getAudio("sentence")
    .wait()
,
getTooltip("instructions")
    .settings.text("Feel free to replay if you want")

Shows an interface to play the audio test.mp3 and attaches a tooltip at its bottom-right corner. The text will be updated after the audio has played, if the tooltip has not been validated, and therefore has not disappeared from the screen in the meantime.

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

getElement(id).settings.bold()

Makes any text in the element appear boldfaced.

Example:

newText("warnning", "NOTE: this text is a warning!")
    .settings.bold()
    .settings.italic()
    .settings.color("red")
    .print()

Prints a text in boldface, italic and red.

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

getElement(id).settings.color("color")

Makes any text in the element appear in the specified color. The "color" string follows CSS conventions (most common names such as “red”, “blue”, … are valid)

Note: if you want to change the background color of an element (say, a Canvas element) use .settings.css("background", color) where color is the name of a color (e.g. "green")

Example:

newText("warnning", "NOTE: this text is a warning!")
    .settings.bold()
    .settings.italic()
    .settings.color("red")
    .print()

Prints a text in boldface, italic and red.

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

getElement(id).settings.italic()

Makes any text in the element appear in italic.

Example:

newText("warnning", "NOTE: this text is a warning!")
    .settings.bold()
    .settings.italic()
    .settings.color("red")
    .print()

Prints a text in boldface, italic and red.

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

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.