String

Examples

= ASCII text in 'single' or "double" quotation marks;

Do not use accents like ` or ´. If you want to use quotation marks as part of your string, use the other kind for declaring the string.

'hello'
'C:\folder1\subfolder2'
'Hello, "World"!'

Double

= number with decimal places; a floating-point number

-5.567

12.123456789

Integer

= number without decimal places

-50
512

Boolean

= Boolean value "True" or "False";

Letters are case-insensitive.

True

False

Date

= a special data type containing time and date information

11/30/2016 09:30:38

List

= list of several objects of the same or different data type (even other variables and other lists can be part of a list)

In former versions, this was called an array.

[1,2,3,5,8,13]

[3, "abc", v_double, ["i", "j", "k"]]

Color

= an object containing 8bit information (value ranges from 0 to 255) about the red, green, blue and alpha channel of a color

The RGB value in the variable list is displayed as hexadecimal code, this page might come in useful when translating colors to and from hex code: https://www.w3schools.com/colors/colors_hexadecimal.asp

#FFFFFF (white)

#7D8000FF (50%opacity, violet)

JSON

= a format for easily storing, editing and exchanging sets of data.

For more information concerning syntax and usage, please refer to the chapter Using JSON

{"name": "Tom", "age": 29}

{"arr": [1,3,5], "map": {"a":1.2, "b": 2}}

Global variables can be used from each script, node or widget that belongs to the WD project. They can be created, edited and viewed in the Variable List or by using the scripting language. The best practice is, to declare global variables first and use them then in separate scripts.

The "Variable List" dialog can be opened via: Scripting menu > Variables. The list shows all existing global variables, their type and value.
The Free version of Widget Designer does not offer the Variable List but it does support variables using the script language.

Even when opening the Variable List for the first time, there are already some variables. These system variables are called internal variables and are created per default, update automatically and can not be deleted nor edited. The system Variable "Now" for example returns the time and date at the moment it is accessed and can be useful for debug messages, protocols or timed events.

The left screenshot shows additional variables that were added by the user as follows. In this example they all start with "var_".

The first way to create a global variable is to use the "Create" command from the right-click menu within the Variable List. Simply decide what type, name and (starting) value it should have and click "Ok".
Please note that the name may consist of letters (lowercase or capital) and numbers, as well as underscore "_", the first character must be a letter. Valid variable names would be "Var_String123" "or myName".

For most variable types you simply pick the value you would like to assign and click "Ok". With the Locked option the variable stays constant, you cannot edit the value until it is unlocked.
A new Boolean variable is initiated with the value "False". Tick the check box "True / Active / Yes" to turn it to "True".
For a list variable enter the elements and separate them with the symbol you defined as the "Separator", e.g. "1,2,3". The square brackets you see later, are added automatically. Building nested lists is only possible from within scripts, adding a list in a list is not possible by directly editing a global variable.

To change a value, right-click the variable and choose "Edit". As explained below, this can also be done via scripting or by using nodes.

The second way to declare a global variable is to use the command VCreate that asks for a new(!) variable name and then a value, e.g.:

VCreate("vString","Karl")

The chapter "Script Language" explains how to work with commands. The variable type is assigned automatically and depends on the value you assign first. In some cases so called members need to be used to specify the type correctly. This is shown below with local variables.

Local variables are initialized inside a script and are deleted as soon as this script is finished. Their values are only accessible within this single script.

You can define a local variable inside of a script by using the indicator "var " (var and space) before a variable name. The variable name must be unique within the scope of the script and - as for global variables - it may consist of letters, numbers and the underscore "_" whilst the first character must be a letter, e.g. "V_String2" or "myName".

As seen with below examples, the value that you assign first defines the type of the value. For defining a date, color and json properly, so called members are used which are explained in detail in the chapter Data Type Specific Members.

var vString = "Karl"

var vDouble = 73.3

var vInteger = 3

var vBoolean = True

var vDate = "2000-1-1 0:0:0".ToDate

var vList = [1,2,3]

var vColor = "#80FF00".ToColor

var vJson = '{"name":"Adam"}'.ToJson

You can also use the member ".Type"  to check the type of a variable e.g. if you are debugging a script that is not working.
var x = Now

DebugMessage(x.Type) //returns "Date"

var y = Now.ToString

DebugMessage(y.Type) //returns "String"

var z

DebugMessage(z.Type) //returns "Object"

The last examples shows that a local variable can be defined without assigning a value in the same step. The variable is then simply an object without a defined type. This is not possible with global variables.

Commands are also interesting in the further workflow when a variable is called and assigned to something else or when it is edited.

After having declared a global or local variable it can adopt a different value at any time. The new value must be of the same type or convertible. Widget Designer tries to convert values as far as possible. The Debug Message "Invalid variable value!" tells you if that was not possible. In those cases you can use members to convert values manually first. The member ".ToInteger", for example, converts a Boolean value to a 1 or 0 (= integer value).

Vice Versa, you can assign the variable to another object such as a Label, Fader, Device, Variable, etc. All members are listed in the according sub chapter under "Object and Member Notation (dot syntax)". Commands are listed in the command list, and more information about the way to write commands is described in the chapter "Script Language". The value of a global variable can also be changed in the Variable List, which was introduced above, or by using Nodes which is shown next.

In case you work with list variables, you might wonder how to write or read them if they get more complex. As an example the variable varList holds different value types, first the integer 3, then the string "abc" and a (so called nested) list with the strings "i" and "j". So the list should look like this: [3,"abc",["i","j"]]

VCreate("varList",[3,"abc",["i","j"]])

Elements of the list can be accessed via an index in square brackets.
varList[0] -> returns 3
varList[1] -> returns "abc"
varList[2] -> returns ["i", "j"]
varList[2][1] -> returns "j"

This example shows how to create a local list variable and fill a DropDown List with the content, then set Label1 to "Berlin" and Fader1 to value 3:
var x = ["Berlin","Cherry",3]

DropDownList1.SetItemsFromArray("x")

Label1.Text = x[0]

Fader1.Value=x[2]

Note that the this example only works with a local variable. When working with global variables, please create them first (e.g. via the command VCreate) and use their values in separate scripts. The reason is, that scripts are compiled before they are executed and global variables cannot be declared and used in one compilation. This is when local variables should be used.

If you would like to lock a variable, use the command VLock(Name). The variable can not be changed until it is unlocked. In the Variable List there is a check box called Lock.
Fading a variable is possible with these commands VFadeTo(VarName,Value,Time) and VFade(VarName,StartValue,EndValue,Time).

Once a global (!) variable is declared it can also be used in the Nodes system by refering to its name. The Nodes chapter explains the usage of nodes.

The Variable Input node can be found under Nodes > Input > Generic and can be linked to a filter or output node in order to use the variable's value there.
The Variable Output node can be found under Nodes > Output > Generic and can be linked to a filter or input node in order to use their value as the new variable value. The output node updates the variable constantly with a new value.

In the depicted example the Fader Input node writes the fader's value into a variable. Then the Variable Input node writes the value into a label. This could of course also be done directly or with below alternative.

Some controls, e.g. a label, allows accessing a variable directly. In the example we could delete the Variable Input Node (ID 3) and the Label Output Node (ID 4) and instead tick the check box "Variable Source" in the label's Item Properties.

Member values, e.g. "Fader.Value", could be seen as some sort of "internal variable". Widget Designer declares them automatically with each item you add to your project. Their name and value relate to the item they belong to. Otherwise you can use member values and variables in the Script language in the same way. See the next chapter Object and Member Notation (dot syntax) for more details.