Code Examples

Passing an Input to the Output

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

-- 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;

Define the Function During Assignment

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

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

Address the Input Directly

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.

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

Determine System Mode - Emulate or Not

if System.IsEmulating then

Controls.Outputs[1].Color = "Green"

else

Controls.Outputs[1].Color = "Red"

end

Performing Math

-- 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;

Vector Value Controls

--To access the vector output of a meter.

t = Controls.Inputs[1].Values

print( t[1]..","..t[2]..","..t[3]..","..t[4] )

Multiple Inputs

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.

-- 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

Ramp or Position Controls

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

Controls.Outputs[1].RampTime = 3

Controls.Inputs[1].EventHandler = function()

Controls.Outputs[1].Value = 0

end

Metadata

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".

Legend Metadata

You cannot attach a handler to a named control.

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

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)

NamedControl

NamedControl.SetString( "ControlName", String )

NamedControl.SetPosition( "ControlName", Position )

NamedControl.SetValue( "ControlName", Value )

NamedControl.Trigger( "ControlName" )

NamedControl.GetString( "ControlName" )

NamedControl.GetPosition( "ControlName" )

NamedControl.GetValue( "ControlName" )

Timer

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:

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

--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)