Script Editor

The Script Editor, as its name suggests, is used to edit Script functions.
It basically consists in a text editor where the user can write a script using a meta-language with a syntax described below.
The script can be manually modified if you have a full understanding of the language syntax, otherwise a few helper buttons are available on the rightmost side of the editor to speed up and facilitate the script creation/editing.
Each line of a script will be executed by QLC+ in a sequential order.

Controls

	Enable the output and run the Script to test its execution
Script name	Change the name of the Script.
	When clicked, this button will display a popup where you can choose the script snippet you want to insert at the current cursor position in the editor. Start Function: Opens the function Selection dialog to select a Function to be started. This operation will automatically add a comment at the end of the line of code, with the QLC+ name of the selected Function. Stop Function: Opens the function Selection dialog to select a Function to be stopped. If at the moment of execution of this line of code the selected Function is not running, this instruction will have no effect. This operation will automatically add a comment at the end of the line of code, with the QLC+ name of the selected Function. Blackout: Opens dialog requesting whether blackout should be turned on or off. Set Fixture: Opens the Fixture Channels selection dialog, where you can choose the channels you want to control with the Script. If multiple channels are selected, this operation will add one line of code for each selected channel. By default, the DMX value generated by this operation will be 0 and has to be changed manually with the script text editor. This operation will automatically add a comment at the end of the line of code, with the QLC+ name of the selected fixtures and channels. System Command: Opens a file dialog to choose the external program/script to run. Please note that the selected file must be executable to be accepted. Once a file has been selected another dialog will ask to enter the program/script arguments. If none are required, just leave the field empty. Wait: Opens a dialog requesting the time to be waited before the script can execute the next instruction Comment: Opens a dialog requesting the text of the comment to insert at the cursor position in the editor. A comment has a C language style appearance: it starts with "//" and everything until the end of the line is then considered a comment Random Number: Opens a dialog requesting the range of values where to perform a randomization of a number. The resulting code snippet will be inserted at the editor current cursor position. This can be useful to randomize DMX values set through the setfixture keyword. See below. File Path: Open a file dialog to select a file. The absolute path and the file name will be inserted at the editor current position. If a path contains spaces, it will be written within quotes
	Cut the currently selected text in the editor for a later paste
	Copy the currently selected text in the editor for a later paste
	Paste a previously cut or copied text at cursor position in the editor
	Undo the last performed operation on the editor
	Check the Script syntax. A popup message will be displayed indicating if the Script is OK or the line numbers where syntax errors have been found.

Language syntax

The QLC+ Script meta-language is based on a keyword:value model, with some insertions of C language syntax rules.
Each line of code is parsed by the QLC+ engine and verified to detect the presence of syntax errors.
Here's a table describing each keyword accepted by the Script engine and its syntax.

startfunction

Type: keyword
Description: starts a QLC+ Function with the given ID
Syntax: startfunction:functionID
functionID is an integer number of the ID assigned by QLC+ to a Function.
Since IDs are not exposed to QLC+ users, in this case it is convenient to use the helper button on the rightmost side of the editor, which also add a comment with the Function name.
Eventually a user will learn the ID of a Function and therefore use it to manually add more code to the script.
Example:

startfunction:2 // Green scene

stopfunction

Type: keyword
Description: stops a running QLC+ Function with the given ID
Syntax: stopfunction:functionID
functionID is an integer number of the ID assigned by QLC+ to a Function. See startfunction description
Example:

stopfunction:0 // Blue scene

blackout

Type: keyword
Description: turns blackout on or off.
Syntax: blackout:on|off
functionID is an integer number of the ID assigned by QLC+ to a Function. See startfunction description.
Examples:

blackout:on
blackout:off

systemcommand

Type: keyword
Description: execute a program or a script at the provided absolute path with the (optional) provided arguments.
Syntax:systemcommand:programPath arg:arg1 arg:arg2 ... arg:argN
programPath is the absolute path of an executable program or script. For example /usr/bin/vlc or C:\\Tools\\myTool.exe
If the path to an executable contains spaces, it must be written between quotes.
_arg1 ... argN are the arguments to be used when executing programPath. If no arguments are needed, then the arg: keywords are not necessary.
If an argument contains spaces it must be written between quotes.
Examples:

systemcommand:/usr/bin/vlc arg:-f arg:/home/user/video.mp4 // plays my video with VLC in fullscreen
systemcommand:"C:\\Program Files\\Tools\\My Tool.exe" arg:"D:\\My Files\\My file.txt"

setfixture

Type: keyword
Description: sets a QLC+ Fixture channel to the provided DMX value.
Syntax: setfixture:fixtureID ch:channelIndex val:DMXValue
fixtureID is an integer number of the ID assigned by QLC+ to a Function.
Since IDs are not exposed to QLC+ users, in this case it is convenient to use the helper button on the rightmost side of the editor, which also add a comment with the fixture and channel name.
Eventually a user will learn the ID of a fixture and the index of a channel and therefore use them to manually add more code to the script.
channelIndex is an integer number representing the fixture channel number. Channels indices here start from 0.
DMXValue is the actual DMX value to be set to the specified fixture channel. It ranges from 0 to 255
Example:

setfixture:0 ch:1 val:135 // Generic RGB, Red. Sets the red channel of a Generic RGB fixture to DMX value 135

wait

Type: keyword
Description: wait for the provided amount of time before executing the next line of code.
Note that a wait time can be randomized too, following the random syntax described below.
Syntax: wait:time
time can be either an integer number of milliseconds or a string representing the wait time in the QLC+ way: **h**m**s.**
Examples:

wait:1800 // Waits for 1 second and 800 milliseconds
wait:03s.20 // Waits for 3 seconds and 200 milliseconds

waitfunctionstart

Type: keyword
Description: wait until a specified function starts running.
This command takes one argument, which is the ID of the function you want to wait for. Once the specified function starts running or if it is already running, the script will continue executing from the next line.
Syntax: waitfunctionstart:functionID
functionID is an integer number of the ID assigned by QLC+ to a Function. See startfunction description.
Examples:

waitfunctionstart:2 // Wait for green scene to start

waitfunctionstop

Type: keyword
Description: wait until a specified function stops running.
This command takes one argument, which is the ID of the function you want to wait for. Once the specified function stops running or if it is not already running, the script will continue executing from the next line.
Syntax: waitfunctionstart:functionID
functionID is an integer number of the ID assigned by QLC+ to a Function. See startfunction description.
Examples:

waitfunctionstop:0 // Wait for blue scene to stop

comments

Type: Helper macro
Description: comments can be inserted at any position in the script code and they do not affect the script execution. They are normally used to give a meaning to a line of code.
QLC+ Scripts comment follow the C Language style rule of the "//" syntax. Basically everything written after "//" will be considered a comment until the end of the line of code.
So pay a particular attention to not writing meaningful code after a "//" and expect it to be run, cause it won't.
Comments can be added at the end of a Script line of code or they can take a whole line, for example to describe an entire block of code.

random

Type: Helper macro
Description: generates a random integer number between the provided minimum and maximum values
Syntax: random(min,max)
min is the minimum value the randomization can reach. It can be either an integer number or a time string
max is the maximum value the randomization can reach. It can be either an integer number or a time string
Examples:

wait:random(02s.00,05s.00) // Waits a random time between 2 and 5 seconds 
// set channel 3 of fixture with ID:1 to a random DMX value between 20 and 235
setfixture:1 ch:2 val:random(20,235)

stoponexit

Type: keyword
Description: controls whether functions started during the script should be stopped at the end.
Syntax: stoponexit:[true|false]
true: all functions started afterward will be stopped when the script finishes (default behaviour).
false: all functions started afterward will continue running when the script finishes.
Example:
In this script example, functions 1 and 3 will be stopped at the end, but functions 2 and 4 will continue running.

startfunction:1 // default behaviour: funciton 1 will be stopped

stoponexit:false
startfunction:2 // function 2 will continue running

stoponexit:true
startfunction:3 // function 3 will be stopped

stoponexit:false
startfunction:4 // function 4 will continue running