Variables

Navigation:  Widget Designer > Scripting >

Variables

prev main next

Navigation:  Widget Designer > Scripting >

Variables

prev main next

Please wait. Due to its content this page might take a while to load...

What is a variable?

Variables are a powerful feature in Widget Designer. Any value can be stored within a variable and be called from another widget or node or command. Variables can hold one (or more) variable value(s) that update automatically, or they can hold one (or more) constant value(s).

Variables are subdivided into these types: String, Double, Integer, Boolean, Date, List, Color and JSON.

String

Ex. 1:

'hello'

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

(do not use accents like ` or ´)

Ex. 2:

'C:\folder1\subfolder2'

If you want to use quotation marks as part of your string, use
the other kind for declaring the string.

Ex. 3:

'Hello, "World"!'

Double

Ex. 1:

-5.567

= number with decimal places

Ex. 2:

12.123456789

(a floating-point number)

Ex. 3:

99999.9

Integer

Ex. 1:

-50

= number without decimal places

Ex. 2:

0

 

Ex. 3:

51347

Boolean

Ex. 1:

True

= Boolean value "True" or "False"
(the letters are case insensitive)

Ex. 2:

False

Date

Ex. 1:

11/30/2016 09:30:38

= a special data type containing time and date information

 

 

List

Ex. 1:

["Sample", "John", 31, false]
(two strings, an integer, a Boolean)

= formerly known as arrays; holds several objects of the same or different data type even other variables and other lists can be part of a list

Ex. 2:

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

Color

Ex. 1

#808080 (dark gray)

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

Ex. 2:

#8000FF (intense violet)

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

Ex. 3:

#FFFFFF (white)

JSON

Ex. 1

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

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

Ex. 2

{"string":"Hello!", "bool": true, "pi": 3.14}

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

 

{"arr": [12,34,56], "map": {"a":1.2, "b": 2.3, "c": 3.4}}

Variables can be defined either globally or locally:
Global variables can be called and edited within the complete project, they are saved in the Variable List.
Local variables are initialized inside a script and will be deleted as soon as this script is finished, their values are also only accessible from inside this single script.

How to create a global variable?

Widget Designer includes a (below depicted) tool called "Variable List". Go to the Scripting menu and choose "Variables" to open it. The list shows all existing global variables, their type and value.
The free version does not include the Variable List though it supports variables.

If you open the Variable List the first time, you will see that 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 time and date at the moment it is accessed and can be useful for debug messages, protocols or timed events.

The additional variables starting with "var_" were declared by the user as follows:

wd_variable-list

wd_variable-list_create

First of all, a variable needs to be declared. You may use the right-click menu within the Variable List or the command VCreate to do so. Commands are also interesting in the further workflow e.g. calling and editing a variable, particularly a list variable.
When you create the variable, decide what type, name and (starting) value it should have.

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. A valid variable name would be e.g. "Var_String123".

For most variable types you simply pick the value you 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 choose from the drop-down, 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.

Every Variable type has its own group of available members. To learn more about object members, please refer to the chapter Object and Member Notation.

A complete list of all members related to special types can be found in the chapter Data Type Specific Member.

How to assign another value to a global variable?

After having declared a variable it can adopt a different value at any time. Obviously the new value must be of the same type. For assigning a new value, there are three ways: use the right-click menu in the Variable List, a node or commands.

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 Nodes chapter explains the usage of nodes. The output node updates the variable constantly with a new value. An example is depicted below.

There are very fast commands like Variable = Value to assign a new (member) value. This is also called a direct command, in difference to common commands, they are more direct, fast and flexible. Please see the below table for possibilities to assign new values to variables. Commands are listed in the command list, and more information about the way to write commands is described in the chapter "Script Language".
 

wd_variables_var-commands

As you see above you can assign values in many ways. In most cases, you can only assign a correct variable type, e.g. a string to a string variable. If you like to assign another type, you need to convert it first, e.g. like this varInteger = varBoolean.ToInteger The chapter Object and Member Notation (dot syntax) explains this syntax in more detail and gives more examples.

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"

There are also commands like Variable += 1, that adds 1 to the current value of the variable. Variable = (1+2*3) even does a complex mathematical calculation for you. More of these advanced variable assignments can be found in the chapter Math Expression.

There are many ways to draw a value from another control like a Label, ListView element, Fader etc.: Start typing the command "VGet" and you will see the full list of possibilities. Alternatives are described in the topic Object and Member Notation (dot syntax).

If you 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(Variable,Value,Time and VFade,Variable,StartValue,EndValue,Time).

 

How to use variables?

Once a variable is declared it can be used by its alias name. There are several ways to do so; one is creating 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. 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.

wd_variable-nodes-setup

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

The last way is using a variable in commands. There are several commands that allow writing a value into a variable, in the command list they start with VGet... . As well you may use commands to assign a specific value or result of a math operation to a variable.
To use a variable's value instead of an argument within a command simply use the variable name. For example, TCPSend(1,var_String) will send "hello" via the TCP Connection if you have declared this variable before.
The chapter Object and Member Notation (dot syntax) gives more examples of commands with variables.

 

How to create and use a local variable?

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 new and valid, i.e. as for global variables, it may consist of letters only (lowercase or capital) and numbers, as well as underscore "_" and the first character must be a letter. A valid variable name would be e.g. "Var_String123".
A value can, but does not have to be assigned in the same step.

The type of the local variable will be determined automatically by its first value as seen in the following examples:

This will set Label1 to "example" and Label2 to "another example".
var x = "an example"
Label1.text = x
var y = "another example"
WDLabelText(2,y)

 

This will set the Fader1 to 50 and Fader2 to 150.
var z = 50
Fader1.Value = z
WDFaderValue(2,z+100)

For more examples of use and practical hints concerning everything around the Widget Designer's scripting language, please also have a look at the Scripting Guide

 

What is the difference between a variable and a member value ?

Member values, e.g. "Fader.Value", could be explained as internal variables. 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.