This repository has been archived by the owner on Aug 20, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 4
/
# DOCUMENTATION.txt
251 lines (223 loc) · 9.65 KB
/
# DOCUMENTATION.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
Q-SYS Plugin "Documentation"
File Extensions Note: Plugins can have either .lua* or .qplug as a file extension and will be recognized. The reason for the * after .lua is that adding extra characters
after .lua won't hide the file from Q-SYS. To Q-SYS, 'example.lua' is just as visible as 'example.luaold'. Using something like 'example.lua.old' will result in hiding
the file from Q-SYS.
PLUGIN FILE SECTIONS-----
PluginInfo section:
PluginInfo =
{
Name = "Plugin Name", <-- Name that will appear in the Schematic Library (putting ~ inbetween words makes second word the name in a folder called by the first word
Version = "1.0", <-- A version number string. Changing later will allow users to upgrade.
Id = "0c02812a-8c75-4867-af91-06c11ee59bce", <-- A unique hyphenated GUID (guidgenerator.com)
Description = "What does this version do?", <-- this message is seen when a version mismatch occurs
ShowDebug = false <-- setting this to true will reveal the Lua debug window at the bottom of the UI
}
To change block color:
(shown with color determined by a property. can just use 'return { R, G, B }' instead)
function GetColor(props)
if props["Input Count"].Value > 4 then
return { 255, 0, 0 }
else return { 0, 255, 0 } end
end
function GetPrettyName(props)
return "The best litle Plugin in Texas" <-- to define a longer component name than the library name
end
function GetProperties()
-- return an ordered list of property parameter lists
return
{
{
Name = "Pick a number",
Type = "integer",
Min = 1,
Max = 100,
Value = 1
},
{
Name = "Best Way to Go",
Type = "enum",
Choices = { "This way", "That way" }, <-- if you want blank by default, place "" as the first list item and Value below.
Value = "This way", <-- must match one of the Choices exactly
},
}
Each property can have:
- Name = string (text displayed next to property and referred to as 'props["<property_name>"].Value' in the code)
- Type = string, integer, double, boolean, enum (boolean will give Yes or No choice, but true/false in the code)
- Value = default value for property (in correct type for property)
- for 'enum' type:
Choices = { list of choice strings } for ComboBox
- for integer or double types:
Min = lowest extent
Max = highest extent
end
function RectifyProperties(props) <-- Used to hide properties that aren't needed based on other property settings
props["Number of PINs"].IsHidden = props["Use PIN"].Value == "No" <-- .IsHidden will hide a property line if set to "Yes"
return props
end
function GetControls(props) <--
- Return a list of controls needed on UI of Plugin
return {
{
Name = "Input Gain", <-- Name used for control, on pins and via Lua Scripts and QRC
ControlType = "Knob", <-- Can be Button, Knob, Indicator or Text
ControlUnit = "dB", <-- ControlUnit ( ControlType == Knob ) can be Hz, Float, Integer, Pan, Percent, Position or Seconds
Min = -6, <-- for knob type
Max = 6, <-- for knob type
Count = 10, <-- number of controls to create (can be calculated based on properties, etc.)
},
{
Name = "Mute",
ControlType = "Button",
ButtonType = "Toggle", <-- ButtonType ( ControlType == Button ) can be Momentary, Toggle or Trigger
Count = 1,
UserPin = boolean (4.2+; false is default. If true, pin will be available in Control Pins area)
PinStyle = "Input", <-- PinStyle can be "Input", "Output", "Both"
},
{
Name = propName.." "..CardToControl[model],
ControlType = "Indicator",
PinStyle = "Output",
IndicatorType = "Led", <-- IndicatorType ( ControlType == Indicator ) can be Led, Meter, Text or Status
Count = 8,
},
}
end
GetControlLayout function:
- Make a local control layout table containing a list specifying details for each control defined in GetControls
layout = {}
layout["Status"] =
{
Style = "Text",
Position = { 114, 31 },
Size = { 217, 19 },
IsReadOnly = true
}
Options:
Position = { x, y }
Size = { h, w }
Color = { r, g, b }
UnlinkOffColor = a boolean
OffColor = { r, g, b }
PrettyName = a string which is displayed to user, but different to what is used in the code
Style = "Fader"/"Knob"/"Button"/"Text"/"Meter"/"Led"/"ListBox"/"ComboBox"
ButtonStyle = "Toggle"/"Momentary"/"Trigger"/"On"/"Off"/"Custom" <-- custom is for a String type button
CustomButtonUp = a string <-- Custom Button only
CustomButtonDown = a string <-- Custom Button only
MeterStyle = "Level"/"Reduction"/"Gain"/"Standard" <-- Meter style only
HTextAlign = "Center"/"Left"/"Right"
VTextAlign = Center, Top, Bottom
TextBoxStyle = "Normal"/"Meter"/"NoBackground"
Legend = a string <-- for buttons (can be changed with runtime Lua)
WordWrap = a boolean
IsBold = a boolean
ShowTextbox = a boolean <-- for meters, faders and knobs
TextFontSize = a number
Margin = a number
Radius = a number
IsReadOnly = a boolean <-- not able to be changed at runtime--good for status readouts; not necessary for indicators
- Still inside the GetControlLayout function, make a local graphics layout table containing a list specifying details for each raphic element needed in the Plugin
- Z-Order is determined by the order graphics are defined (lower to upper; upper covers lower)
graphics = {
{
Type = "GroupBox",
Text = "Status",
HTextAlign = "Left",
StrokeWidth = 1,
CornerRadius = 8,
Fill = { 215, 215, 235 },
Position = { 0, 0 },
Size = { 345, 126 }
}, <-- comma because the next graphic element is another table (in Lua, even the last item can have a trailing comma
Options:
Position = { 20, 30 }
Size = { 64, 64 }
Type = "Label"/"GroupBox"/"Header"/"MeterLegend"
Text = a string
TextSize = a number
HTextAlign = "Center"/"Left"/"Right"
VTextAlign = "Center"/"Top"/"Bottom"
IsBold = a boolean
Color = { r, g, b }
TextColor = { r, g, b } <-- For "Label" type, use 'Color' to set the text color
StrokeColor = { r, g, b } <-- color of the outline (GroupBox and Label only)
Fill = { r, g, b } <-- color inside the outline (GroupBox only)
StrokeWidth = a number
CornerRadius = a number
return layout, graphics
end
function GetPins(props) <-- define Plugin pins that AREN'T tied to UI controls (internal components)
-- The order the pins are defined determines their onscreen order
-- This section is optional. If you don't need pins to internal components, you can omit the function
local pins = {}
table.insert(pins,
{
Name = "Audio Input",
Direction = "input",
})
table.insert(pins,
{
Name = "Audio Output",
Direction = "output",
})
table.insert(pins,
{
Name = "Serial",
Direction = "input",
Domain = "serial" <-- to add serial pins. Not needed for audio pins.
})
return pins
end
function GetComponents(props)
-- This section is optional. If you don't need any internal components, you can omit the function
return
{
{
Name = "main_mixer", <-- Name which your runtime Lua code will reference this component
Type = "mixer", <-- Type is the type obtained from the Named Components Lister
Properties =
{
["n_inputs"] = 8, <-- define any non-default properties the component must use (Named Component Lister)
["n_outputs"] = 1,
}
}
}
end
function GetWiring(props)
-- This section is optional. If you have any internal components or non-control pins, you can omit the function
-- Wiring to multiple internal components or pins: place all pins into one longer wiring definition statement
local wiring = {}
for i = 1,8 do
table.insert( wiring, { string.format("Input %i", i), string.format("main_mixer Input %i", i) } )
end
table.insert( wiring, { "Mix Output", "main_mixer Output 1" } )
return wiring
end
if controls then
-- Your runtime Lua code goes here.
-- All Q-Sys Lua libraries and functions and are available within the Plugin environment.
-- Access Plugin controls with "Controls." as you would in a Scriptable Control
-- You may access variables and functions outside of this if statement if necessary.
-- ...No need to make copies to place within this if statement to access them.
end
-- This is the end of the Plugin file
Tips
Tip 1:
If you have multiple identical components named with ascending numbers, to access those components from the runtime Lua code, you must refer to them using the Global Lua variable _G and their name:
example: If you defined a mixer component in a loop and appended numbers to the names to keep them unique...
mixer1 = _G["mixer_1"]
print(mixer1["output.1.gain"]
or
mixer1gain = _G["mixer_1"]["output.1.gain"]
print(mixer1gain)
HINT: Basically, you can just pre-pend the _G to the usual way to address Named Components
Tip 2:
Components within Plugins only have accessability from the Lua script within the Plugin. This means that you can reuse an internal component name in another Plugin within the same file or have multiple copies of the same Plugin within a file without conflict and because of the embarassment that would cause.
Tip 3:
- To access Plugin property values table from within the runtime Lua code, use the 'Properties' table constant
- Each property name has .Name (itself), Value (what it is currently set to), Type (string, integer, double, bool, enum) and for integer type, Min and Max.
- To access the value of the value of any property, use dot notation (example of an enum property called "Model"):
if Properties.Model.Value == "Tesla Model S" then
print("Awesome!")
elseif Properties.Model.Value == "Geo Metro" then
print("Awww!")
end