Key element

Key elements let you listen for presses on keyboard keys.

Creation:

newKey("myKey", "")

Example:

newText("instructions", "Please press the spacebar")
    .print()
,
newKey("space", " ")
    .wait()
,
newText("thanks", "Thank you!")
    .print()

The code above adds a text asking for a press of the spacebar key. The text Thank you! get printed below it only after the spacebar was pressed.

Note: pass the void string "" for a press on any key.

Actions

key.wait

getKey(id).wait()

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

or getKey(id).wait(test)

Waits until a key is pressed.

If you call wait("first"), then if a valid key has been pressed since the creation of the key element, the next commands are evaluated and executed right away. If no valid key was pressed in the meantime, the next commands are only evaluated and executed after a valid key is pressed.

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

newText("instructions", "Please press the spacebar")
    .print()
,
newKey("space", " ")
    .wait()
,
newText("thanks", "Thank you!")
    .print()

Adds a text asking for a press of the spacebar key. The text Thank you! get printed below it only after the spacebar was pressed.

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

key.settings.callback

getKey(id).settings.callback( command )

or getKey(id).settings.callback( command1, command2 )

Will execute the command(s) whenever a key corresponding to the element is pressed.

Example:

newText("sentence", "Hello world")
    .print()
,
newVar("word", 0)
,
newKey("control", " \n\r")
    .settings.callback(
        getText("sentence")
            .settings.color("red")
        ,
        newTimer(1000)
            .start()
            .wait()
        ,
        getText("sentence")
            .settings.color("black")
    )

Prints Hello world onto the page and will highlight it in red for 1s whenever the Space or the Enter/Return key is pressed.

key.settings.log

getKey(id).settings.log()

or getKey(id).settings.log("wait") (since beta 0.4)

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

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

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

A line will be added to the results file indicating which key was pressed when.

If you leave the parentheses blank or pass "wait" (those are equivalent) then key presses will only be logged if they validate a .wait command on the Key element.

If you pass "first" then the first key press on one of the specified keys will be logged (regardless of whether it validates a .wait command). Correspondingly, if you pass "last" then the last valid key press will be logged. If you pass "all" then all key presses will be logged.

Note: "all" (or blank, its equivalent) was the only available option in beta 0.3.

newText("instructions", "Please press any key")
    .print()
,
newKey("anyKey", "")
    .settings.log()
    .wait()
,
newText("thanks", "Thank you!")
    .print()

Adds a text asking for a press on any key, after which the text Thank you! get printed below. The results file will contain a line indicating which key was pressed, and at what time(stamp) it was pressed.

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

key.test.pressed

getKey(id).test.pressed()

or getKey(id).test.pressed( string )

or getKey(id).test.pressed( string , "first" ) (since beta 0.3)

or getKey(id).test.pressed( number )

or getKey(id).test.pressed( number , "first" ) (since beta 0.3)

Tests whether a key was pressed.

If you pass no argument, it will yield success if any (valid) key has been pressed since the creation of the Key element. If you pass a string, it will test that the pressed key(s) is/are contained in the string. Alternatively you can pass a number representing a charCode. Since beta 0.3, if you pass a string as a second parameter (e.g. “first”) then only the first valid key that was pressed since the creation of the Key element will be tested.

Example:

newText("instructions", "Press F if you think 0.999... = 1, press J otherwise.")
    .print()
,
newKey("forj", "FJ")
    .wait()
,
getKey("forj")
    .test.pressed("F")
    .success( newText("success", "You're right!").print() )
    .failure( newText("failure", "You're wrong, 0.999... and 1 do refer to the same number").print() )

Will print the success message if the key that was pressed was F. Will print the failure message otherwise (i.e., if it was J).