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.
Fun c t ion Ar gu me n t s
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.
Re t u r ning V a lu e s
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
end
-- return the string that we built return ReturnString;
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.
Re t u r ning M ul t ipl e V a lu e s
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.
Re d e f ining Fun c t ion s
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.
P u tt ing Fun c t ion s in T a bl e s
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();
S t r i n g M a n i p u l a t i o n
String Manipulation
In this section we will briefly cover some of the most common string manipulation techniques, such as string concatenation and comparisons.
(For more information on the string functions available to you in AutoPlay Media Studio, see
Program Reference / Actions / String in the online help.)
C on ca t e n a t ing St r ing s
We have already covered string concatenation, but it is well worth repeating. The string concatenation operator is two periods in a row (..). For example:
FullName = "Bo".." Derek"; -- FullName is now "Bo Derek"
-- You can also concatenate numbers into strings DaysInYear = 365;
YearString = "There are "..DaysInYear.." days in a year.";
Note that you can put spaces on either side of the dots, or on one side, or not put any spaces at all. For example, the following four lines will accomplish the same thing:
foo = "Hello " .. user_name; foo = "Hello ".. user_name; foo = "Hello " ..user_name; foo = "Hello "..user_name;
C o m p ar ing St r ing s
Next to concatenation, one of the most common things you will want to do with strings is compare one string to another. Depending on what constitutes a "match," this can either be very simple, or just a bit tricky.
If you want to perform a case-sensitive comparison, then all you have to do is use the equals operator (==). For example:
strOne = "Strongbad"; strTwo = "Strongbad";
if strOne == strTwo then
Dialog.Message("Guess what?", "The two strings are equal!");
else
end
Dialog.Message("Hmmm", "The two strings are different.");
Since the == operator performs a case-sensitive comparison when applied to strings, the above script will display a message box proclaiming that the two strings are equal.
If you want to perform a case-insensitive comparison, then you need to take advantage of either the String.Upper or String.Lower function, to ensure that both strings have the same case before you compare them. The String.Upper function returns an all-uppercase version of the string it is
given, and the String.Lower function returns an all-lowercase version. Note that it doesn't matter which function you use in your comparison, so long as you use the same function on both sides of the == operator in your if statement.
For example:
strOne = "Mooohahahaha"; strTwo = "MOOohaHAHAha";
if String.Upper(strOne) == String.Upper(strTwo) then Dialog.Message("Guess what?", "The two strings are equal!");
else
end
Dialog.Message("Hmmm", "The two strings are different.");
In the example above, the String.Upper function converts strOne to "MOOOHAHAHAHA" and strTwo to "MOOOHAHAHAHA" and then the if statement compares the results. (Note: the two original strings remain unchanged.) That way, it doesn't matter what case the original strings had; all that matters is whether the letters are the same.
C oun t ing C h arac t er s
If you ever want to know how long a string is, you can easily count the number of characters it contains. Just use the String.Length function, like so:
twister = "If a wood chuck could chuck wood, how much would...um..."; num_chars = String.Length(twister);
Dialog.Message("That tongue twister has:", num_chars .. " characters!");
...which would produce the following dialog message:
You can also get the length of a string using the length operator #. For example, #"hey" would result in 3.
Finding St r ing s
Another common thing you'll want to do with strings is to search for one string within another. This is very simple to do using the String.Find action.
For example:
strSearchIn = "Isn't it a wonderful day outside?"; strSearchFor = "wonder";
-- search for strSearchIn inside strSearchFor nFoundPos = String.Find(strSearchIn, strSearchFor);
if nFoundPos ~= nil then
-- found it!
Dialog.Message("Search Result", strSearchFor ..
" found at position " .. nFoundPos);
else
end
-- no luck
Dialog.Message("Search Result", strSearchFor .. " not found!");
...would cause the following message to be displayed:
Tip: Try experimenting with different values for strSearchFor and strSearchIn.
Re pl ac ing St r ing s
One of the most powerful things you can do with strings is to perform a search and replace operation on them. The following example shows how you can use the String.Replace action to replace every occurrence of a string with another inside a target string.
strTarget = "There can be only one. Only one is allowed!"; strSearchFor = "one";
strReplaceWith = "a dozen";
strNewString = String.Replace(strTarget, strSearchFor, strReplaceWith); Dialog.Message("After searching and replacing:", strNewString);
-- create a copy of the target string with no spaces in it strNoSpaces = String.Replace(strTarget, " ", ""); Dialog.Message("After removing spaces:", strNoSpaces);
The above example would display the following two messages:
E x t rac t ing St r ing s
There are three string functions that allow you to "extract" a portion of a string, rather than copying the entire string itself. These functions are String.Left, String.Right, and String.Mid.
String.Left copies a number of characters from the beginning of the string. String.Right does the same, but counting from the right end of the string instead. String.Mid allows you to copy a number of characters starting from any position in the string.
You can use these functions to perform all kinds of advanced operations on strings. Here's a basic example showing how they work:
strOriginal = "It really is good to see you again.";
-- copy the first 13 characters into strLeft strLeft = String.Left(strOriginal, 13);
-- copy the last 18 characters into strRight strRight = String.Right(strOriginal, 18);
-- create a new string with the two pieces
strNeo = String.Left .. "awesome" .. strRight .. " Whoa.";
-- copy the word "good" into strMiddle strMiddle = String.Mid(strOriginal, 13, 4);
C on ver t ing N u mer i c St r ing s in t o N u m b er s
There may be times when you have a numeric string, and you need to convert it to a number.
For example, if you have an input field where the user can enter their age, and you read in the text that they typed, you might get a value like "31". Because they typed it in, though, this value is actually a string consisting of the characters "3" and "1".
If you tried to compare this value to a number, you would get a syntax error saying that you attempted to compare a number with a string.
For example, the following script:
age = "31";
if age > 18 then
Dialog.Message("", "You're older than 18.");
end
...would produce the following error message:
The problem in this case is the line that compares the contents of the variable "age" with the number 18:
if age > 18 then
This generates an error because age contains a string, and not a number. The script engine doesn't allow you to compare numbers with strings in this way. It has no way of knowing whether you wanted to treat age as a number, or treat 18 as a string.
The solution is simply to convert the value of age to a number before comparing it. There are two ways to do this. One way is to use the String.ToNumber function.
The String.ToNumber function translates a numeric string into the equivalent number, so it can be used in a numeric comparison.
age = "31";
if String.ToNumber(age) > 18 then Dialog.Message("", "You're older than 18.");
end
The other way takes advantage of the scripting engine's ability to convert numbers into strings when it knows what your intentions are. For example, if you're performing an arithmetic operation (such as adding two numbers), the engine will automatically convert any numeric strings to numbers for you:
age = "26" + 5; -- result is a numeric value
The above example would not generate any errors, because the scripting engine understands that the only way the statement makes sense is if you meant to use the numeric string as a number. As a result, the engine automatically converts the numeric string to a number so it can perform the calculation.
Knowing this, we can convert a numeric string to a number without changing its value by simply adding 0 to it, like so:
age = "31";
if (age + 0) > 18 then
Dialog.Message("", "You're older than 18.");
end
In the preceding example, adding zero to the variable gets the engine to convert the value to a number, and the result is then compared with 18. No more error.
O t h e r B u il t- i n F un c t i o n s
Other Built-in Functions
S cr ip t Fun c t ion s
There are three other built-in functions that may prove useful to you: dofile, require, and type.
dofile
Loads and executes a script file. The contents of the file will be executed as though it was typed directly into the script. The syntax is:
dofile(file_path);