Code Examples

The following is a simple script in which the input of the control that changed (changedControl) is passed to the output (Controls.Outputs[1]).

Copy 
-- first define a function (syntax: function name ( args ) body [return values] end)
 
function handler( changedControl )
 
-- set the first output (Controls.Outputs[1].Value) to value of first input (changedControl.Value)
-- Note: Arrays are 1 based in Lua.
 
Controls.Outputs[1].Value = changedControl.Value
end
 
-- now attach the handler
 
Controls.Inputs[1].EventHandler = handler;

Lua supports anonymous functions so you can define the function during assignment as follows:

Copy 
Controls.Inputs[1].EventHandler = function( changedControl ) Controls.Outputs[1].Value = changedControl.Value end

The signature of the Control value EventHandler takes the control that changed as an argument. Due to Lua's 'loose' typing, it is possible to remove that argument and just address the input directly.

Copy 
Controls.Inputs[1].EventHandler = function() Controls.Outputs[1].Value = Controls.Inputs[1].Value end
Copy 
if System.IsEmulating then
Controls.Outputs[1].Color = "Green"
else
Controls.Outputs[1].Color = "Red"
end
Copy 
-- first define a function
 
function handler( changedControl )
 
-- set first output to 1/2 the value of first input
-- Note: Arrays are 1 based in Lua.
 
Controls.Outputs[1].Value = changedControl.Value / 2
end
 
-- now attach the handler
 
Controls.Inputs[1].EventHandler = handler;
Copy 
--To access the vector output of a meter. 
 
t = Controls.Inputs[1].Values
print( t[1]..","..t[2]..","..t[3]..","..t[4] )

If you have multiple inputs and want to run the same script if any of the inputs change, the easiest way to accomplish this would be to iterate all the inputs.

Copy 
-- helper function which returns sum and count
-- Note: Lua functions can return multiple values
 
function SumAndCount()
sum = 0
count = 0
for i,v in ipairs(Controls.Inputs) do
sum = sum + v.Position
count = count + 1
end
return sum, count
end
 
-- average all inputs
 
function avr()
s, c = SumAndCount()
Controls.Outputs[1].Position = s/c
end
 
-- iterate all inputs and set up the event handler
 
for i,v in ipairs(Controls.Inputs) do
v.EventHandler = avr
end

You can also ramp control values or positions via script. RampTime is specified in seconds.

Copy 
Controls.Outputs[1].RampTime = 3
Controls.Inputs[1].EventHandler = function()
Controls.Outputs[1].Value = 0
end

When controls have metadata attached to them, you can do the following:

  • set a control to visible or invisible,
  • set a control to enabled or disabled,
  • specify its choices, and
  • set its color.

Metadata is used on some built-in controls - for example, the High-Pass Filter uses metadata to disable the Q control when the filter type is not set to Variable Q. The controls in the Custom Controls component have metadata turned on by default. Attempting to access metadata on a control which does not have metadata will result in an error.

Color metadata is in the form of a string. Q-SYS uses the built in .NET string->color converter which allows for strings in the form "#RGB", "#RRGGBB", CSS Color Names, and HSV values using the format "!HHSSVV".

You cannot attach a handler to a named control.

The following code toggles visibility, color, disablement and choices metadata:

Copy 
toggle = 0
colorize = 1
colors = {
"#F00", "#E00", "#D00", "#C00", "#B00", "#A00", "#900",
"#800", "#700", "#600", "#500", "#400", "#300", "#200", "#100"
}
 
function timerFunc()
if toggle == 0 then
toggle = 1
else
toggle = 0
end
Controls.Outputs[1].IsInvisible = toggle
Controls.Outputs[2].IsDisabled = toggle
Controls.Outputs[4].Color = colors[colorIndex]
colorIndex = colorIndex + 1
if colorIndex == #colors then colorIndex = 1 end
end
 
Controls.Outputs[5].Choices = { "this", "is", "a", "test" }
 
Timer1 = Timer.New()
Timer1.EventHandler = timerFunc
Timer1:Start(.2)
 

Each Control Script has a timer available. It has a Tick event that a TickHandler can be attached to. You can start or stop the timer. The Timer TickHandler signature looks like:

Copy 
void tickHandler()
 
-- example of using built in script timer
 
function timer_func()
-- each timer tick increments the first outputs position
-- if the position is greater than 1.0 reset it to 0.0
Controls.Outputs[1].Position = cur_pos
cur_pos = cur_pos + 0.1
if cur_pos > 1.0 then
cur_pos = 0
end
end
--initialize the variable
cur_pos = math.floor(Controls.Outputs[1].Position)
 
-- add the timer
Timer1 = Timer.New()
Timer1.EventHandler = timer_func
 
-- and start it with a delay of 500 ms
Timer1:Start(.500)

The following is a sample script to encode icons to a button. The codes for each icon can be found in C:\Program Files\QSC\Q-SYS Designer\lua\icons.lua.

Copy 
local json = require("rapidjson")
btn.EventHandler = function()
if btn.Boolean then
btn.Style = json.encode{IconString = string.char(0xef,0x88,0x90)}
else btn.Style = json.encode{IconString = string.char(0xef,0x88,0x91)}
end
end