Text Controller

1. In your schematic, double-click the Text Controller component to open the elements editor.
2. In the Controls section, click to add a new control.
3. In the Properties section, configure the new control. See Properties.
4. Click Edit to open the Lua text editor.
5. Write Lua code for your defined controls. Click Save changes (yellow bar) to save your script.
6. Run (F5) or emulate (F6) your design to start the script.

To see an example configuration, see Example.

Double-click the Text controller component to open the elements editor, which is where you define controls for your Lua script. After defining controls, click Edit to open the Lua text editor.

Controls

Control	Function
Controls	Click to add a new control to the list, and then configure its properties. Click and drag the icon to re-order the list of controls. Select one or more control icons and drag or copy/paste them into your schematic or user control interface. (Use the Ctrl key to select multiple controls.)
Serial Port Inputs	Specify how many serial port input pins to expose, 0 - 128.

Properties

Property	Function	Choices
General
Name	Specify a name for the input.	Text input
Count	Specify the number of controls of the specified type to create.	1 to 256
Control Type
Category	Button Select a Push Action: Momentary – When the button is clicked, it stays in its opposite state until released. Toggle – Allows you to turn the button on or off. Trigger – Sends a single pulse. Knob Specify a Max Value and Min Value for the specified Units:dB, Hz, Float, Integer, Pan, Percent, Position, Seconds. Indicator Specify a Type: LED, Meter, Text, Status. Text Specify a Type: Text Box, Combo Box, List Box	Button, Knob, Indicator, Text
Control Pin	Expose pins for these controls: None, Input (pins on the left), Output (pins on the right), or Both.	None, Input, Output, Both

The script editor contains these areas:

• Text editor – Write script for your configuration. You can edit the script in the Design, Emulate, or Run modes, but any errors are only detected in the Run or Emulate modes.

Tip: While in the Script area, press F1 for help on the Lua scripting language.

• Script menu – Click to start or stop the script.
• Information bar at the top of the script – Click the yellow "Save changes" bar to reload (not run) the script. Syntax errors are indicated in a red bar at top-right, as well as in the Debug Output area.
• Debug Output – Displays error messages from the Lua engine describing errors in the script, as well as any "print" output. The output is limited to 16 lines.
• Search bar – Click the Search bar on the right side of the page to locate or replace text in your script.

Rules for Referencing Control Names in Script

• Control names that contain no spaces can be referenced with dotted notation. Examples: 'Button' could be referenced 'Controls.Button.Boolean'; Names with spaces: 'Big Button' = 'Controls["Big Button"].Boolean'
• For a single control (Count = 1), you can directly access the control. Example: 'MyKnob' = 'Controls.MyKnob.Value'
• If at least two controls are defined in a row (Count = 2+), you must access the controls as an array. Example: 'MyKnobs' x 3 = 'Controls.MyKnobs[1].Value', 'Controls.MyKnobs[2].Value', 'Controls.MyKnob[3].Value'
• If at least two controls are defined in a row (Count = 2+) and spaces are used in the control name, quotes must be used around the control name. Example: 'My Knobs' x 2 = 'Controls["My Knobs"][1].Value', 'Controls["My Knobs"][2].Value'

Script Errors

In the script, if you reference an input or output that has nothing connected to it, the following error message appears: [string "cin_speaker = Controls.Inputs[1]..."]:43: attempt to index global 'cin_ramptime' (a nil value). In most cases, the error messages are more understandable than this one.

The available Control Pins depend on settings in Properties.

Pin Name	Value	String	Position	Pins Available
Code	(text)			Input / Output
Script Start	(trigger)			Input / Output
Script Status	(text)			Output
Script Stop	(trigger)			Input / Output

In this simple example, Text Controller is configured with a control button that can be used to retrieve a list of control names from any named component in the design.

Naming components

This example contains two audio components - Gain and Delay. Rename each with a custom name ("MyGain", "MyDelay"). Renaming the components with custom names allows the Named Components function to retrieve a table of control names for those components. For more information about named components in Lua, see Named Components.

Defining controls

Drag Text Controller onto the canvas and double-click it to open the elements editor. Add three controls with these names and properties:

• Get Controls – A trigger button that retrieves a table of control names for the specified component custom name. (Category = Button; Push Action = Trigger)
• Component Name – A text box for entering the custom name of a component. (Category = Text; Type = Text Box)
• Output – A text box to contain the returned table of control names. (Category = Text; Type = Text Box)

Adding Lua script

Click Edit to open the Lua text editor. Add the following script, and then click Save changes.

Controls["Component Name"].EventHandler = function(ctl)
comp = Component.New(ctl.String)
end

-- Returns all controls of the component in "Component Name"

Controls["Get Controls"].EventHandler = function()
local str = " Get Controls for "..Controls["Component Name"].String.."\r"
for k,v in pairs(comp) do
str = str..k.."\r"
end
Controls.Output.String = str
end

comp = Component.New(Controls["Component Name"].String)

Running the script

1. Emulate (F6) or run (F5) the design to start the script.
2. Click the schematic page tab ("Page 1" if you didn't rename it).
3. In the Component Name text box, type the name of one of the custom control names - MyGain - and then press Enter.
4. Click Get Controls.
5. The Output text box shows the list of controls for that component name. Repeat the process for MyDelay to see how the output changes.

• Refer to Q-SYS Control Scripting and the Lua 5.3 Reference Manual for information about writing scripts.
• Q-SYS Training - Control 101

  Learn the basic Q-SYS third party control principles, including Lua scripting basics.