Loading...

The Function and Macro Editor lets you store a series of commands as a script. It can include variable parameters that can be changed easily and any time when calling the script to be executed. In other words, a script is a sub routine, with or without input variables, that allows dynamic programming. The difference between functions and macros is explained below.

Using scripts in form of functions or macros is helpful when the same series of commands should be called from different places especially when the same command structure should be executed but its effect should be adjusted flexibly. Those scripts save time entering and editing commands.

Setting up a Function or Macro

To open the editor go to "Scripting" and "Scripts (Functions & Macros)". An exemplary function is depicted below. Enter a function or macro name an optional description. Click the "Add" button if you would like to have dynamic parameters (the colored placeholders). Then enter the scripting text itself referring to these parameters. The descriptions are shown in the ScriptAssistant later when calling the Macro/ Function.
Click "Apply" to save the script or changes you made in it.

If you have many macros and functions in your project, it might come in handy to have them sorted in folders. The "Path" field enables you to enter a path that creates folders within the Scripting menu and files your script there. In the example below, the function can be found in the folder "functions" in the sub folder "faders".

In the scripting field you may enter commands to be executed, just type in the command directly in the text field. The topic Script Language explains this in more detail.
See here a list of all commands.
You can also use other functions and macros, Variables and other programming statements e.g. an If-clause. It is not recommended to call the same function or macro recursively as you might create a deadlock!

A function can end with an optional return statement, a line that says "return" and "something". You can return all kind of values, e.g. variables, strings or Boolean values. This value can be used from outside the function for further usage or maybe simply as a "function completed" message. Macros do not have return expressions.

If you decide you would rather use a macro than a function, you can change the type anytime with the drop-down below the scripting section.

 

Testing a Function or Macro

To test a script, you can right-click in the script field and press "Test". A new window will open where you can enter values to substitute your optional parameters. When you use this way of testing, you don't have a display for your function return value. You could for example enter a "DebugMessage" command right before your return statement to check if your return value was computed correctly.

 

 

Calling a Macro

You can call a macro within scripts, functions or other macros and you have two possible ways to do so. The first option is to call it by its name and values for your parameters in round brackets, like any normal Widget Designer command.

e.g.: FaderMacro(1,5)

Alternatively, the command "WDMacro" can be used. The optional macro parameters are added as parameters to WDMacro:

WDMacro("FaderMacro",1,5)

Macros are always called asynchronously, i.e. they run simultaneously and do not "block" other scripts or macros. The following example will execute the macro "FaderMacro" three times at once, which means that all three Faders fade up and down together within 4 seconds:

FaderMacro(1,2)

FaderMacro(2,2)

FaderMacro(3,2)

 

Calling a Function

Functions are called similar to macros. If you want to make use of the return value, you need an additional object receiving this value:

e.g.: Label1.Text = FaderFunction(1,5)

The fading script is being executed and the text of Label1 is set to "Done".

The receiving object has to match the data type of the return value. In this case, we return a string value, so we could for example also set a string variable "varString", or other Widgets' properties like "InputBox1.Text", "Playlist2.Title" and "Fader3.Note" instead of "Label1.Text".

Equivalent to this syntax, the command "VGetFunctionResult" can be used to execute the function and write its return value in a predefined variable:

var result = ""

VGetFunctionResult("result","FaderFunction",1,5)  

Calling the script with the function name only will also execute the fading script, if a return value was set, it is discarded:

FaderFunction(1,5)

Alternatively, the command "WDFunction" can be used. The optional function parameters are added as parameters to WDFunction:

WDFunction("FaderFunction",1,5)

It is also possible to integrate the return value in another command parameters. This script would have the same result as the example above:

WDLabelText(1,FaderFunction(1,5))

You can also write the return value into the DebugLogger and add the system Variable "Now" which returns the date and time from the moment it is accessed, e.g. DebugMessage(Now + " - " + FaderFunction(1,5)) results in the message: 2017-10-10 17:06:28.143 - Done

In this example, we use the FaderFunction from above and generate an entry in the DebugLogger as log for a successful execution:

DebugMessage(Now + " - " + FaderFunction(1,2))

DebugMessage(Now + " - " + FaderFunction(2,2))

DebugMessage(Now + " - " + FaderFunction(3,2))

 

Functions in Widget Designer are always called in blocking mode, i.e. synchronously. This means that it is not possible to run several functions simultaneously within one script, they will always be executed one after another, i.e. after the previous functions has finished.

The example above shows a synchronous call, it would fade Fader1 up and down first and write the log message, then Fader2, then Fader3. Each fade begins only after the previous one has finished. The complete script would be finished after 12 seconds (4 seconds per call), the DebugLogger would show something similar to this:

2017-10-10 17:05:52.266 - Done

2017-10-10 17:05:56.289 - Done

2017-10-10 17:06:00.308 - Done

 

Important Note

Scripts in WD are processed from top to bottom in the order you wrote them in. Some methods in WD are synchronous, others asynchronous. Examples are the command "WDFaderUp" which can fade several faders simultaneously, whereas the command "WDWait" blocks the script until the wait time is elapsed. When you write a script, you can decide how it is supposed to be processed.

A macro that is supposed to run in blocking mode can either be used inside of a function, or you can simply write the macro script as a function without return statement.

A function can never be called asynchronously. If you do not need a return statement but want to have your functions processed simultaneously, use a macro instead.

 

Additional Example for a Function

This example shows how a function can be used to compare two numbers and return the higher number so that it can be used for displaying it in a label and fading an according fader.