Text Controller

Use the Text Controller component to easily declare one or more custom controls and then build the Lua script associated with those controls using a Lua text editor.

Note: This component uses the Q-SYS Scripting Engine, which is a licensed feature on certain Cores manufactured with Q-SYS 7.0 and later. For more information, see Licensing.

  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 Text Controller.
  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.
  7. You can add Panels to a Text Controller, by clicking on the at the top of the Controller window. After a panel is added, you can name the panels by double-clicking on Panel 1-n. The same capabilities exist for a panel that exist for the schematic page with the exception of wiring.

Note: If there are no Panels, then the "Controls" tab is shown.

To see an example configuration, see Example.

Inputs and Outputs

Control components do not have traditional input and output pins. If a Control Pin is available for the component, an input or output will appear.

Control Pins represent the controls available in the component's Control Panel. Control Pins are used to link controls between Schematic Elements, and link to / from Control Scripts. Control Pin signal pins are represented by a square, and the wiring is represented by a thick blue / white line.

Text Controller Properties

User Panel Lock

When the property is set to no (Default), a Panel can be deleted by clicking on the X in the Panel tab.

When the property is set to yes, A lock icon appears on the Panel tab preventing any changes within or the option to delete the active Panel.

Display User Panel

Note: If there are no Panels, then the "Controls" tab is shown.

The dropdown will provide Panel 1-n, depending on how many you have set up. Whichever Panel you choose in this dropdown will be displayed by default when opening the Text Controller.

Start Automatically

When the property is set to no, the script will not start when entering emulation or loading a design to a core.

When the property is set to yes (Default), the script will start when entering emulation mode or when loading a design to a core.

Graphic Properties

Label

Use the Label property to change the name of the component in the schematic. The Label property defaults to the component name. To learn more about renaming schematic elements, see Organizing Your Design.

Position

The coordinates reference a specific place in the schematic - for example,"100,100" (horizontal, vertical). 0,0 is the upper left corner of the schematic.

Fill

Sets the fill color of the component in the schematic.

Script Access Properties

Code Name

Displays the currently assign name for control access. You can use the auto-assigned name or customize it. Q-SYS will automatically check all Code Names in the design to ensure name is unique.

Script Access

Defines whether the component will be accessible by script and/or externally, or not at all. Choices include All, External, None (default), and Script.

Tip: Use Script Programmer Mode to quickly view the Script Access setting directly on the component in the design schematic without the need to disconnect from the Q-SYS Core processor.

Is Managed

For QSC-authored plugins only, select 'Yes' to add the plugin to your Inventory list, which makes the plugin's Status available for monitoring in Core Manager and Enterprise Manager. When enabled, you can then specify a Name and Location for the plugin, as with any other Inventory item. Enabling the Is Managed property also reveals the Is Required property, if applicable to the plugin.

Start Automatically

When the property is set to no, the script will not start when entering emulation or loading a design to a core.

When the property is set to yes (Default), the script will start when entering emulation mode or when loading a design to a core.

External Prefix

Allows you to specify a prefix that is added to external control strings sent or received by the scripting component. This can be useful in scenarios where you want to distinguish or differentiate external control commands or data associated with a particular scripting component from others in your Q-SYS design.

External Prefix Mode

Allows you to specify how the scripting component interprets incoming messages. When you enable this mode, the scripting component treats messages with a specific prefix as external control messages, meaning they are processed differently from internal scripting messages. You can choose either Native which uses Lua Scripting or JavaScript.

Graphic Properties

Label

Use the Label property to change the name of the component in the schematic. The Label property defaults to the component name. To learn more about renaming schematic elements, see Organizing Your Design.

Position

The coordinates reference a specific place in the schematic - for example,"100,100" (horizontal, vertical). 0,0 is the upper left corner of the schematic.

Fill

Sets the fill color of the component in the schematic.

Script Access Properties

Code Name

Displays the currently assign name for control access. You can use the auto-assigned name or customize it. Q-SYS will automatically check all Code Names in the design to ensure name is unique.

Script Access

Defines whether the component will be accessible by script and/or externally, or not at all. Choices include All, External, None (default), and Script.

Tip: Use Script Programmer Mode to quickly view the Script Access setting directly on the component in the design schematic without the need to disconnect from the Q-SYS Core processor.

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

  • 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, from 0 to 128. Use these pins with the SerialPorts Lua library.

Virtual Serial Port Outputs

Specify how many virtual serial port output pins to expose, from 0 to 128. Use these pins with the SerialServerPorts Lua library.

General Properties

Name

Specify a name for the input.

Count

Specify the number of controls of the specified type to create.

Control Type

Category

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 command.
  • State Trigger: Sends a command when conditions are met. See the State Trigger topic.

Specify a Max Value and Min Value for the specified Units:

  • dB: -100 to 20
  • Hz: 10 to 20000
  • Float: (No limit)
  • Integer: -999999999 to 99999999
  • Pan: -1 to 1

    Note: The Pan range is ignored when setting the Pan value. When setting a pan control value in the Block Controller control panel, the valid range is L100 to 0 (or C) to R100. In the Blocks Editor, the valid range is -1 to 1, where -1 is the equivalent of 'L100', 0 is the equivalent of 'C', and 1 is the equivalent of 'R100'. For example, a value of -0.5 is L50, and a value of 0.5 is R50.

  • Percent: 0 to 100
  • Position: 0 to 1
  • Seconds: (No limit)

Specify a Type: LED, Meter, Text, Status.

Specify a Type: Text Box, Combo Box, List Box

Control Pin

Expose pins for these controls: None, Input (pins on the left), Output (pins on the right), or Both.

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

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.
  • 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.
  • Search bar – Click the Search bar on the right side of the page to locate or replace text in your script. As a shortcut, press F3 to find the next item.

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'

See Debug Output.

The available Control Pins depend on settings in Properties.

Pin Name

Value

String

Position

Pins Available

Code

(text)

Allows you to enter code.

Input / Output

Script Start

(trigger)

Starts the script running.

Input / Output

Script Status

(text)

Current status of the script.

Output

Script Stop

(trigger)

Stops the script.

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

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.

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

Using Components with Snapshot Controller Ramp Time

Components such as the Crossover Component or other Text Controller or Custom Controls like the Integer Knobs, and Hexadecimal Knobs will not be recalled by Snapshot if the Ramp Time is a non-zero number.