Im po r t a n t S c r i p t i n g C o n ce p t s
Important Scripting Concepts
There are a few important things that you should know about the AutoPlay Media Studio scripting language in general before we go on.
S cr ip t i s Glob a l
The scripting engine is global to the runtime environment. That means that all of your events will "know" about other variables and functions declared elsewhere in the product. For example, if you assign "myvar = 10;" in the project's On Startup event, myvar will still equal 10 when the next event is triggered. There are ways around this global nature (see Variable Scope), but it is generally true of the scripting engine.
S cr ip t i s Ca s e -S e n s i t i ve
The scripting engine is case-sensitive. This means that upper and lower case characters are important for things like keywords, variable names and function names.
For example:
ABC = 10;
aBC = 7;
In the above script, ABC and aBC refer to two different variables, and can hold different values. The lowercase "a" in "aBC" makes it completely different from "ABC" as far as AutoPlay is concerned.
The same principle applies to function names as well. For example:
Dialog.Message("Hi", "Hello World");
...refers to a built-in AutoPlay function. However,
DIALOG.Message("Hi", "Hello World");
...will not be recognized as the built-in function, because DIALOG and Dialog are seen as two completely different names.
Note: It's entirely possible to have two functions with the same spelling but different capitalization-for example, GreetUser and gREeTUSeR would be seen as two totally different functions. Although it's definitely possible for such functions to coexist, it's generally better to give functions completely different names to avoid any confusion.
C o mme n t s
You can insert non-executable comments into your scripts to explain and document your code. In a script, any text after two dashes (--) on a line will be ignored. For example:
-- Assign 10 to variable abc abc = 10;
...or:
abc = 10; -- Assign 10 to abc
Both of the above examples do the exact same thing-the comments do not affect the script in any way.
You can also create multi-line comments by using --[[ and ]]-- on either side of the comment:
--[[ This is a multi-line comment ]]-- a = 10;
Nested comments are not supported using [[ string ]]. In these cases you can use the syntax [=[ and ]=]. You can continue to nest these by adding more "=" signs so that each one is paired, for example, [===[...]===].
You should use comments to explain your scripts as much as possible in order to make them easier to understand by yourself and others.
De li m i t ing St a t eme n t s
Each unique statement can either be on its own line and/or separated by a semi-colon (;). For example, all of the following scripts are valid:
Script 1:
a = 10
MyVar = a
Script 2:
a = 10; MyVar = a;
Script 3:
a = 10;
MyVar = a;
However, we recommend that you end all statements with a semi-colon (as in scripts 2 and 3 above).
Variables
Variables
Wh a t are V ar i a bl e s ?
Variables are very important to scripting in AutoPlay. Variables are simply "nicknames" or "placeholders" for values that might need to be modified or re-used in the future. For example, the following script assigns the value 10 to a variable called "amount."
amount = 10;
Note: We say that values are "assigned to" or "stored in" variables. If you picture a variable as a container that can hold a value, assigning a value to a variable is like "placing" that value into a container. You can change this value at any time by assigning a different value to the variable; the
new value simply replaces the old one. This ability to hold changeable information is what makes variables so useful.
Here are a couple of examples demonstrating how you can operate on the "amount" variable:
amount = 10;
amount = amount + 20; Dialog.Message("Value", amount);
This stores 10 in the variable named amount, then adds 20 to that value, and then finally makes a message box appear with the current value (which is now the number 30) in it.
You can also assign one variable to another:
a = 10;
b = a; Dialog.Message("Value", b);
This will make a message box appear with the number 10 in it. The line "b = a;" assigns the value of "a" (which is 10) to "b."
V ar i a bl e S c op e
As mentioned earlier in this document, all variables in AutoPlay Media Studio are global by default. This just means that they exist project-wide, and hold their values from one script to the next. In other words, if a value is assigned to a variable in one script, the variable will still hold that value when the next script is executed.
For example, if you enter the script:
foo = 10;
...into the current page's On Open event, and then enter:
Dialog.Message("The value is:", foo);
...into a button object's On Click event, the second script will use the value that was assigned to "foo" in the first script. As a result, when the button object is clicked, a message box will appear with the number 10 in it.
Note that the order of execution is important...in order for one script to be able to use the value that was assigned to the variable in another script, that other script has to be executed first. In the above example, the page's On Open event is triggered before the button's On Click event, so the value 10 is already assigned to foo when the On Click event's script is executed.
Local Variables
The global nature of the scripting engine means that a variable will retain its value throughout your entire project. You can, however, make variables that are non-global, by using the special keyword "local." Putting the word "local" in front of a variable assignment creates a variable that is local to the current script or function.
For example, let's say you have the following three scripts in the same project:
Script 1:
-- assign 10 to x x = 10;
Script 2:
local x = 500;
Dialog.Message("Local value of x is:", x);
x = 250; -- this changes the local x, not the global one Dialog.Message("Local value of x is:", x);
Script 3:
-- display the global value of x Dialog.Message("Global value of x is:", x);
Let's assume these three scripts are performed one after the other. The first script gives x the value 10. Since all variables are global by default, x will have this value inside all other scripts, too. The second script makes a local assignment to x, giving it the value of 500-but only inside that script. If anything else inside that script wants to access the value of x, it will see the local value instead of the global one. It's like the "x" variable has been temporarily replaced by another variable that looks just like it, but has a different value.
(This reminds me of those caper movies, where the bank robbers put a picture in front of the security cameras so the guards won't see that the vault is being emptied. Only in this case, it's like the bank robbers create a whole new working vault, just like the original, and then dismantle it when they leave.)
When told to display the contents of x, the first Dialog.Message action inside script #2 will display 500, since that is the local value of x when the action is performed. The next line assigns 250 to the local value of x-note that once you make a local variable, it completely replaces the global variable for the rest of the script.
Finally, the third script displays the global value of x, which is still 10.
V ar i a bl e Nam ing
Variable names can be made up of any combination of letters, digits and underscores as long as they do not begin with a number and do not conflict with reserved keywords.
Examples of valid variables names:
a strName
_My_Variable
data1 data_1_23 index bReset nCount
Examples of invalid variable names: 1