1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Q Light Controller Plus - Script Editor</TITLE>
<SCRIPT SRC="utility.js" TYPE="text/javascript"></SCRIPT>
<link href="style.css" rel="stylesheet" type="text/css" />
</HEAD>
<BODY onLoad="replaceqrc()">
<H1>Script Editor</H1>
<P>
The Script Editor, as its name suggests, is used to edit
<IMG SRC="qrc:/script.png" align="absmiddle"> <A HREF="concept.html#Script">Script</A> functions.<br>
It basically consists in a text editor where the user can write a script using a meta-language with
a syntax described below.<br>
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.<br>
Each line of a script will be executed by QLC+ in a sequential order.
</P>
<H3>Controls</H3>
<TABLE BORDER=1 class="qlcTable">
<TR>
<TD>
<img src="qrc:/player_play.png" />
</TD>
<TD>
Enable the output and run the Script to test its execution
</TD>
</TR>
<TR>
<TD>
<B>Script name</B>
</TD>
<TD>
Change the name of the Script.
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/edit_add.png">
</TD>
<TD>
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.
<UL>
<LI><IMG SRC="qrc:/function.png" width=24 align="absmiddle"> <B>Start Function</B>: Opens the
<A HREF="selectfunction.html">Functon Selection</A> dialog to select a Function to be started.<br>
This operation will automatically add a comment at the end of the line of code, with the
QLC+ name of the selected Function.
</LI>
<LI><IMG SRC="qrc:/fileclose.png" width=24 align="absmiddle"> <B>Stop Function</B>: Opens the
<A HREF="selectfunction.html">Functon Selection</A> 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.<br>
This operation will automatically add a comment at the end of the line of code, with the
QLC+ name of the selected Function.
</LI>
<LI><IMG SRC="qrc:/blackout.png" width=24 align="absmiddle"> <B>Blackout</B>: Opens dialog
requesting whether blackout should be turned on or off.
</LI>
<LI><IMG SRC="qrc:/fixture.png" width=24 align="absmiddle"> <B>Set Fixture</B>: 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 opration will be 0 and has
to be changed manually with the script text editor.<br>
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.
</LI>
<LI><IMG SRC="qrc:/player_play.png" width=24 align="absmiddle"> <B>System Command</B>: 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.
</LI>
<LI><IMG SRC="qrc:/speed.png" width=24 align="absmiddle"> <B>Wait</B>: Opens a dialog requesting
the time to be waited before the script can execute the next instruction
</LI>
<LI><IMG SRC="qrc:/label.png" width=24 align="absmiddle"> <B>Comment</B>: Opens a dialog requesting
the text of the comment to insert at the cursor position in the editor.<br>
A comment has a C language style appearance: it starts with "//" and everything until the end
of the line is then considered a comment
</LI>
<LI><IMG SRC="qrc:/other.png" width=24 align="absmiddle"> <B>Random Number</B>: 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.<br>
This can be useful to randomize DMX values set through the setfixture keyword. See below.
</LI>
<LI><IMG SRC="qrc:/fileopen.png" width=24 align="absmiddle"> <B>File Path</B>: Open a file dialog
to select a file. The absolute path and the file name will be insterted at the editor current position.<br>
If a path contains spaces, it will be written within quotes
</LI>
</UL>
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/editcut.png">
</TD>
<TD>
Cut the currently selected text in the editor for a later paste
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/editcopy.png">
</TD>
<TD>
Copy the currently selected text in the editor for a later paste
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/editpaste.png">
</TD>
<TD>
Paste a previously cut or copied text at cursor position in the editor
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/undo.png">
</TD>
<TD>
Undo the last performed operation on the editor
</TD>
</TR>
<TR>
<TD>
<IMG SRC="qrc:/check.png">
</TD>
<TD>
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.
</TD>
</TR>
</TABLE>
<H3>Language syntax</H3>
<P>
The QLC+ Script meta-language is based on a <B>keyword:value</B> model, with some insertions of
C language syntax rules.<br>
Each line of code is parsed by the QLC+ engine and verified to detect the presence of
syntax errors.<br>
Here's a table describing each keyword accepted by the Script engine and its syntax.
</P>
<TABLE BORDER=1 class="qlcTable">
<TR>
<TD>startfunction</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: starts a QLC+ Function with the given ID.<br>
<B>Syntax</B>: startfunction:functionID<br><br>
<I>functionID</I> 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.<br>
Eventually a user will learn the ID of a Function and therefore use it to manually add more code
to the script.<br>
<B>Example</B>: <PRE>startfunction:2 // Green scene</PRE>
</TD>
</TR>
<TR>
<TD>stopfunction</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: stops a running QLC+ Function with the given ID.<br>
<B>Syntax</B>: stopfunction:functionID<br><br>
<I>functionID</I> is an integer number of the ID assigned by QLC+ to a Function. See <I>startfunction</I>
description.<br>
<B>Example</B>: <PRE>stopfunction:0 // Blue scene</PRE>
</TD>
</TR>
<TR>
<TD>blackout</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: turns blackout on or off.<br>
<B>Syntax</B>: blackout:on|off<br><br>
<I>functionID</I> is an integer number of the ID assigned by QLC+ to a Function. See <I>startfunction</I>
description.<br>
<B>Examples</B>:
<PRE>blackout:on
blackout:off</PRE>
</TD>
</TR>
<TR>
<TD>systemcommand</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: execute a program or a script at the provided absolute path with the (optional) provided arguments.<br>
<B>Syntax</B>: systemcommand:programPath arg:arg1 arg:arg2 ... arg:argN<br><br>
<I>programPath</I> is the absolute path of an executable program or script. For example "/usr/bin/vlc" or "C:\Tools\myTool.exe"<br>
If the path to an executable contains spaces, it must be written between quotes.<br>
<I>arg1 ... argN</I> are the arguments to be used when executing <I>programPath</I>. If no arguments are
needed, then the arg: keywords are not necessary.<br>
If an argument contans spaces it must be written between quotes.<br>
<B>Examples</B>:
<PRE>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"</PRE>
</TD>
</TR>
<TR>
<TD>setfixture</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: sets a QLC+ Fixture channel to the provided DMX value.<br>
<B>Syntax</B>: setfixture:fixtureID ch:channelIndex val:DMXValue<br><br>
<I>fixtureID</I> 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.<br>
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.<br>
<I>channelIndex</I> is an integer number representing the fixture channel number. Channels indices here start from 0.<br>
<I>DMXValue</I> is the actual DMX value to be set to the specified fixture channel. It ranges from 0 to 255<br>
<B>Example</B>: <PRE>setfixture:0 ch:1 val:135 // Generic RGB, Red. Sets the red channel of a Generic RGB fixture to DMX value 135</PRE>
</TD>
</TR>
<TR>
<TD>wait</TD>
<TD>
<B>Type</B>: keyword<br>
<B>Description</B>: wait for the provided amount of time before executing the next line of code.<br>
Note that a wait time can be randomized too, following the <i>random</i> syntax described below.<br>
<B>Syntax</B>: wait:time<br><br>
<I>time</I> can be either an integer number of milliseconds or a string
representing the wait time in the QLC+ way: **h**m**s.**<br>
<B>Examples</B>:
<PRE>wait:1800 // Waits for 1 second and 800 milliseconds
wait:03s.20 // Waits for 3 seconds and 200 milliseconds</PRE>
</TD>
</TR>
<TR>
<TD>comments</TD>
<TD>
<B>Type</B>: Helper macro<br>
<B>Description</B>: 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.<br>
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.<br>
So pay a particular attention to not writing meaningful code after a "//" and expect it to be
run, cause it won't.<br>
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.
</TD>
</TR>
<TR>
<TD>random</TD>
<TD>
<B>Type</B>: Helper macro<br>
<B>Description</B>: generates a random integer number between the provided minimum and maximum values<br>
<B>Syntax</B>: random(min,max)<br><br>
<I>min</I> is the minimum value the randomization can reach. It can be either an integer number or a time string<br>
<I>max</I> is the maximum value the randomization can reach. It can be either an integer number or a time string<br>
<B>Examples</B>:
<PRE>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)</PRE>
</TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
