Script Parameters allow a script to take variable input from users, directly from custom UI input fields built from the script itself. A script can create or define UI input field controls, and then choose from various options on where to display them. The scripting system will then return the input that the user has entered in the script’s input fields in various ways, depending on where the input fields was shown.

Defining Input Fields

There are several script commands that let you define different types of UI input fields, including the textbox command, and the checkbox command. When these commands are executed, they take the arguments provided in the command as properties for the UI input field, and return a map that describes the input field that was defined by the command. It is important to note that these commands do not add any input fields to the app’s UI by themselves, but instead only define the properties, while the description of the UI input field returned by the command can be used in other commands that do add UI input fields to specific parts of the app.

The description of the UI input fields, as returned by these defining commands, can be stored in variables, or provided directly as an input to other commands. It is not recommended to store the returned descriptions of UI input fields in global variables.

Translation Parameters

Translation Parameters are script parameters that are shown in the output column in the advanced settings of a translation, when the script is selected as the output of that translation. The values provided in the UI input fields will be included as context every time the script is ran from the translation.

UI input fields can be added to a translation from a script using the translationparameter command. This command should only be used inside the uirefreshed event, as that event is called by the scripting system whenever the app requires the necessary UI parameter information to render the input fields.

Example:

// print the values entered by the user whenever the script is ran.
print ($parameters input1)
print ($parameters input2)

// listen for the event that tells us when the parameter info has to be provided
event uirefreshed
    // Define the properties of a textbox and checkbox and add them to the translation
    $textBox = (textbox "Input 1" "This is a description!")
    translationparameter input1 $textBox
    $checkBox = (checkbox "Input 2" "Checkbox description." true)
    translationparameter input2 $checkBox

A screenshot showing the advanced settings of a translation, with 2 script parameters provided by the selected script, named “input 1” and “input 2”.

Configuration Parameters (Beta Build #559)

Configuration Parameters are script parameters that are shown in their own separate configuration window, whenever the user chooses to open the script’s configuration window. The values entered in the UI input fields are returned to the script through the configchanged event, when the user closes the configuration window. As opposed to translation parameters, these values are not automatically included whenever the script is ran, and the script should use global variables to permanently store the values provided by the user, when they are returned in the configchanged event. This behaviour makes configuration parameters ideal for global settings for your script that don’t need to be specified with a translation parameter in every translation, or for scripts that don’t use translations at all.

The configuration window for a script can be shown by clicking the “configure” button below the script preview in the script hub. This button will automatically be shown or hidden depending on whether the script offers configuration parameters. For local scripts, the configuration window can also be opened in the script editor by clicking “File” in the menu bar and selecting “Configure Script” with a script open in the editor.

To provide the app with the UI input fields you want to be shown in the configuration window of your script, the configurationparameter command is used. This command should only be used inside the uirefreshed event, as that event is called by the scripting system whenever the app requires the necessary UI parameter information to render the input fields.

Example:

// listen for the event that tells us when the parameter info has to be provided
event uirefreshed
    // Assign a default value to the variable
    if !%my_script_configuration_value
        %my_script_configuration_value = "text here"
    // Add the configuration parameter UI element
    configurationparameter "input1" (textbox "Input 1" "The description!" %my_script_configuration_value)

// Listen for when the user submits a new configuration
event configchanged
    print ($trigger parameters)
    // Store the new value in the variable
    %my_script_configuration_value = ($trigger parameters input1)

A screenshot showing the configuration window of a script, opened through the configure button for the script in the script hub.

Inputwindow Parameters (Beta Build #560)

Another way for a script to take direct user input is through the inputwindow command. Similar to the configuration parameters, the inputwindow command allows you to create a new window with custom UI input fields on it. However, unlike the configuration parameters, the inputwindow command immediately opens the new window with the controls specified inside the inputwindow command. The inputwindow command will then hold the current script until the user closes the window that was opened, after which the inputwindow command will return the values provided by the user as a command return.

Once the window is closed, the command will return the input provided by the user in the form of a map where the keys are the ID’s specified for each UI input field, and the values are the values entered in the input field by the the user.

The inputwindow command allows for a script to show UI input fields on their own accord, without having to wait for a user to click a configure button or set up a translation. For public scripts, it is discouraged to use this for the purpose of a script configuration or translation variables, and only use it when it is the only logical way to obtain user input for your use case.

Example:
// define the UI input fields
$textBox = (textbox "Input 1" "This is a description!" "Text here!")
$checkBox = (checkbox "Input 2" "Checkbox description." true)
// show the input window with the specified input fields and retrieve the values
$values = (inputwindow "My Input Window" input1:$textBox,input2:$checkBox)
// print the value for the "Input 1" input field.
print ($values input1)

A screenshot showing a window created and opened by the inputwindow script command.