Selector element

Selector elements let you create a group of existing elements out of which to make a selection, by clicking them or pressing a key.

Creation:

newSelector("mySelector")

Example:

newCanvas("two shapes", 820, 400)
    .settings.add(   0, 0, newImage("square", "square.png") )
    .settings.add( 420, 0, newImage("triangle", "triangle.png") )
    .print()
,
newSelector("shape")
    .settings.add( getImage("square") , getImage("triangle") )
    .wait()

The code above adds two images side by side and waits for a click on either one of them.

Actions

selector.select

getSelector(id).select(element)

Selects the specified element.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .select( getImage("square") )
    .wait()

Adds two images side by side, selects the image square by default, and waits for a click on either one of them.

selector.shuffle

getSelector(id).shuffle() (since beta 0.3)

or getSelector(id).shuffle( element1 , element2 , ... )

Shuffles the elements that have been added to the selector so far, so their positions on the page are randomly switched (NB: make sure the elements are already printed when you call shuffle).

You can specify a subset of elements to be shifted, so the other elements will remain in their original position no matter what, if you do not want to shuffle them.

Note: if you call .settings.keys before you shuffle, the key-element associations will be preserved. If you call .settings.keys after you shuffle, each key will be associated with the element that ends up where the element it was originally associated with was (useful if for instance you assign a key to “the element on the left” and a key to “the element on the right”).

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.disableClicks()
    .settings.add( getImage("square") , getImage("triangle") )
    .shuffle()
    .settings.keys(     "F"           ,        "J"           )
    .wait()

Adds two images side by side. Initially, square is on the left, and triangle is on the right, but .shuffle randomly reverses (or does not reverse) the order. A press on the F key will select the image that ends up on the left (whichever it ends up being) and a press on the J key will select the image that ends up on the right (whichever it ends up being).

selector.unselect

getSelector(id).unselect() (since beta 0.3)

Unselects any element currently selected.

selector.wait

getSelector(id).wait()

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

or getSelector(id).wait(test)

Waits until one of the elements of the selector is selected before evaluating and executing the next commands.

If you call wait("first"), then if an element has already been selected before this command is evaluated, the next commands are evaluated and executed right away. If no element was selected before, the next commands are only evaluated and executed after one element in the selector gets selected.

If you pass a test on an element as an argument, it only evaluates and executes the next commands when an element gets selected while the test is successful. If the test is not successful, it will be checked again upon the next selection.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .wait()

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

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

selector.settings.add

getSelector(id).settings.add( element1, element2, ... )

Adds as many elements to the selector. By default, selection is done through clicks. See .settings.keys and .settings.enableClicks and .settings.disableClicks.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .wait()

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

selector.settings.callback

getSelector(id).settings.callback( element )

or getSelector(id).settings.callback( function )

Will execute the command on the element upon next selection, or the function whenever selection happens.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.callback( getSelector("shapes").shuffle() )
    .wait()

Adds two images side by side. The positions of the images are shuffled anytime either image is clicked.

selector.settings.disableClicks

getSelector(id).settings.disableClicks()

Makes it impossible to select by clicking. If no .settings.keys command is called on the element, this makes any selection impossible.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.disableClicks()
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.keys(     "F"           ,        "J"           )
    .wait()

Adds two images side by side and waits for a selection by pressing either the F key or the J key.

selector.settings.enableClicks

getSelector(id).settings.enableClicks()

Makes it possible to select by clicking (default).

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.disableClicks()
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.keys(     "F"           ,        "J"           )
    .wait()
    .settings.enableClicks()

Adds two images side by side and waits for a selection by pressing either the F key or the J key, after which it becomes possible to select by clicking again.

selector.settings.frame

getSelector(id).settings.frame("border style")

Defines the style of the frame around the selected element. By default, it is set to solid 2px green.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.frame("dashed 3px violet")
    .wait()

Adds two images side by side, waits for a click on either one of them and then prints a button. Until the button is clicked, the selected image appears in a dashed, violet, 3px-wide frame.

selector.settings.keys

getSelector(id).settings.keys( "key1", "key2", ... )

Makes it possible to select the elements by pressing the specified keys. The keys are associated to the element in the order in which they were added, if no shuffle took place in the meantime.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.disableClicks()
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.keys(     "F"           ,        "J"           )
    .wait()

Adds two images side by side and waits for a selection by pressing either the F key or the J key.

selector.settings.log

getSelector(id).settings.log()

or getSelector(id).settings.log("first") (since beta 0.4)

or getSelector(id).settings.log("last") (since beta 0.4)

or getSelector(id).settings.log("all")

A line will be added to the results file when an element is selected indicating its reference name and the timestamp of selection.

Leaving the parentheses blank or calling "last" will log the last selection. Calling "first" will log the first selection. Calling "all" will log all selections.

Note: in beta 0.3, the only options were blank and "all", and they were equivalent.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.log()
,
newButton("validation", "Validate")
    .print()
    .wait()

Adds two images side by side and a button to click below them. Any selection of either image will output a line in the results file.

selector.settings.once

getSelector(id).settings.once()

Disables the selector after the first selection has happened.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
    .settings.once()

Adds two images side by side and a button to click below them. Any selection is definitive: further clicks will not move the frame.

selector.settings.shuffle

getSelector(id).settings.shuffle() (deprecated since beta 0.3)

or getSelector(id).settings.shuffle( element1, element2, ... )

See the action command shuffle

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

Tests

selector.test.index

getSelector(id).test.index( element ) (since version 1.0)

or getSelector(id).test.index( element , index ) (since version 1.0)

Tests the index of an element in the selector (starting with 0). If you pass no index, the test will be a success if the element is part of the selector, else a failure.

This is particularly useful when you want to test the position of an element after a shuffle.

Example:

newText("feedback")
,
newCanvas("shapes", 825, 440)
    .settings.add(   0,   0, newImage("square"  , "square.png"  ) ) 
    .settings.add( 425,   0, newImage("triangle", "triangle.png") ) 
    .print()
,
newSelector("choice")
    .settings.add( getImage("square") , getImage("triangle") ) 
    .shuffle()
,
getSelector("choice")
    .test.index( getImage("square") , 0 )
    .success( getText("feedback").settings.text("Square is on the left!")  )
    .failure( getText("feedback").settings.text("Square is on the right!") )
,
getCanvas("shapes")
    .settings.add( "center at 50%" , "center at 420" , getText("feedback") )

First draws a square Image element to the left of a triangle Image element onto a Canvas element, then groups the Image elements into a Selector element and uses this to shuffle their positions. Will draw a Text element saying Square is on the left! if the square Image element ended up first in the Selector element after shuffling (index = 0), or Square is on the right! otherwise (i.e., if it ended up second, index = 1).

selector.test.selected

getSelector(id).test.selected()

or getSelector(id).test.selected( element )

Tests whether an element is selected.

Example:

newImage("square", "square.png")
,
newImage("triangle", "triangle.png")
    .settings.before( getImage("square") )
    .print()
,
newSelector("shapes")
    .settings.add( getImage("square") , getImage("triangle") )
,
newButton("validation", "Validate")
    .print()
    .wait( getSelector("shapes").test.selected() )

Adds two images side by side, and a Validate button below them. The button will validate a click only after an image has been selected.