T i p s
Helpful Tips
Contents
Please select one of the following subjects:
Planning Your Project Naming Objects Naming Variables Using Variables Using Comments Using Whitespace
Helpful Tips
ContentsPlanning Your Project
(A guest topic by AutoPlay beta tester Derek Johnson.)
Before you start your project you need to consider whom the project is for and what is required of it.
If the project is for your own use, it is a good idea to compose a list of what it will do, the type of media you want to include in it, and how it is to be designed. A quick sketch of the basics is always a good place to start.
If the project is for a customer, you have much more to include. The basics are the same, of course. In this project, the customer may want to be involved to a certain degree. There are times the customer will give you the go-ahead to create a project using your own initiative and will only be interested in the finished product. You should get into a habit of discussing the idea behind the project and what it will be used for. Will the project form part of an application for the work they carry out, or will it be used for presentation? And for whom? Some companies may need the project for their own use only, while others will surely be showing it to their customers.
Additionally, you should seek out the ideas that your customer has for the project. Some customers will already have an idea in mind as to how they want the project to run-and may even have a sketch for you to use. Company media, too, may need to be included in the project, such as a company logo. All this needs to be acquired in advance, along with any other content they want in the project. After all, they are the customer!
Once you have all the information necessary from the customer and have acquired any media that needs to be included, you should go through your sketch again to ensure that you are happy with the overall layout and design. Once you are happy that the project will work in theory, it is time to create it.
I n c lud e d M e di a
There is a lot of media that can be included in Autoplay Media Studio. You might find it easier to edit any graphics and video before you start.
Internet web pages are also something you may want to consider. If you are linking to the Internet for information, make sure you have the necessary permission and licenses before starting your project. Don't forget, too, that a web page on the Internet today, may not be there tomorrow. The internet is changing daily and it might be a preferable strategy to include a copy of the web pages in you project instead of linking to them-if this is permissible!
Helpful Tips
ContentsNaming Objects
Every object has a name. The name is what identifies the object on the page. Every object on a page must have a unique name-in fact, AutoPlay Media Studio won't let you give two objects on a page the same name.
When you add a new object, it is automatically given a default name like "Label1" or "Image8." Each time you add another image of the same type, AutoPlay adjusts the number to make sure the new object's name is unique. For example, when you add two button objects in a row to a blank page, the first object would be named Button1, and the second object would be named Button2.
Now, suppose you added 12 more button objects to the page. You would have 14 objects with names from Button1 all the way to Button14. Which is okay, if you don't need to refer to those objects at all...and some objects are like that, just sitting on the page, never needing to be the target of an action like Button.SetVisible or Button.SetText. But as soon as you want to perform an action on an object, things can get tricky if they all have relatively meaningless names.
The problem with the default names is that they don't give you any indication of what the object is used for. Sure, you could remember that "Button9" is the one with "Install Files" in it, and "Label4" is the one that you display the user's name in. But chances are, you'll forget which object is which, or you'll come
back to your project after an especially long weekend and find yourself wishing you gave the objects better names.
Which is exactly what you should do whenever you add an object: give it a meaningful name.
Giving objects names that you can easily recognize helps you make sure that the object you're working on is the object you wanted to be working on. So, give each object a name that you can remember...and make sure it's an object name that will still make sense to you three months from now when you come back to make changes to the project.
(The only exception is if you know for sure that the object will never need to be the target of an action, or if you're working on a simple project that only has three objects in it.)
S o Wh a t M ake s a Good Obj ec t Name ?
There are no hard and fast rules for naming objects-other than the fact that you can't have two objects on a page with the same name, the sky's the limit on what you call the little critters. Before you start naming everything after your late great uncle's exotic collection of sea shells, though, it pays to consider the following bits of advice.
· Use simple, descriptive, meaningful names for your objects. Don't call an image object that has a picture of a rose in it "Smells Better Than My Socks." Call a rose a rose, and name the object something like "Rose Image" or even just "Rose." If you have more than one rose image on the page, try making the names a bit more specific: "Pink Rose," "Red Rose 3," etc.
· Using the object type in the name is an easy way to prevent two different types of objects from having the same name. You can't name a label object "Starship" if you already have an image object named "Starship" on the same page. Instead, either name everything with a prefix or suffix that identifies the object type ("Label - Starship" or "Starship Label"), or simply be more specific ("Starship Name").
· Of course, don't feel like you have to mention the object type in the name (e.g. "Songs ListBox" vs. "Songs"). You can always use the object browser to view the list of objects by object type, no matter what you name your objects.
· It's perfectly okay to use spaces...you don't have to name your objects things like "MyNameHasNoSpacesInIt" or "I_am_a_l33t_programmer_look_at_my_nifty_object_name" unless you've worn out the space bar on your keyboard.
· Be descriptive. Shorter names will not make your application run faster. You don't have to use cryptic abbreviations in your names.
· All else being equal, shorter names are usually easier to type. If you plan to do any scripting with the object, you might want to avoid overly long names, just to avoid having to type all the letters over and over again. (If you're a touch typist, though, full words are usually easier to type than abbreviations.)
· Have fun with the names. Go ahead...call your exit button "Exit button...tally-ho!" Name an image "Jose's favorite sunset photo" in honor of your pet iguana. No one but you will ever see them. Well, except perhaps your coworkers, and maybe your boss, and Indigo Rose tech support...okay, on second thought, don't have too much fun with your names.
· Try to pick names that will sort the way you want them to. Instead of "Left Image" and "Right Image", use "Image - Left" and "Image - Right." This way, related objects will appear next to each other when you select a name in the New Action wizard or view the objects in the object browser (a.k.a. the "Objects" panel).
Helpful Tips
ContentsNaming Variables
You can name your variables almost anything you like, but there are a few rules and guidelines you should follow:
1. Variable names can only contain letters, digits and underscores.
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 any reserved keywords.
2. Variable names are case sensitive.
The names MyVar and myvar each refer to a different variable.
3. Don't use any hyphens (-) in your variable names.
The hyphen is used as an operator in AutoPlay. If you put an operator in a variable name, it will "break up" the variable into two separate variables, resulting in a syntax error (if you're lucky) or some kind of unexpected behaviour at run time. For example, Foo-Bar would be seen as subtracting the value of "Bar" from the value of "Foo" using the "-" operator.
4. Try to use meaningful names.
For example, if you read a product's installation date from the Registry, naming the variable Greegleborg452sx probably isn't a good idea. Use a variable name like InstallDate instead.
5. Use prefixes to your advantage.
A common tactic among programmers is to use short prefixes like "str" and "n" to mark variables according to what kind of data they contain-such as string or numeric values. Although AutoPlay's variables can hold any type of value at any time, it can still be helpful to use prefixes in your variable names. For example, using this system the name strResult would be used to contain a string, and the name nResult would be used to store a number. Prefixes help make your intentions clear in such cases where the name is somewhat ambiguous on its own.
6. Be consistent.
If you start out with UserName and UserAge, don't name your third variable WhereTheUserGoesToWork. A name like UserCompany will be easier to remember when you find yourself asking "what did I name that variable, again?"
7. Don't use any of the action category names.
Action names are made up of a category, like Application or File, followed by a dot and a function name, like Exit or Copy. For example, the Application.Exit action is located in the "Application" category, and the File.Copy action is located in the "File" category.
Using a variable name like "Application" or "File" will cause all of the actions in that category to be inaccessible. This is because the action names are implemented as tables containing functions. For example, the File category is internally represented by a table containing the various file functions like Copy, Find, and Open.
Since assigning a value to a variable overwrites any value that is already in the variable,
assigning a value to a variable named "File" will replace the File category with your value.
So, as a general rule, never name your variables anything that appears to the left of a period in an action name.
8. Don't assign a value to a built-in variable by mistake.
For example, assigning a value to a variable called _SystemFolder would override the built-in variable with the same name. Take time to familiarize yourself with the list of built-in global variables so you don't use any of them by accident.
9. Don't use the same variable name twice unless you mean to.
Using a name twice is fine if you're assigning a value to a variable in one place, and accessing that value in another. Just be careful not to unintentionally give the same name to two variables if they're being used to represent two different things.
Of course, it's okay to assign a value to a variable twice if you want its value to change. In that case, the first value will only be in effect until the second one "overwrites" it.
10. Avoid using accented characters in variable names.
We recommend avoiding variable names with accented characters. Some characters have been known to cause issues.
11. When in doubt, double-check.
A common mistake is to name a variable one thing in one part of your project, and start calling it something else later. If you're not sure what name you used, double-check by going back to the place where you defined the variable.
Helpful Tips
ContentsUsing Variables
Here are some general notes on using variables:
1. Variables are automatically "created" the first time a value is assigned to them.
2. Variables are essentially typeless. You don't have to "declare" variables to be of a specific type, like in some programming languages. Instead, variables can hold any type of value. You can freely assign a string to a variable that currently contains a number, and vice-versa. (This doesn't mean that types aren't important...the type of the value itself still matters for actions and functions and such.)
3. Variables are global by default. This means that once a variable is created, it is available throughout your project (unless you specifically make it a local variable).
Note: Variables persist across pages and dialogs. This means that variables hold their values across pages and dialogs. If you assign a value to a variable on one page or dialog, it will still have that value on another page or dialog-and another-and another-until eventually you assign something else to that variable.
4. Once a value has been assigned to a variable, it will continue to contain that value until you assign something else to it.
It's important to remember this when you're using variables to control the "state" of things on a page or dialog (like remembering whether the user turned the background music off). If you need a variable to have a default value whenever a page or dialog is shown, you'll need to set that default value yourself, by assigning a value to the variable in that page's On Preload event.
5. Order is important.
When creating and using variables, be sure to think about when and where they will be used, and what their values will be at that point in time. A variable that is only assigned a value on the last page of your AutoPlay application won't have a value when your application starts up.
For example, let's say you use a Dialog.Input action that asks the user for their name and stores it in a variable called UserName. It's important to realize that UserName won't contain the user's name until after that Dialog.Input action is performed. If the action is only performed when Page2 opens, UserName won't have a value earlier on when Page1 is shown. In this case, using UserName in a Label.SetText action on Page1 would result in an error because Label.SetText is expecting a string value, but UserName doesn't contain a string. (It contains nothing, represented by the keyword "nil.")
The same is true for using variables within a script. When you assign a value to a variable, the value doesn't get assigned to the variable until that line of script is performed; in other words, it's value is only available to the actions that come "later." If you try to use the variable in an action higher "up" in the same script, or use it in another event that happens "earlier," the variable either won't have a value yet, or it won't have the value you expected it to have, and your AutoPlay application will either generate an error or not behave as you intended. (This is why it's important to test your application thoroughly before releasing it to the public.)
A variable is only available to the parts of the your application that are performed after the variable is created. If you want to use a variable in an action on Page4, make sure a value is assigned to the variable before that action is performed.
6. The built-in variables are listed along with all of the actions and constants when you press Ctrl+Space in the script editor. Since all of the built-in variables start with an underscore, if you type _ and then press Ctrl+Space, you'll be taken right to the first built-in variable in the list.
Helpful Tips
ContentsUsing Comments
Comments are just bits of text that are completely ignored by AutoPlay. You can use comments to add notes to your scripts in order to make them easier to understand.
Note: Because the text will be ignored, you can write anything you want in a comment, and it will have no effect on how your application operates.
In AutoPlay, anything after two dashes (--) on a line is a comment. You can either put comments on their own line, like this:
-- Assign 10 to variable abc abc = 10;
...or put them at the end of a line, like this:
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 putting paired square brackets ([[ and ]]) around the comment text, like this:
--[[ This is a multi-line comment ]] abc = 10;
Note: Comments are displayed in a different color that makes them easy to recognize in the script editor. (The comments are displayed in green by default, but you can change this color in the script editor settings.)
C o mme n t s S ave Y ou Ti me a nd Eff o r t
You should make a habit of adding comments to your scripts as you build them. If adding comments seems like a waste of time, consider how much time you will spend working on these scripts in the future. Complex scripts that make perfect sense to you now might take a few minutes to interpret the next time you need to make changes to a project. A few comments written while things are fresh in your mind can minimize the amount of re-thinking required.
Comments are especially important in a multi-user environment. If it's foreseeable at all that someone else may need to work on your project in the future, do your organization a favor and document your actions well.
Here are some tips for using comments:
· Use comments to summarize large blocks of actions. This way, you only have to read the comment to know what the actions do. It's easier to read one line of text than it is to decipher a long list of actions.
· Use comments to explain why an action is needed. This is especially important when the purpose of an action isn't obvious.
· Use comments to highlight important actions, or to label different parts of your scripts so they're easier to find.
· Use comments in a team environment to help keep track of changes (and who made them).
· Use comments to document the decision process that led you to choose one approach over another. This could save you time if you ever find yourself considering other approaches again.
· Use comments appropriately. Don't waste time explaining simple actions that are readily apparent.
Think of comments as investing a little bit of time now to save you a lot of time over the long run. You only have to write a comment once, but you will benefit from the comment many times over. In the long run, well-written comments will save you time, time and time again.
Tip: Use comments. You'll thank us later.
A n E xam pl e o f Good C o mme n t s
Here's a real-world example showing how a few comments can help clarify even a short, simple script. First, the script without any comments:
nPos = String.ReverseFind(e_URL, "#", true);
if nPos then
strPage = String.Mid(e_URL, nPos + 1, -1); Page.Jump(strPage);
end
The script is simple enough, but it becomes even clearer once some comments have been added:
---------------------------------------------------------------------
-
-- jump to a page when the user clicks on a link in this web object -
-
---------------------------------------------------------------------
-
-- search the target URL from right to left for a number sign (#) nPos = String.ReverseFind(e_URL, "#", true);
-- did we find a # ? if nPos then
-- get everything to the right of the # strPage = String.Mid(e_URL, nPos + 1, -1);
end
--[[ jump to the page name that we extracted from the URL. If there is no page by that name, this Page.Jump won't do anything. ]]
Page.Jump(strPage);
Helpful Tips
ContentsUsing Whitespace
"Whitespace" is a term programmers use to describe things like blank lines, tab characters and spaces that are used to improve the readability of their code. You can use whitespace to make your AutoPlay scripts easier to read.
Unless they are contained within a string, whitespace characters (like spaces and tabs) are completely ignored by the AutoPlay application at run time. Their only purpose is to allow you to separate and format your actions a little and make your scripts easier to read.
For example, separating groups of actions with one or more blank lines makes it easier to recognize that the actions are meant to work together as a group. This is especially useful when combined with comments...a single comment can explain an entire group actions this way. Take a look at the following script:
Debug.ShowWindow(true);
file = _TempFolder .. "\\MyTempFile.tmp";
-- convert that path into its various parts path_parts = String.SplitPath(file);
-- display the parts on the debug window Debug.Print("Drive: " .. path_parts.Drive .. "\r\n");
Debug.Print("Folder: " .. path_parts.Folder .. "\r\n"); Debug.Print("Filename: " .. path_parts.Filename .. "\r\n"); Debug.Print("Extension: " .. path_parts.Extension .. "\r\n");
-- get the file's current attributes attrib = File.GetAttributes( file );
-- override a couple of the values in the table attrib.ReadOnly = true;
attrib.Hidden = false;
-- set the modified attributes back to the file File.SetAttributes( file, attrib );
A bit hard to read, isn't it?
Now here's the same script with a few blank lines added:
Debug.ShowWindow(true);
file = _TempFolder .. "\\MyTempFile.tmp";
-- convert that path into its various parts path_parts = String.SplitPath(file);
-- display the parts on the debug window Debug.Print("Drive: " .. path_parts.Drive .. "\r\n"); Debug.Print("Folder: " .. path_parts.Folder .. "\r\n"); Debug.Print("Filename: " .. path_parts.Filename .. "\r\n");
Debug.Print("Extension: " .. path_parts.Extension .. "\r\n");
-- get the file's current attributes attrib = File.GetAttributes( file );
-- override a couple of the values in the table attrib.ReadOnly = true;
attrib.Hidden = false;
-- set the modified attributes back to the file File.SetAttributes( file, attrib );
The whitespace makes it much easier to read.
B lo ck I nd e n t a t ion
Another common use of whitespace is to make script blocks easier to see.
A block is a section of script that is controlled or affected by a control structure, such as an if statement or a while loop. For example, in an if statement, the block consists of the lines of script "inside" the if statement, that are only executed if that if statement's test is found to be true:
if(foo == true) then
-- tell the user foo is true Dialog.Message("Hey User", "foo is true!");
end
In the example above, the two indented lines form a script "block." Technically, a block doesn't have to be indented, but it's common practice to do so, and it really makes it easier to see the part that will be affected by the if statement in the script.
AutoPlay's script editor makes it easy to add this kind of indentation to your scripts. To indent your first line in a block, just press the tab key at the start of the line. This will move the cursor over by one "level" of indentation to the right. Then continue adding lines to the block. Whenever you press Enter on a line that is indented, the editor automatically positions your cursor at the same level of indentation on the next line.
Tip: You can even indent or unindent multiple lines at once, by selecting the lines and pressing Tab (to increase the level of indentation) or pressing Shift+Tab (to decrease the level of indentation).
Indentation is especially important when there are multiple levels involved. For example, here is a short script that has a nested for loop (i.e. one for loop inside another) and a bunch of if statements. First let's see the script with no indentation:
Debug.ShowWindow(true); if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n"); for j = 5, 1, -1 do
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n"); else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!"); end
for i = 1, 100 do Debug.Print(i.."\r\n"); if count == 50 then
Debug.Print("We're half way to a hundred!\r\n") end
end end end
Now here's the script with standard block formatting:
Debug.ShowWindow(true); if bCount then
Debug.Print("\r\nCounting to a hundred five times...\r\n"); for j = 5, 1, -1 do
if(j == 1) then
Debug.Print("\r\n\r\nThis is the last time!\r\n"); else
Debug.Print("\r\n\r\n" .. j - 1 .. " more times to go!");
end
for i = 1, 100 do Debug.Print(i.."\r\n"); if count == 50 then
Debug.Print("We're half way to a hundred!\r\n")
end
end
end
end
See how the indentation makes it easier to see the different blocks?
Here's another example from an On Click script used in a tic-tac-toe application. First with no indentation:
Hotspot.SetEnabled("5", false); if (player == "o") then Label.SetVisible("o5", true); pos5 = "o";
player = "x"; skip = "true";
if (pos1 == "o" and pos9 == "o") then Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos7 == "o" and pos3 == "o") then Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos2 == "o" and pos8 == "o") then Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos4 == "o" and pos6 == "o") then Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
end
if (player == "x" and skip ~= "true") then Label.SetVisible("x5", true);
pos5 = "x"; player = "o";
if (pos1 == "x" and pos9 == "x") then Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos7 == "x" and pos3 == "x") then Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos2 == "x" and pos8 == "x") then Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
if (pos4 == "x" and pos6 == "x") then Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1"); end
end
skip = "false"; clicked = clicked + 1;
if (clicked == 9) then
result = Dialog.Message("Game Over", "Cat's game (tie) Click to restart", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
Page.Jump("Page1"); end
Now, the same script with some whitespace added:
Hotspot.SetEnabled("5", false);
if (player == "o") then Label.SetVisible("o5", true); pos5 = "o";
player = "x"; skip = "true";
if (pos1 == "o" and pos9 == "o") then
Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
if (pos7 == "o" and pos3 == "o") then
Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
if (pos2 == "o" and pos8 == "o") then
Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
if (pos4 == "o" and pos6 == "o") then
Dialog.Message("Game Over", "O Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
end
if (player == "x" and skip ~= "true") then Label.SetVisible("x5", true);
pos5 = "x"; player = "o";
if (pos1 == "x" and pos9 == "x") then
Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
if (pos7 == "x" and pos3 == "x") then
Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
if (pos2 == "x" and pos8 == "x") then
Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
end
Page.Jump("Page1");
if (pos4 == "x" and pos6 == "x") then
Dialog.Message("Game Over", "X Wins! Click to restart"); clicked = 0;
Page.Jump("Page1");
end
end
skip = "false"; clicked = clicked + 1; if (clicked == 9) then
result = Dialog.Message("Game Over", "Cat's game (tie) Click to restart", MB_OK, MB_ICONINFORMATION, MB_DEFBUTTON1);
Page.Jump("Page1");
end
The second version is much easier to follow.