Named Components

Using the Control Tree, there’s actually a third way we can manipulate controls within our script.

With the Control Script you needed to wire an outside control into your script’s control pins,

and with Scriptable Controls you can reference a native control built into that component, but you could also make use of Named Components.

A Named Component is exactly what it sounds like: a component that you’ve given a custom name. For instance, I’ll drag this Gain block into the design, and let’s look at its properties.

One of its properties is called “Label,” which is just the friendly name displayed on the component in the schematic.

But there’s another property called “Code Name.” I’ll give my Gain component a sneaky code name like . . . “RobinHood.”

This is quite different than changing its label, because under the hood, this is assigning a Lua table to my component.

The component is still visually labeled “Gain,” but if I hover my mouse over it I can confirm its secret code name of RobinHood.

Using this Code Name, you can actually target your component’s controls from any Lua script, without needing to wire the control to that script.

For instance, if you open up a Block Controller, you’ll see a branch for your Named Components on the left for every component that is accessible by a Code Name.

This way, I might use a Trigger button here in the Block Controller to change the Named Component’s gain knob to -40dB.

Now when I tap the Trigger button, you can see that the Named Component was successfully changed.

For those of you prefer Lua, let’s open up a Control Script and target the component from there as well.

The syntax looks like this: Component.New, then in parentheses you’ll need to provide the Code Name of the Named Component.

Since this text is a string, you’ll need to put quotes around it.

Next you’ll need to open up some brackets to specify the name of the control within that component that you want to target, which once again, must be enclosed in quotes.

If you’re not sure what the names of the controls inside the component are, you can select the Component and go to the Tools menu, and select “View Component Controls Info.”

This will display the Lua name for each control on the left, as well as a friendly name for it and what type of control it is on the right.

Now that you’ve successfully referenced the control itself, you can then continue the Control Tree to select one of its properties.

For instance, I’ll change the .Value of Robin Hood’s Mute control. And when I run the script, you can see that it worked.

Personally, I would recommend using a variable to represent this control.

This is an ugly piece of code – Component.New-parentheses quotes, brackets quotes – let’s just define variable MrGain as that whole thing.

Now I can reference that control just by using MrGain.Value or MrGain.String, which is a lot easier to look at, and should feel more like the other control tree activities you’ve seen so far.

Named Components are a powerful way to give your scripts access to your controls without using wires or Scriptable Controls.

It also means that any number of different Lua scripts can reference that same control.

Basically, this lets you reference something specific that’s not in your script.

For example, if I were to mention that I’m also a novelist and I wrote a book about Robin Hood, that would be a weirdly specific reference that’s definitely not in the script.

You can find my book at...

Well, Nate's fired... so...

As I was saying, Named Components are an important tool in your scripting database. You should also be aware of the “Script Access” property.

You might have noticed that when you change the component’s Code Name, the “Script Access” property also changed from “None” to “All.”

By default your components start in the safest mode of not allowing any external access,

but Q-SYS is assuming that if you’re giving this component a Code Name, you want it to be controllable.

You could also customize this field to “Script,” which only allows internal scripts to access your component, or “External,” which only allows external devices to do so.

Finally, there’s another option available under the Tools menu called “Script Programmer Mode.”

When this mode is engaged, the Label and the Code Name for each of these components are visually reversed, so you can see each component’s Code Name displayed prominently,

and its Label will only be visible when you hover your mouse over the component.

In this mode, renaming the component here in the Schematic will update its Code Name rather than its Label, so be sure to keep track of which mode you’re in.

You’ll also notice that every component displays a small colored square indicating its Script Access property: red for All, amber for External, yellow for Scripts, and grey for None.

Well, that’s it for Named Components, and for Nate. There’s an exercise to complete in the Control Worksheet, and then move on whenever you’re ready.