Before we cover some of the fundamental structure and logic of ActionScript 3.0, let’s write another script to help get the feel of the language and build a little confidence. Specifically, we’ll build on the Hello World! exercise from Chapter 1 to introduce some of the material explained in detail in this chapter. We’ll give you a brief explanation here and then expand on each relevant topic as you read on. Create a new ActionScript 3.0 FLA file and type the following code into frame 1 using the Actions panel. You can compare your work with the hello_world_if_loop.fla source file.

1    var str:String = "Hello World!";
2
3    if (Math.random() < 0.5) {
4        var txtFld:TextField = new TextField();
5        addChild(txtFld);
6        txtFld.text = str;
7    } else {
8        for (var i:int = 0; i < 3; i++) {
9            trace(str);
10        }
11    }

Line 1 creates a variable and tells the ActionScript compiler that it will contain a String, which is simply text. Telling the compiler what kind of data you intend to put into a variable will help it warn you if something attempts to manipulate the data in an incompatible way later on—such as trying to treat text as if it were a number.

The if statement in line 3 does what its name implies. It tests to see if something is true and, if so, executes the code within its braces. In this case, the braces are balanced on line 7, but the statement continues with an else. This means that if the test is false, the next set of instructions, balanced with the last brace on line 11 (lines 8 through 10), is executed. The test in this example, added to show how easy it can be to randomize an outcome in ActionScript, is whether a random number is less than 0.5. Math.random() will create a random number between 0 and 1.

If that number is less than 0.5, the first block of code (lines 4 through 6) will execute. This code creates a text field, makes it visible by adding it to the display list, and puts the contents of the variable into the field—just as you saw in Chapter 1. If the test fails, the second block (lines 8 through 10) will execute. This code is a loop that will run through three times, tracing the value of the string to the Window✓Output panel.

We’ll explain the syntax of this script in greater detail as this chapter progresses, but if you test your movie using Control✓Test Movie, you’ll see the result immediately. Based on the random number selection, you’ll either see text on the stage or in your Output panel. You can test your movie repeatedly to see various outcomes. Now, let’s dig in to some language fundamentals!

Some basic topics don’t require a section devoted to their discussion, but should still be mentioned due to their use throughout the book. For example:

Variables are best described as containers into which you place information for later recall. Imagine if you were unable to store any information for later use. You would not be able to compare values against previously described information (such as user names or passwords), your scripts would suffer performance lags due to unnecessarily repeating calculations, and you wouldn’t be able to carry any prior experiences through to the next possible implementation of a task. In general, you wouldn’t be able to do anything that required data that your application had to “remember.”

Variables make all this and more possible. In the most basic terms, you need only create a variable with a unique name and then populate it with a value. However, for an ActionScript 3.0 compiler to know you are creating a variable, rather than mistyping some other ActionScript keyword, you must also declare the variable using the var keyword. A simple example is remembering the number 1 with the following:

var myVariable = 1;

Keep in mind that variable names:

To help ensure that you are using variables (and other ActionScript language elements) appropriately, ActionScript can check your efforts and warn you when you go awry. Not every mistake can be detected, of course, but every little bit helps. For example, your ActionScript compiler can warn you if you try to perform a mathematical operation on a passage of text. Dividing the text “Flash” by 17, for example, doesn’t make much sense, and it really helps when you are told of such errors.

To make this possible, you must use what is called data typing when you write your code. That is, you must tell the compiler that a variable will contain a specific type of data. To accomplish this, you must follow your variable name with a colon (:) and then the type of data that you want to store in that variable. For example, to data type the previous sample code write:

var horizontalLocation:Number = 4.5;

This insures that any type of number, be it positive or negative, whole number or decimal value, is the only type of data that can ever be stored in horizontalLocation. (In just a few moments, we’ll show you what would happen if you tried to put something other than a number into this variable.)

ActionScript supports several basic data types including, but not limited to, those listed in Table 2-1.

In addition to these basic data types, it’s very common to store variable references to ActionScript objects, such as a movie clip, text field, or sound, and to use type checking to make sure your code contains fewer errors. For example, the following instruction places a MovieClip into the variable logo. The data type insures that the compiler will warn you if you do anything with this variable that is not compatible with the MovieClip type.

var logo:MovieClip = new MovieClip();

Let’s revisit our horizontalLocation variable and see what happens if we try to perform an operation on it that is incompatible with the Number data type. Here’s an example of trying to reassign the variable to a String:

horizontalLocation = "ActionScript";

Having told the compiler to expect only numbers in this variable, this will yield the following error:

1067: Implicit coercion of a value of type String to an unrelated type Number.

This means your code is trying to change a value of type Number to a value of type String, without first explicitly telling the compiler you want to do so. The compiler warns you about this because you may not have intended to change the data type and it wants a clearer instruction before allowing the switch. While this is usually a huge benefit, you may sometimes want a type change to occur. In these cases, you just need to be more direct by casting the data.

horizontalLocation = Number("300");
horizontalLocation = "300" as Number;

var userName:String = "Aubrey";
trace(userName is String);
//traces true to the Output panel

Strict Mode

Once you start data typing your variables, you can be warned of related errors when your application runs or, better yet, when you compile your file—such as when testing your movie in Flash Professional. Whether you check for errors at runtime or when compiling your code is determined by your ActionScript compiler’s Strict Mode setting.

In Flash Professional, the Strict Mode setting is on by default and is a per-file preference, rather than an application preference. As such, it’s found in the Publish Settings of each file (File✓Publish Settings). Flash Professional CS5 users will find shortcuts to this destination in the File menu (File✓ActionScript Settings) and in the Publish section of the Properties panel. In the Flash option at the top of the Publish Settings dialog is a pull-down menu that lets you choose which version of ActionScript to use in each file. Next to that menu is a Settings button, as seen in Figure 2-1. Clicking this button will reveal the Strict Mode option in the Advanced ActionScript 3.0 Settings dialog, as seen in Figure 2-2.

Figure 2-1. A detail from the Flash section of the Publish Settings dialog

Figure 2-2. A detail from the Advanced ActionScript 3.0 Settings dialog, where the Strict Mode preference is found

If Strict Mode is enabled, you will be notified of errors when you compile your file as well as when your SWF is running. If you disable Strict Mode, you will rely solely on runtime error warnings to catch mistakes. We recommend keeping Strict Mode enabled because the compiler will not only help you catch problems as you code, but will even try to tell you where the problem is in your scripts.

Operators are characters that dictate how to combine, compare, or modify values of objects, properties, or expressions. Table 2-2 lists most of ActionScript 3.0’s operators, focusing on the operators you’re likely to use when working with this book’s examples.

You’re probably familiar with many of ActionScript 3.0’s arithmetic, assignment, and comparison operators. Other operators may be new to you, and many will be explained and used throughout the coming chapters. Here are some quick notes referred to in Table 2-2 covering some of the operators you may be less familiar with:

You will often need to make a decision in your script, choosing to do one thing under one circumstance and another thing under a different circumstance. These situations are usually handled by conditionals. Put simply, a test asks whether a condition is met. If the condition is met, the test evaluates to true and specific code is executed accordingly. If the condition is not met, either no further action is taken or an alternate set of code is executed. We’ll now take a look at the if and switch conditional structures.

You can try this code for yourself, or look at the conditionals.fla source file from the chapter archive found in the Downloads section of the companion website. This section provides multiple examples of conditionals to teach the logic behind their use. For an additional practical example, revisit the opening of this chapter, which uses a conditional to perform one of two tasks based on a random number value.

var num:Number = 1;
var str:String = "hello";
var bool:Boolean = false;

if (num == 1) {
    trace("num equals 1");
}

if (num == 1 && str == "goodbye") {
    trace("both tests are true");
}

if (num == 1 || str == "goodbye") {
    trace("one test is true");
}

if (!bool) {
    trace("bool is not true");
}

if (num != 1) {
    trace("num does not equal 1");
}

if (num != 1) {
    trace("num does not equal 1");
} else {
    trace("num equals 1");
}

if (num == 2) {
    trace("num does not equal 1");
} else if (num == 1) {
    trace("num equals 1");
}

if (num == 1) {
    trace("num equals 1");
} else if (str == "hello") {
    trace("str equals 'hello'");
} else {
    trace("other");
}

if (num == 1) {
trace("num equals 1");
}
if (str == "hello") {
trace("str equals 'hello'");
} else {
trace("other");
}

switch (num) {
    case 1 :
        trace("one");
        break;
    case 2 :
        trace("two");
        break;
    case 3 :
        trace("three");
        break;
    default :
        trace("other");
        break;
}

switch (num) {
    case 1 :
        trace("one");
    case 2 :
        trace("two");
        break;
}

switch (true) {
    case num == 1 :
        trace("one");
        break;
    case str == "hello":
        trace("two");
        break;
    case bool :
        trace("three");
        break;
}

It is quite common to execute many repetitive instructions in your scripts. However, including them line by line, one copy after another, is inefficient as well as difficult to edit and maintain. Wrapping repetitive tasks in an efficient structure is the role of loops. A programming loop is probably just what you think it is: it goes through the structure and then loops back to the start and does it again until its task is concluded. There are a few kinds of loops, and the type you choose to use can help determine how many times your instructions are executed. The examples in this section can be found in the loops.fla file, which is downloadable from the companion website. This section explains two kinds of loops: for and while. The first for loop example will look familiar from the opening of this chapter.

for (var i:int = 0; i < 3; i++) {
    trace("hello");
}

for (i = 3; i > 0; i--) {
    trace("hello");
}

var num:Number = Math.random();
while (num < 0.5) {
    trace(num, "is less than 0.5");
    num = Math.random();
}
trace("final num:", num);

var flag:Boolean = true;
while (flag) {
    trace("infinite loop");
}

for (var i:int; i < 3; i++) {
    trace("infinite loop");
    i = 0;
}

Basic variables can contain only one value. If you set a variable to 1 and then set that same variable to 2 in the following line of code, the value would be reassigned, and the value of the variable would be 2.

However, there are times when you need one variable to contain more than one value. Think of a hypothetical set of groceries, including 50 items. The standard variable approach to this problem would be to define 50 variables and populate each with a grocery item. That is the equivalent of 50 pieces of paper, each with one grocery item written on its face. This is unwieldy and can be created only at authoring time—at which point the process is fixed—and you’d have to recall and manage all variable names every time you wanted to access the grocery items.

In real life, you handle the problem by writing a list of 50 grocery items on one piece of paper. You can add to the list while at the store and cross each item off once it is acquired, and you only have to manage one piece of paper. In ActionScript, you handle the problem by creating an array, the code equivalent of that sheet of paper.

Creating an array is quite easy. Like many objects in ActionScript 3.0, you can create an array using the new keyword—either prepopulating the array with a comma-separated list of items, or as an empty array that you intend to populate at runtime. You can also create an array by wrapping your list of items in brackets. Creating an empty array with brackets requires only an empty set of brackets. Both techniques are illustrated here:

var needToBuy:Array = new Array("eggs", "flour", "milk");
var impulseItems:Array = new Array();

var needToBuy2:Array = ["eggs", "flour", "milk"];
var impulseItems2:Array = [];

An array of comma-separated values is called a linear array because it contains a series of items in linear order. Whether the array is prepopulated or empty, you can add to, or remove from, the array at runtime. For example, you can add a value to an array using the push() method, which pushes the value into the array at the end.

The push() method is a handy way to add something to an array because it also tells you how long the new array is, and you can choose to use that information or ignore it. In the following example, the second line of code uses push() without any regard for the feedback the method returns. All that matters is adding the item to the end of the array. The second time push() is used, however, the entire statement is placed inside a trace(). As a result, when push() returns a value of 2 to indicate that there are now two items in the array, that value will be traced. Finally, the resulting array is displayed in the last executed instruction.

var cake:Array = new Array();
cake.push("sugar");
trace(cake);
// sugar appears in the Output panel
trace(cake.push("vanilla"));
// 2 appears in the Output panel
trace(cake);
// sugar,vanilla appears in the Output panel

You can remove an item from the end of an array in a similar manner, using the pop() method. This method also returns a value that you may wish to use but, instead of returning the new length of the array, it returns the item removed from the array.

The next code passage continues the previous example, in which the last value of cake was “sugar, vanilla”. The first line removes the last item in the array and, because it does so from within the trace() statement, the removed item appears in the Output panel. Finally, the entire array is then traced.

trace(cake.pop());
// vanilla appears in the Output panel
trace(cake);
// the final one-item array, sugar, is traced

mc1.mc2.width;

You can add values to or retrieve values from locations within the array by using brackets and including the index, or position, of the array item you need. To do so, you must understand that ActionScript uses what are called zero-based arrays. This means that the first value is at position 0, the second is at position 1, the next at position 2, and so on. As an example, to retrieve the existing third value from an array, you must request the item at index 2:

var newArray:Array = ["chocolate", "lemon", "red velvet"];
trace(newArray[2]);
//"red velvet" appears in the Output panel

To determine the number of items in an array, use the length property:

trace(newArray.length);
//"3" appears in the Output panel

You can also create arrays inside arrays. These are typically called multidimensional arrays and are used to create multiple levels of data. A typical database is a multidimensional array because it is a list of records (such as users), each of which contains fields (such as name, phone, email). If such a database had three records, it would be equivalent to one array of three arrays.

Creating this arrangement is as simple as using an inner array as a value for one of the indices of the outer array. You can do this at the outset, or add it using push()—both of which are demonstrated here:

var mdArray1:Array = ["a", "b", ["c", "d"]];
var mdArray2:Array = ["e", "f"];
mdArray2.push(["g", "h"]);

To access values in a multidimensional array, you must use multiple brackets to go into the nested arrays. For instance, continuing the prior example to retrieve the first item in the array mdArray1, you need only the standard single bracket syntax:

trace(mdArray1[0]);
//traces "a" to the Output panel

However, to access the values in the nested array requires two components. First, you must identify the nested array as the third item of mdArray1 (at index 2). Then you must reference the item within that nested array with another pair of brackets. So, to retrieve “c”, which is the first item in the nested array, the syntax is as follows:

trace(mdArray1[2][0]);
//traces "c" to the Output panel

This makes sense, if you think about it in steps, because not only is mdArray1 an array requiring bracket syntax to retrieve an item therein, but mdArray1[2] is also an array requiring its own brackets to retrieve an item.

Vectors (not to be confused with the precise lines, curves, and shapes created by such object-drawing tools as Adobe Illustrator) are typed arrays. Arrays like those in the previous section can contain data of any type. The following example array includes a String, Number, and Boolean:

var arr:Array = new Array();
arr[0] = "avocado";
arr[0] = 2;
arr[0] = true;

A vector, however, can contain data of only one type, which is determined at the time the vector was created. Although vector syntax may look a little odd at first, its principle uniqueness is the addition of the data type to the vector creation process. The following example vector contains only integers.

var vec:Vector.<int> = new Vector.<int>();
vec[0] = 1;
vec[0] = 2;
vec[0] = 3;

If you try to add an incompatible data type to a vector, you will receive a type coercion error. The following example tries to add a String to the integer vector from the previous snippet:

vec[3] = "guacamole"
//Error 1067: Implicit coercion of a value of type String
//           to an unrelated type int.

From a syntax and use perspective, vectors function the same way arrays do. Vector syntax is typically identical to array syntax. However, because they can contain only one data type, they support more restrictive error checking. When working with vectors, you can be certain that any data you retrieve will be the correct data type for your needs, and any data you add will be checked to be sure it conforms to the desired type. In addition, vectors can be significantly faster than arrays—particularly with large data sets.

Functions are an indispensable part of programming in that they wrap code into blocks that can be executed only when needed. They also allow code blocks to be reused and edited efficiently, without having to copy, paste, and edit repeatedly. Without functions, all code would be executed in a linear progression from start to finish, and edits would require changes to every single occurrence of any repeated code. We’ll look at functions in three parts: minimal structure, use of arguments, and returning values. Figure 2-3 identifies examples of each of the parts of a function that we’ll discuss.

Figure 2-3. Parts of a function

Creating a basic function requires little more than surrounding the code you wish to trigger at will with a simple syntax that allows you to give the block of code a name. Triggering that function later requires only that you call the function by name.

The following syntax shows a function that traces a string to the Output panel. The function is first defined and then, to illustrate the process, immediately called. (In a real-world scenario, the function is usually called at some other time or from some other place, such as when the user clicks a button with the mouse.) The actual output is depicted in the comment that follows the function call, without any added quotation marks. This code can be found in the functions_simple.fla source file.

//single-line comment

/*
multi-line
comment
*/

function showMsg() {
    trace("hello");
}
showMsg();
//hello

If reusing code and executing code only when needed were the only advantages of functions, you’d already have a useful enhancement to the linear execution of ActionScript, because it would allow you to group your code into subroutines that could be triggered at any time and in any order. However, you can do much more with functions to gain even greater power.

function showMsg() {
    var msg:String = "hello";
    trace(msg);
}
showMsg();
//hello

var msg2:String = "hello";
function showMsg2() {
    trace(msg2);
}
showMsg2();
//hello

function showMsg(msg:String) {
    trace(msg);
}
showMsg("goodbye");
//goodbye

function showMsg2(msg:String, user:String) {
    trace(msg + ", " + user + "!");
}
showMsg2("Welcome", "Sally");
//Welcome, Sally!

function showMsg3(msg:String, user:String="User") {
    trace(msg + ", " + user + "!");
}
showMsg3("Welcome", "Claire");
//Welcome, Claire!
showMsg3("Welcome");
//Welcome, User!

function celciusToFarenheit(temp:Number):Number {
    return (9 / 5) * (temp + 32);
}
trace(celciusToFarenheit(20));
//68

function farenheitToCelcius(temp:Number):Number {
    return (5 / 9) * (temp - 32);
}
var temperature:Number = farenheitToCelcius(68);
trace(temperature);
//20

After working with ActionScript for just a short while, you will realize that you are immersed neck-deep in objects—whether you’re using procedural or object-oriented programming. In addition to the numerous objects that are already predefined in the ActionScript language (such as movie clips, text fields, sounds, and more), you can create your own objects and give them properties—the adjectives of the ActionScript world, describing an object’s general characteristics, the way you might describe a movie clip’s width, location, rotation, and so on.

To demonstrate this, we’ll create a custom object called villain, and give it properties for health, armor, and lives. None of these terms—villain, health, armor, or lives—are already part of the ActionScript language. However, the syntax for using custom objects conforms to the same dot syntax used throughout ActionScript, so it will seem like those properties have always been there. The following snippet creates an object, and then creates and populates properties:

var villain:Object = new Object();
villain.health = 100;
villain.armor = 100;
villain.lives = 3;

These values can be called up at any time, by querying the properties the same way they were created.

trace(villain.health);
//100

var obj:Object = {msg:"Hello", user:"Jodi"};

//object syntax
trace(obj.msg);
//associative array syntax
trace(obj["msg"]);

Although potentially a bit nebulous when you’re starting with ActionScript, this can be your friend. It is essentially a self-referential pronoun and is shorthand for “whichever object or scope you’re working with now.” Scope is the realm or space within which an object lives. For example, think of a movie clip inside Flash’s main timeline. Each of these objects (the movie clip and main timeline) has a unique scope, so a variable or function defined inside the movie clip will not exist in the main timeline, and vice versa.

It is easiest to understand the usage of this in context, but here are a couple of examples to get you started. If, from the current scope, you wanted to check the x location of a movie clip with the instance name mc, you might say:

this.mc.x;

Conversely, if you wanted to send the main timeline to frame 2, but do so from within the movie clip, you might say:

this.parent.gotoAndStop(2);

The latter example uses the parent keyword, which refers to the object that is immediately above the current scope in the object hierarchy. In this case, it refers to a movie clip (or main timeline) in which another movie clip resides, and this will be discussed a wee bit more in the following section.

In both cases, this is a reference point from which you start your path. It’s very common to drop the this keyword when referencing properties and methods in the current scope. Many programmers include the keyword for clarity, but it’s also sometimes particularly useful or even required—such as when some ActionScript editors color various parts of your script for improved legibility. In any case, keeping this in your code will help you remember that you’re referencing an object—a concept easy to forget if you frequently omit the friendly pronoun.

Much like a computer operating system’s directory, or the file structure of a website, ActionScript refers to the address of its objects in a hierarchical fashion. You can reference an object address using an absolute or relative path. Absolute paths can be easy because you most likely know the exact path to any object starting from the top of your application—such as Flash Professional’s main timeline. However, absolute paths are quite rigid and will break if you change the nested relationship of any of the referenced objects. Relative paths can be a bit harder to call to mind at any given moment, but they are more flexible. Working from a movie clip and going up one level to its parent and down one level to a child will work from anywhere—be that in the root timeline, another movie clip, or nested even deeper—because the various stages aren’t referenced by name.

Table 2-5 and Table 2-6 draw analogies to uses found in more familiar computer operating system and website analogies.

To end this chapter, let’s look at a script that brings together much of what we’ve discussed to create a randomizing sentence builder. This code can be found in the build_a_sentence.fla source file. To begin, lines 1 through 7 create a series of arrays of adjectives, nouns, and verbs, imagined by my children, Sally and Claire.

Lines 9 through 22 define the buildASentence() function, which takes the adjective, noun, and verb arrays as arguments. Lines 10 through 12 store the number of items in each array, and then the conditional in lines 13 through 15 check to make sure there is at least one item in each array. If any array has 0 items, a warning is returned in line 14 and the function is at an end.

Lines 17 through 19 create a random number between 0 and 2. The Math.random() method generates a random number between 0 and 1, which is then multiplied by the length of each array. The resulting numbers will be used in line 21 as indices to retrieve values from the arrays that were passed into the function. Because array indices must be integers, we must round the random number created.

However, a random number between 0 and 3 might round to a value of 3. Traditional rounding techniques round up when the number is 0.5 or above, and round down for anything under 0.5. So, value of 2.9 would round up to 3. In this case, you’d receive an error because only items 0, 1, and 2 exist in the array. There is no fourth item (that would be retrieved with an index of 3). To skirt this possibility, we force the rounding operation to round down, using the Math.floor() method, allowing only numbers 0, 1, and 2.

Math.round(0.8); //1
Math.round(0.2); //0
Math.floor(0.8); //0
Math.floor(0.2); //0
Math.ceil(0.8); //1
Math.ceil(0.2); //1

The function then ends by returning a sentence. It combines “The ”, a random adjective, a space, a random noun, a space, a random verb, and “ away!” and returns it to the caller of the function. We’ll look at that process, after the code.

1    var adjsSally:Array = ["hairy", "funny", "bouncy"];
2    var nounsSally:Array = ["daddy", "mommy", "sister"];
3    var verbsSally:Array = ["drove", "swam", "ran"];
4
5    var adjsClaire:Array = ["tall", "snuggly", "clean"];
6    var nounsClaire:Array = ["duck", "birdy", "chipmunk"];
7    var verbsClaire:Array = ["ran", "jumped", "tip-toed"];
8
9    function buildASentence(adj:Array, noun:Array, verb:Array):String {
10        var aCount:int = adj.length;
11        var nCount:int = noun.length;
12        var vCount:int = verb.length;
13        if (aCount == 0 || nCount == 0 || vCount == 0) {
14            return ("not enough words provided");
15        }
16
17        var a:int = Math.floor(Math.random() * aCount);
18        var n:int = Math.floor(Math.random() * nCount);
19        var v:int = Math.floor(Math.random() * vCount);
20
21        return "The " + adj[a] + " " + noun[n] + " " + verb[v] +
                "away!";
22    }
23
24    for (var i:int = 0; i < 3; i++) {
25        var sallySays:String = buildASentence(adjsSally, nounsSally,
                                               verbsSally);
26        trace(sallySays);
27
28        var claireSays:String = buildASentence(adjsClaire, nounsClaire,
                                               verbsClaire);
29        trace(claireSays);
30    }

To call the function, we use a for loop in lines 24 through 30. The loop executes 3 times, calling the function with Sally’s arrays (line 25) and Claire’s arrays (line 28). The function returns a sentence in each line, and the loop then traces the results in lines 26 and 29. The results are random, but here is a sample:

The funny mommy drove away!
The snuggly birdy ran away!
The funny sister swam away!
The tall duck tip-toed away!
The hairy daddy swam away!
The clean chipmunk jumped away!

Ideally, we’ve provided just enough background (or review) of key ActionScript fundamentals to now focus on topical syntax. Although we won’t entirely ignore basic elements within the scripts of future chapters, we will spend more time describing the collective goal of a script, and highlighting new issues introduced or updated by ActionScript 3.0.

Next, we start off the ActionScript 3.0-specific material with a look at the three essential building blocks of most ActionScript objects: properties, methods, and events. Events are one of the most significantly changed elements of ActionScript with the introduction of version 3.0.

In the next chapter, we’ll discuss: