Functions

Q-SYS Control 101 Training : Flow Control

3 ) Simple Communication

15m 13s

4 ) Feature License Activation

4m 12s

5 ) Block Controller

19m 7s

7 ) Flow Control

34m 20s

8 ) Control 101 Conclusion

1m 42s

Lesson Description

Functions 6m 41s

Create repeatable functions, and then execute those functions with varying parameters in both Lua and the Block Controller.

Video Transcript

Functions 6m 41s
0:08
In scripting, a function is an action or series of actions that is initiated by a particular stimulus. Other
0:15
coding languages might call this a procedure, or a subroutine. So far everything that we’ve scripted
0:21
has happened automatically as soon as we run the script, but a function is an action that you define
0:26
in the script, and then you can execute that function whenever and however you like.
0:32
There are five pieces to the construction of a function in Lua. First you enter the word function, then
0:39
if you like you can provide a name for the function.
0:42
If you give your function a name, that lets you quickly recall the same process over and over again
0:47
from multiple places, rather than rewriting it every time you want to perform it.
0:52
Next, within a set of parentheses you include any arguments that you want to pass into the function.
0:58
You could consider an argument to be like a local variable – it’s a thing that’s going to be used within
1:04
the function.
1:05
Next we write the body of the function, which is the list of actions you want the function to perform,
1:11
and finally you close off the function with the word end.
1:16
Here we have a very simple function named “f” which has two arguments – x and y. Within the body
1:23
of this function we are printing the result of x plus y. The word end completes the function. Now we
1:30
can launch this function simply by entering its name, and including the arguments we want to pass
1:35
into it in our parentheses. For instance if I enter “f(1,2)” then it will print the result of “3.” Note that
1:43
the function is expecting two arguments in this case, so it will return an error if I recall the function
1:49
without all the information it needs. Or if I were to add a third argument here, it won’t do anything
1:56
with that information because this function has no instructions to do anything with a third argument.
2:00
If this looks familiar, it’s because you’ve already been using a named function called … print. The
2:07
print command is a function, and whatever you put in its single argument, in the parenthesis, is the
2:13
information that this function sends to the Debug Window.
2:18
When you get into some more advanced functions, you may discover times when you don’t know
2:23
how many arguments you want to pass in. In this case you could use “…” in lieu of the arguments,
2:29
which tells the function to adapt to as many arguments as are provided. On the other hand, if your
2:35
function requires no arguments at all, you still need the open- and closed-parentheses to complete
2:41
the structure of the function, but there will simply be nothing in between them.
2:45
For instance, let’s look at a couple of other simple functions.
2:48
Here’s a function called “goblue”, with no arguments. The body of the function simply changes a
2:54
particular control’s .Color parameter to “blue,” and then it ends. Since this function only does one
3:01
thing, with no variables, we don’t need any information in our argument parentheses.
3:06
Here, let’s make a simple mathematical function called “plus5.” It will include one argument, A. We’ll
3:13
use this function to add 5 to the value of a control. So the body of the function would look like this:
3:20
we will take the incoming A.Value and redefine it as it’s current state plus 5. And just for good
3:28
measure let’s print the new A.Value before we end it. Now we could execute that function and enter
3:35
any control we like as the argument, and that control will have 5 added to its Value.
3:41
You could also add a return command within the body of your function, which will output whatever
3:48
information you specify at the conclusion of the function. For instance, looking back at our first
3:53
function, rather than include a print statement in my function, I’m going to define local variable M as
3:59
our “X+Y” Now I can’t print “m” because that’s a local variable, so my print command can’t access it.
4:08
But if I add the phrase “return m” at the end of our function, then this basically tells our function to
4:15
spit this answer back out. So now I can choose to print the function itself (print (f(1,2)), which returns
4:25
m, which is sent to my debug window.
4:28
One last thing while we're here on the Lua side, you may have noticed this little icon to the left of
4:33
your function. If you click it, the entire structure of function will collapse to a single line of code so
4:39
that it's not cluttering up the rest of your screen. You can always expand it again to keep on editing it,
4:44
or you can collapse it again just to make it a little bit easier to read.
4:48
In the Block Controller, you can define a function by going to the Variables & Functions section. Here
4:54
you’ll see two “define function” blocks, in which one has a “return” option and the other does not.
5:01
So, if you wanted this function to return information you could add that variable at this point,
5:07
whereas this function has a point of no return. JOKES! Alright, let's give a name to our function, and if
5:17
you want to include arguments passed into this function, you can click on the cog icon and add
5:22
“inputs” to the body of this block. Here I’ll add two arguments, and if I wanted this function to print
5:28
their sum, I could go to the System section and grab a Debug Print command, then go to the Operators
5:35
section and grab a mathematical addition block. I can pull the arguments right out of the top of this
5:41
function block to add them to its body. Just hover your mouse over the argument and the blocks
5:46
related to it are revealed. I’ll drag x and x1 into my arithmetic block. Now to launch this function, I can
5:54
find it as an available function in my Variables and Functions list. I simply need to populate the two
6:00
two arguments with actual information, and then when my Block Controller script runs it will run
6:06
the function. As always, I encourage you to look at the Lua generated by these blocks to reinforce
6:12
your learning of script. You can see that the function is built the same way we just learned, and it is
6:18
then executed using the two values we input into the arguments sections.
6:24
In the next section we’ll talk about creating the conditions for which a function like this could be
6:29
executed. But first, we have some exercises on functions for you to perform in the Control
6:34
Worksheet. Once you’re done, move on to the next video.