This chapter explains how to enter commands and includes links to all topics that are related to the script language in Widget Designer.
The built-in script language allows you to create customized routines of commands. Currently over 3000 commands are available to control specific features of Pandoras Box, Widget Designer or other 3rd party products and protocols. Commands can be used as a project's Start-up Script or in some nodes, tools and many widgets. A common task is to assign one or more commands to a button click.
1 - Choose a command name
In order to use a command, create anything that offers a scripting field, a Custom Script Button for example, and open its Item properties.
As soon as you start typing in the dedicated script text field, the feature Script Assistant will automatically search for available commands that contain the typed characters (see Filter Style) and display the result in a list box. WD commands can be written in upper or lower case style or mixed.
The availability of commands depends on the fact, whether a widget, device or node is already added to the project. For instance, the Script Assistant will not offer Fader related commands if there is none in the project.
The [Esc] key hides the Script Assistant window. Typing a new letter, opens it again.
To read more about a command in the Script Assistant window, select it either with a mouse click or the Up/Down arrow key of the keyboard. Double-click a command or hit the [Enter] or [Tab] key to apply it to the script field.
2 - Define its parameters
Most commands need to be executed with so called parameters that are enclosed in round brackets. In the example, the command WDFaderUp was chosen and now, the parameters "ID" and "Seconds" need to be defined so that Widget Designer knows which Fader should fade up for how long.
The Script Assistant will guide you through the parameters, by highlighting the current one, listing their total count, names and respective data types (such as String, Integer, Boolean, ...). The given Example and below Description help understanding what to enter, too.
You may either enter values directly, e.g. the number 1 to define ID 1 or "text" to define a string value. Or, you may substitute this with a variable which is explained in the chapter "Variables".
Please note that all literal values, meaning any kind of character string, have to be enclosed in either single or double quotation marks. If one of those is part of your string, just use the other one for declaring the literal. Do not use accents like ´ or `!
Some strings, like Pandoras Box device parameters or variable names, already appear in the Script Assistant with quotation marks. You can select one of those without adding anything and proceed with the next parameter. If you would like to use a variable's value, type the variable name without quotation marks. In contrast to the command names, parameter names are case-sensitive.
3 - Enter more commands, optional
After the last parameter, please close the command with a round bracket. Commands without parameters work without brackets. If you would like to extend your script with a second command, simply hit [Enter] and enter the next command. To delete a command, select it and press the [Delete] key.
4 - Execute / Test / Debug the script
As we have entered this script in the "On Press Script" from a Custom Script Button, it is executed when the user clicks the button.
In order to test single lines or the entire script, you can choose the according "Test..." option in the right-click menu of the script field or the according shortcuts: [Ctrl (+ Shift) + T].
The Debug Logger logs error messages, e.g. if a parameter is missing or has a wrong type. It can be opened with the shortcut [Ctrl + D] and is described in the chapter "Scripting Menu".
Depending on the command, the Script Assistant displays Alternative Examples which show that a command is available with the object and member notation, or "dot syntax", too. In those cases it is purely a question how the user prefers to write commands. The majority of commands exist for both workflows, the traditional workflow (WDFaderUp) and the newer dot syntax (Fader1.FadeUp). However, there are exceptions where a command exists only for either one. For newer features (like the Devices in the Configuration) for example, Widget Designer offers only the member notation.
The chapter "Command List" gives an overview of all traditional commands whilst the chapter "Object and Member Notation (dot syntax)" includes sub chapters mentioning those members which are not covered by the Command List. The Script Assistant refers to that information and displays it in Widget Designer directly.
The script depicted on the left does exactly the same as the one above but uses the dot syntax. Further, it defines a local variable called "time" in the beginning and assigns this to the fade and wait command.
This shows how both scripting techniques can be used to achieve the same result, but also that the dot syntax allows direct value assignment, e.g.: Label1.Text = "Fading...".
Please refer to these sub chapter for more information: