By far the coolest and most powerful feature of the scripting engine is functions. You have already seen a lot of functions used throughout this document, such as “Dialog.Message.” Functions are simply portions of script that you can define, name and then call from anywhere else.
Although there are a lot of built-in AutoPlay functions, you can also make your own custom functions to suit your specific needs. In general, functions are defined as follows:
function function_name (arguments)
function script here
return return_value;
end
The first part is the keyword “function.” This tells the scripting engine that what follows is a function definition. The function_name is simply a unique name for your function. The arguments are parameters (or values) that will be passed to the function every time it is called. A function can receive any number of arguments from 0 to infinity (well, not infinity, but don’t get technical on me). The “return” keyword tells the function to return one or more values back to the script that called it.
The easiest way to learn about functions is to look at some examples. In this first example, we will make a simple function that shows a message box. It does not take any arguments and does not return anything.
function HelloWorld()
Dialog.Message("Welcome","Hello World");
end
Notice that if you put the above script into an event and preview your application, nothing happens. Well, that is true and not true. It is true that nothing visible happens but the magic is in what you don’t see. When the event is fired and the function script is executed, the function called “HelloWorld” becomes part of the scripting engine. That means it is now available to the rest of the application in any other script.
This brings up an important point about scripting in AutoPlay Media Studio. When making a function, the function does not get “into” the engine until the script is executed. That means that if you define HelloWorld() in a button’s On Click event, but that event never gets triggered (because the user doesn’t click on the button), the HelloWorld() function will never exist. That is, you will not be able to call it from anywhere else.
That is why, in general, it is best to define your global functions in the global script of the project. (To access the global script, choose Project > Global Functions from the menu.)
Now back to the good stuff. Let’s add a line to actually call the function:
function HelloWorld()
Dialog.Message("Welcome","Hello
World");
end
HelloWorld();
The “HelloWorld();” line tells the scripting engine to “go perform the function named HelloWorld.” When that line gets executed, you would see a welcome message with the text “Hello World” in it.
Let’s take this a bit further and tell the message box which text to display by adding an argument to the function.
function HelloWorld(Message)
Dialog.Message("Welcome", Message);
end
HelloWorld("This is an argument");
Now the message box shows the text that was “passed” to the function.
In the function definition, “Message” is a variable that will automatically receive whatever argument is passed to the function. In the function call, we pass the string “This is an argument” as the first (and only) argument for the HelloWorld function.
Here is an example of using multiple arguments.
function HelloWorld(Title, Message)
Dialog.Message(Title, Message);
end
HelloWorld("This is argument one", "This is argument two");
HelloWorld("Welcome", "Hi there");
This time, the function definition uses two variables, one for each of its two arguments...and each function call passes two strings to the HelloWorld function.
Note that by changing the content of those strings, you can send different arguments to the function, and achieve different results.
The next step is to make the function return values back to the calling script. Here is a function that accepts a number as its single argument, and then returns a string containing all of the numbers from one to that number.
function Count(n)
-- start out with a blank return string
ReturnString = "";
for num = 1,n do
-- add the current number (num) to the end of
the return string
ReturnString = ReturnString..num;
-- if this isn't the last number, then add a comma
and a space
-- to separate the numbers a bit in the return
string
if (num ~= n) then
ReturnString = ReturnString..",
";
end
end
-- return the string that we built
return ReturnString;
end
CountString = Count(10);
Dialog.Message("Count", CountString);
The last two lines of the above script uses the Count function to build a string counting from 1 to 10, stores it in a variable named CountString, and then displays the contents of that variable in a dialog message box.
You can return multiple values from functions as well:
function SortNumbers(Number1, Number2)
if Number1 <= Number2 then
return Number1, Number2
else
return Number2, Number1
end
end
firstNum, secondNum = SortNumbers(102, 100);
Dialog.Message("Sorted", firstNum ..", ".. secondNum);
The above script creates a function called SortNumbers that takes two arguments and then returns two values. The first value returned is the smaller number, and the second value returned is the larger one. Note that we specified two variables to receive the return values from the function call on the second last line. The last line of the script displays the two numbers in the order they were sorted into by the function.
Another interesting thing about functions is that you can override a previous function definition simply by re-defining it.
function HelloWorld()
Dialog.Message("Message","Hello
World");
end
function HelloWorld()
Dialog.Message("Message","Hello
Earth");
end
HelloWorld();
The script above shows a message box that says “Hello Earth,” and not “Hello World.” That is because the second version of the HelloWorld() function overrides the first one.
One really powerful thing about tables is that they can be used to hold functions as well as other values. This is significant because it allows you to make sure that your functions have unique names and are logically grouped. (This is how all of the AutoPlay Media Studio functions are implemented.) Here is an example:
-- Make the functions:
function HelloEarth()
Dialog.Message("Message","Hello
Earth");
end
function HelloMoon()
Dialog.Message("Message","Hello
Moon");
end
-- Define an empty table:
Hello = {};
-- Assign the functions to the table:
Hello.Earth = HelloEarth;
Hello.Moon = HelloMoon;
-- Now call the functions:
Hello.Earth();
Hello.Moon();
It is also interesting to note that you can define functions right in your table definition:
Hello = {
Earth = function () Dialog.Message("Message","Hello Earth")
end,
Moon = function () Dialog.Message("Message","Hello
Moon") end };
-- Now call the functions:
Hello.Earth();
Hello.Moon();