Once you understand where a variable is visible, using one is the same everywhere in Buttons: browse for it, insert it, and optionally transform it with an expression.
Select the button or section that should hold the variable.
In the inspector, open its Variables tab.
Select + next to Self to add a variable that only this element can see, or next to Parent to add one to the section this element sits in, shared by everything directly inside that section. The Parent heading names that section.
In Add Variable, enter a Name, an optional Description, and a Type, then select Create.
Enter an Initial value for the new variable, then select Apply.
Each variable shows the reference to use it by, such as $(self.state.camera), next to its name.
Open the position's Configuration tab and find Position Variables, or open any element's Variables tab and use its Position group.
Select +.
Enter a Name and an optional Description, and choose a Type: Boolean, Connection, Feedback, Number, Routing Endpoint, or String. For Connection, also choose the Connection Type (Module) the variable may point to.
Select Create, then set its Initial value for this position and select Apply. Each position that uses this variable needs its own value set independently.
To use a Position Variable to swap which connection a control targets, set its type to Connection, then use the Set Position Variable Internal Action on a button to change it at runtime.
Drag a Workflow Variable node from the node pool onto the canvas. The Create Variable dialog opens.
Give it a Variable Key: this is the individual variable's own key, separate from the Workflow's own Variable Key (which defaults to the Workflow's name and is used for other purposes on the Workflow itself).
Set Type: String, Number, or Boolean.
Set an Initial Value, or turn on Persist Value to keep the variable's current value across a restart instead of resetting to its initial value.
Select the check mark to create the node, then select Apply on the workflow.
Change its value from anywhere using the Set Workflow Variable Internal Action.
Most text fields in the inspector have a small folder icon at the end. Selecting it opens the field in an editor with Browse Variables underneath. Variables are grouped into folders: self, parent, position, time, then one folder per connection (named by its Variable Key) and one per Workflow. The number on a folder is how many variables it holds. A folder without a number, such as a connection or Workflow with no variables, has nothing to insert.
Open a folder and select a variable to insert it, then select Done.
A connection variable's full name starts with that connection's Variable Key (set on the connection's Config tab), then a dot, then the variable's own name. If you leave the prefix out, Buttons can't tell which connection you mean, and the reference doesn't work.
For a connection whose Variable Key is ATEM:
Write this
Not this
$(ATEM.pgm1_usk_1_onAir)
$(pgm1_usk_1_onAir)
$(ATEM.device_ip)
$(device_ip)
The same applies inside an expression. An expression that's true while upstream key 1 is on air on M/E 1 is written as:
$(ATEM.pgm1_usk_1_onAir) == true
If you rename a connection's Variable Key, for example from ATEM to StudioA, every reference has to use the new prefix: $(StudioA.pgm1_usk_1_onAir).
Tip
Pick variables from the variable browser or the expression editor's suggestions rather than typing them. Both insert the full name, prefix included.
When a variable's raw value isn't quite what you need, use an expression instead of the variable directly:
Open the expression editor from the same field you'd insert a variable into.
Reference the variable inside the expression, and combine it with functions as needed. For example, concat combines several strings and variables into one value.
The expression editor suggests available functions and variables as you type, so you don't need to remember exact syntax.
Two variables seem to conflict, or one shows the wrong value.
Check their scope: a Self variable in one element and an identically-named Self variable in another are never actually the same variable.
A Position Variable shows a different value than you expect.
Confirm you're looking at the right position: the definition is shared, but each position holds its own independent value.
A Workflow Variable resets after a restart when you expected it to keep its value.
Turn on Persist Value for that variable.
An expression fails with an error such as Unexpected token, or a condition always takes its Else branch.
Check that every connection variable includes its prefix: $(ATEM.pgm1_usk_1_onAir), not $(pgm1_usk_1_onAir). The error doesn't name the variable, so check each $(…) in the expression.
You can't find a variable you know exists.
Open the variable browser (the folder icon) and check under the scope you expect it in: Self and Parent variables only appear while you're inside the right element.
