The Actions panel is where you’ll be writing your scripts (Figure 6-1). While it’s also possible to write scripts in external files (discussed at length in the companion volume Learning ActionScript 3.0), this book concentrates on originating your scripts in the Flash Timeline, so the Actions panel will be your home.

Here’s an overview of tools found within the Actions panel. In some cases, their functionality may not be self-explanatory, but relevant topics will be explained later in the chapter:

The Output panel is a very simple, but very useful, text output panel that can be used to monitor your own understanding of a script (Figure 6-2). Its sole purpose is to display text generated by a script at authortime. You can’t enter a script in the Output panel, and the panel doesn’t exist at runtime.

You will use the Output panel only as a means of getting quick feedback from an example, or as a testing and debugging technique when writing scripts. You’ll likely find the trace command very helpful, both in this book and in your own scripts, to send information to the panel.

Figure 6-2. The Output panel

Properties are somewhat akin to adjectives in that they describe the object being modified or queried. For example, you can check or set the width of a movie clip. Most properties are read-write, meaning that you can both get and set their values. Some properties, however, are read-only, which means you can ask for, but not change, their values.

Here are examples of setting the width, height, and rotation of a movie clip. You can see these properties in use in the properties.fla source file.

mc.width = 100;
mc.height = 50;
mc.rotation = 90;

Methods are a bit like verbs. They are used to tell objects to do something, such as play and stop. In some cases, methods can simplify the setting of properties. You might use a method called setSize(), for example, to simultaneously set the width and height of something. Other methods are more unique, such as navigateToURL(), which will instruct a browser to display a web page.

Here are examples of telling a movie clip to play, stop, and go to the next frame. You can see these in use in the methods.fla source file.

mc.play();
mc.stop();
mc.nextFrame();

Events are the catalysts that trigger the actions you write, such as setting properties and calling methods. For instance, a user might click the mouse button, which results in a mouse event. That event then causes a function to execute, performing the desired actions. Event handlers are the ActionScript middlemen that trap the events and actually call the functions. ActionScript 3.0 unifies event handling into a consistent system of event listeners, which are set up to listen for the occurrence of a specific event and react accordingly.

Here is an example of an event listener, designed to listen for a mouse up event. You can see this in use in the events.fla source file:

mc.addEventListener(MouseEvent.MOUSE_UP, doIt);
function doIt(evt:MouseEvent):void {
    trace("do it");
}

You’ll learn more about some important concepts in action here, such as how the block of code called a function works, what’s inside the parentheses of the function name, and what void means, but here is the basic idea.

An event listener is listening for a specific mouse event—a mouse up event only, or when the mouse button is released after being pressed. The listener is attached to the movie clip, so when the movie clip is clicked, a mouse up event will be detected. When that happens, the function called doIt() is executed, and the letters “do it” are displayed in the Flash Output panel.

This flow of information—from the click of the mouse, to the trapping (receipt) of the event, to the execution of the function and the eventual output of the text message—is the cycle of event processing. Additional details will be discussed later in this chapter, but this is the mechanism by which interactivity is controlled.

If you look over the code examples earlier in the Basic Script Grammar section, you’ll see that a dot (.) separates the movie clip instance name from its properties and methods. This is sometimes referred to as dot syntax or dot notation. Essentially, this system strings together a series of items, from highest to lowest in the object hierarchy, including only items relevant to the task at hand. In this case, the first relevant item is the movie clip instance and the last is the property or method. Considering another example, in which you want to check the width of a movie clip that is inside another movie clip, the first item will be the parent, or container movie clip, then comes the nested movie clip, and then comes its width:

mc1.mc2.width;

This dot syntax will be used in virtually every example for the rest of this book, and it will soon become as familiar as your own language.

Simply put, ActionScript is case-sensitive. For any word that is already part of the ActionScript lexicon, you must replicate that case exactly. For example, neither “True” nor “TRUE” will work when you’re trying to represent the Boolean (true/false) value of true. Another example is keyboard input. When you want to verify a user’s key input, “Claire” and “CLAIRE” are not the same.

For words you make up, such as variable names (a variable is a container for storing data, discussed later in the chapter), you must be consistent. If you name a variable myMovieClip, you can’t refer to it later as MyMovieClip.

Although you can use any case you like for your own names, a few conventions exist to make code more readable—particularly among multiple programmers working on the same project, where standardized practices really help. A few examples of conventions that are widely adopted include:

In general, ActionScript executes in a top-to-bottom, left-to-right order. That is, each line executes one after another, working from left to right. While this is typically a reliable rule of thumb, several things can change this order in subtle ways. For example, subroutines of one type or another can be called in the middle of a script. This causes the execution order of the original script to pause while the remote routine is executed. When the subroutine has completed, the execution of the original script continues where it left off. Execution flow will be explained in context in all scripts in this book.

The official use of the semicolon in most ECMAScript languages is simply to allow execution of more than one instruction on a single line. This is rare in the average script, and we will look at this technique when discussing loops.

However, the semicolon is also used to indicate the end of a line. Typically, this is not required, but there are cases in AS3 that rely on the semicolon to indicate the end of a line. These are cases in which a single line would be too difficult to read, so the line is broken up by carriage returns, even though it’s essentially a single execution.

A good example of this is writing XML in a human-readable form in a script. The ActionScript compiler is smart enough to understand that line breaks in XML are just for readability, and it looks for the semicolon to indicate the end of a line.

For this reason, and because forging this habit makes it easier to transition into learning other languages where the semicolon is required, place a semicolon at the end of every line.

It’s helpful to note that you are usually not solving an equation when you see an expression with like values on the left and right of an equals sign. For example, if you see something like x = x + 1, it’s unlikely that you will be solving for the value of x. Instead, this line is assigning a new value to x by adding 1 to its previous value.

Much like a computer operating system’s directory or the file structure of a website, ActionScript refers to the location of its objects in a hierarchical fashion. You can reference an object, such as a movie clip, 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 main Timeline. However, they 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 sibling will work from anywhere, be it in the main Timeline, another movie clip, or nested even deeper, because the various stages aren’t named.

Table 6-1 and Table 6-2 draw parallels to the operating system and website analogies. Table 6-1 references the root, which in this case is another way to refer to the main Timeline. The companion website has more information about how to use root.

Comments are lines of text within your scripts that are not executed and are invaluable programmer’s tools. The obvious purpose of a comment is to add a brief descriptive note that will explain the purpose, expected outcome, or possibly a caveat of a segment of your script. Comments are really important when working with other programmers, but they’re also very helpful when archiving your own code. It’s not uncommon to revisit code long after writing it and have to figure out what it does for your project. A single-line comment begins with two slashes:

//set width to size of left column
mc.width = 100;

There’s another, possibly lesser-known purpose of comments, however. It’s quite convenient to use comments to temporarily disable code. For example, you may want to quickly disable ActionScript sound playback or change navigation options. You can also use comments to try two different approaches to a programming task without deleting and rewriting. By completing two alternate versions of a code segment, you can test either at any time by commenting one out and the other back in. Symmetrical slash-asterisk pairs surround multiline comments:

/*
mc.width = 100;
mc.height = 50;
*/
mc.width = 50;
mc.height = 100;

This is obviously a very simple example just to demonstrate the comment toggling process. In this case, it may be as easy to switch the values each time you test, but it’s also easy to become distracted and lose track of the values you tested. As a proof of concept, this example switches a movie clip between horizontal and vertical sizes. To try this code the other way, you could uncomment the first block and comment the second block:

mc.width = 100;
mc.height = 50;
/*
mc.width = 50;
mc.height = 100;
*/

As you write your scripts, it’s helpful to check your progress. As Adobe’s John Dowdell likes to say, “test early, test often.” There are a few tools built into Flash’s interface that can help you quickly examine the health of your scripts:

Assume you need to vary the purpose of the previous function slightly. Let’s say you need to trace 10 different messages. To do that using only what you’ve learned so far, you’d have to create 10 functions and vary the string that is sent to the Output panel in each function.

However, you can accomplish this more easily using arguments. Arguments are like variables that have life only within their own functions. By adding an argument to the parenthesis next to the function name, you can pass a value into that argument when you call the function. In the following case, the argument is called msg and is expected to contain a data type of String:

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

By using msg in the body of the function, it takes on the value that is sent into the argument. In this example, the function no longer traces “hello” every time it’s called. Instead, it traces the text sent into its argument when the function is called. When using arguments, it’s ideal to type the data coming in so Flash knows how to react and can issue any warnings or errors.

It’s also possible to return a value from a function, increasing its usefulness. Returning a value to the script from which it was called means a function can vary its input and its output. The following examples convert temperature values from Celsius to Fahrenheit and Fahrenheit to Celsius. In both cases, a value is sent into the function and a calculated value is returned to the script. The first example immediately traces the result sent back from the function, while the second example stores the value returned from the function in a variable. This mimics real-life usage in that you can immediately act upon the returned value or store and process the data at a later time.

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

function farToCel(far:Number):Number {
    return (5 / 9) * (far - 32);
}
var celDeg:Number = farToCel(68);
trace(celDeg);
//20

When returning a value from a function, you should also declare the data type of the return value. As with applying other data types, use a colon followed by the type specific to that function, but place the data type between the argument’s close parenthesis and the opening function brace. Once you get used to this practice, it’s best to specify void as a return type when your function does not return a value. This will cause an alert if you attempt to return a value after originally planning not to do so.

The most common form conditional is the if statement. The structure of the statement’s basic structure is the if keyword, followed by the conditional test in parentheses and the code to be executed (if the statement evaluates to true) in braces. The first three lines in the following example establish a set of facts. The if statement evaluates the given facts (this initial set of facts will be used for this and subsequent examples in this section).

var a:Number = 1;
var b:String = "hello";
var c:Boolean = false;

if (a == 1) {
    trace("option a");
}

To evaluate the truth of the test inside the parentheses, conditionals often make use of comparison and logical operators. A comparison operator compares two values, such as equals (==), less than (<), and greater than or equal to (>=), to name a few.

A logical operator evaluates the logic of an expression. Included in this category are and (&&), or (||), and not (!). These allow you to ask if “this and that” are true, or if “this or that” is true, or if “this” is not true.

For example, the following code would return false because both conditions must be true. The value of a is 1, but the value of b is “hello.” Because the second test fails, the combined test fails. As a result, nothing would appear in the Output panel.

if (a == 1 && b == "goodbye") {
    trace("options a and b");
}

In the next example, the test would evaluate to true, because one of the two conditions (the first) is true. As a result, “option a or b” would appear in the Output panel.

if (a == 1 || b == "goodbye") {
    trace("option a or b");
}

Finally, the following would also evaluate to true because the not operator correctly determines that c is not true (remember that every if statement, at its core, is testing for truth).

if (!c) {
    trace("not option c");
}

You can also use the not operator in a comparison. When combined with a single equals sign, the pair means “not equal to.” Therefore, the following will fail because a does equal 1, and nothing will appear in the Output panel:

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

Additional power can be added to the if statement by adding an unconditional alternative (true no matter what). In this case, an alternative set of code is executed no matter what the value being tested is, simply because the test did not pass. With the following new code added to the previous example, the second (else) trace will occur:

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

Finally, you can make the statement even more robust by adding a conditional alternative (or an additional test) to the structure. In this example, the second trace will occur:

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

The if statement requires one if. You can use only one optional else, but you can use any number of optional additional else if tests. In all cases, however, only one result can come from the structure. Consider the following example, in which all three results could potentially execute—the first two because they are true, and the last because it’s an unconditional alternative:

if (a == 1) {
    trace("option a");
} else if (b == "hello") {
    trace("option b");
} else {
    trace("option other");
}

In this case, only “option a” would appear in the Output panel, because the first truth would exit the if structure. If you needed more than one execution to occur, you would need to use two or more conditionals. The following structure, for example, executes the first trace in each if, by design:

if (a == 1) {
    trace("option a");
}
if (b == "hello") {
    trace("option b");
} else {
    trace("option other");
}

An if statement can be as simple or as complex as needed. However, long if structures can be difficult to read and are sometimes better expressed using the switch statement. The switch statement also has a unique feature that lets you control which, if any, instructions are executed, even when a test evaluates to false.

Imagine an if statement asking if a variable is 1, else if it’s 2, else if it’s 3, and so on. A test like that can become difficult to read quickly. An alternate structure appears as follows:

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

In this case, “one” would appear in the Output panel. The switch line contains the object or expression you want to test. Each case line offers a possible value. Following the colon are the instructions to execute upon a successful test, and each break line prevents any following instructions from executing. When not used, the next instructions in line will execute, even if that test is false.

For example, if a equals 1, the following will place both “one” and “two” in the Output panel, even though a does not equal 2:

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

This break feature does not exist with the if statement and, if used with care, makes switch an efficient alternative to a more complex series of multiple if statements. Switch statements must have one switch and one case, an optional unconditional alternative in the form of default, and an optional break for each case and default. The final break is not needed, but you may prefer to include it for consistency.

The first type of loop structure is the for loop. This loop executes its contents a finite number of times. For example, you may wish to create a grid of 25 movie clips or check to see which of 5 radio buttons a user has selected.

For our purposes, suppose you want to trace content to the Output panel three times. To loop through a process effectively, you must first start with an initial value, such as 0, so you know you have not yet traced anything to the Output panel. The next step is to test to see if you have exceeded your limit. The first time through, 0 does not exceed the limit of three times. The next step is to trace the content once, and the final step is to increment the initial value, registering that you’ve traced the desired content once. The process then starts over until, ultimately, you will exceed the limit of the loop. The syntax for a basic for loop is as follows:

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

You may notice the declaration and typing of the counter, i. This is a common technique because the i variable is often used only for counting and, therefore, is created on the spot and not used again. If you have already declared and typed the counter, you can omit this step. Next is the loop test. In this case, the counter variable must have a value that is less than 3. Finally, the double plus sign (++) is equivalent to i = i + 1, or “add 1 to the current value of i.”

The result is three occurrences of the word “hello” in the Output panel. It’s also possible to count down by reversing the values in steps 1 and 2, and then decrementing the counter:

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

In other words, as long as the value of i is greater than 0, execute the loop and subtract one from the counter each time. This is less common, and works in this case because the loop only traces a string. However, if you need to use the actual value of i inside the loop, that need may dictate whether you count up or down. For example, if you created 10 movie clips and called them mc0, mc1, mc2, and so on, it may be clearer to count up.

The other loop you’ll likely use is the while loop. Instead of executing its contents a finite number of times, it executes as long as something remains true.

For example, look at a very simple case of choosing a random number. ActionScript generates a random number using a method of the Math class called random(). This method chooses a random number between 0 and 1. So, say you want to choose a random number greater than or equal to 0.5. For the sake of discussion, you have a 50% chance of choosing a desired number each time, so you may end up with the wrong choice several times in a row. To be sure you get a qualifying number, you can add this to your script:

var num:Number = 0;
while (num < 0.5) {
    num = Math.random();
}

Starting with a default value of 0, num will be less than 0.5 the first time into the loop. A random number is then put into the num variable, and if it’s less than 0.5, the loop will execute again. This will go on until a random number that is greater than 0.5 is chosen, thus exiting the loop.

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

It’s very important to understand that although they are compact and convenient, loop structures are not always the best method to achieve an outcome. This is because loops are very processor-intensive. Once a loop begins its process, nothing else will execute until the loop has been exited. For this reason, it may be wise to avoid for and while loops when interim visual updates are required.

In other words, when a loop serves as an initialization for a process that is updated only once upon its completion, such as creating the aforementioned grid of 25 movie clips, you are less likely to have a problem. The script enters the loop, 25 clips are created, the loop is completed, a frame update can then occur, and you see all 25 clips.

However, if you want each of the 25 clips to appear one by one, those interim visual updates of the playhead cannot occur while the processor is consumed by the loop. In this situation, it’s more desirable to create a loop using methods that do not interfere with the normal playhead updates. A frame loop is just such a method. A frame loop is simply a repeating frame event, executing an instruction each time the playhead is updated. The events occur concurrently with any other events in the ordinary functioning of the file, so visual updates, for example, can continue while the frame loop is executing.

Frame loops will be explained in greater detail later in this chapter. For now, the important thing is to remember that frame loops offer a possible alternative to for and while loops.

Arrays can even contain other arrays. The result is called a multidimensional array. Arrays within arrays can resemble database structures or tables. Here are two examples of creating multidimensional arrays:

var multiArray:Array = new Array();
multiArray.push([1,2,3]);
multiArray.push([4,5,6]);

var multiArray2:Array = new Array();
var array1:Array = [1,2,3];
var array2:Array = [4,5,6];
multiArray2.push(array1);
multiArray2.push(array2);

The example in the first three lines pushes two arrays that are created on the fly into a multidimensional array. The second example pushes two existing arrays, which have already been stored in their own variables, into a multidimensional array. In both cases, the resulting array looks like this:

// [[1,2,3],[4,5,6]]

As stated earlier, this is nothing more than an array of arrays. As such, accessing values from the multidimensional array is similar to accessing values from one-dimensional arrays. First, you follow the array name with brackets and an index that identifies which array you want to query further. Because that, too, is an array, you follow it with another set of brackets and index. The following example contains the syntax required to pull 4 out of the first position of the second array in either multidimensional array in the example (the first example, multiArray, is used here):

trace(multiArray[1][0]);
// 4

Associative arrays store a pair of items—the value and an associated property name, or key, to describe that value. For example, a student might be represented this way:

var student1:Array = new Array();
student1["name"] = "Jodi";
student1["email"] = "[email protected]";
student1["phone"] = "212-555-1212";

You can access the value the same way you set the value:

trace(student1["name"]);
// Jodi

Although the values can be any data type, each property in an associative array must be a string.

Another way to accomplish this task is to use an object. Creating a custom object allows you to get and set your property values using the familiar dot syntax employed throughout ActionScript. There are two ways to define objects. The first is to write them out explicitly, as shown in the following example. The syntax looks a bit like an array, with two differences. First, the entity is wrapped with braces, not brackets. Second, instead of single values, commas separate property/value pairs. To access or populate the values, simply reference the property using dot syntax:

var student2:Object = {name:"Sally", email:
"[email protected]", phone:"212-555-1212"};
trace(student2.name);
// Sally

You can create an array of objects this way. You will see this approach in Chapter 9 when you work with components. To access an object’s property, use the same syntax, but first determine which item in the array you want to manipulate. Pull that object out of the array using brackets, then access its property using dot syntax as previously described:

var studentGroup:Aray = new Array();
studentGroup.push({name:"Jodi", email:"[email protected]",
 phone:"212-555-1212"});
studentGroup.push({name:"Sally", email:"[email protected]", phone:"212-555-1212"});
studentGroup.push({name:"Claire", email:"[email protected]",
 phone:"212-555-1212"});
trace(studentGroup[0].name);
// Jodi

Finally, the clearest way to create and populate an object is to create a new instance of the object and add its properties as needed:

var student3:Object = new Object();
student3.name = "Claire";
student3.email = "[email protected]";
student3.phone = "212-555-1212";
trace(student3.name);
// Claire

The concept of event listeners is pretty simple. Imagine that you are in a lecture hall that holds 100 people. Only one person in the audience has been given instructions about how to respond when the lecturer asks a specific question. In this case, one person has been told to listen for a specific event and to act on the provided instructions when this event occurs.

Now imagine that many more responses are required. For example, when the lecturer takes the stage, someone must dim the lights. When the lecturer clicks a hand-held beeping device, an audio/visual technician must advance to the next slide in the presentation. When each video ends, the lecturer must react by introducing the next exhibit in the lecture. Finally, when an audience member raises a hand, an usher must bring a microphone to assist the audience member in asking his or her question.

These are all reactions to specific events that are occurring throughout the lecture. Some are planned and directed to a specific recipient, such as the beeping that triggers the technician to advance to the next video in the series. Others are unplanned, such as when, or even if, an audience member has a question. Yet each appropriate party in the mix has been told which event to listen for and how to react when that event occurs.

Creating an event listener, in its most basic form, is also fairly straightforward. The first step is to identify the host of the listener. That is, which object should be told to listen for a specific event. One easy-to-understand example is instructing a button to listen for mouse events that might trigger its scripted behavior.

Once you have identified an element that should listen for an event, the next step is choosing an event appropriate for that element. For example, it makes sense for a button to listen for a mouse event, but it makes less sense for the same button to listen for the end of a video or the resizing of the Stage. It would be more appropriate for the video player to listen for the end of the video and for the Stage to listen for any resize event. Each respective element could then act or instruct others to act when that event occurs, which leads to the third main step in setting up a listener.

To identify the instructions that must be executed when an event occurs, you simply write a function, then tell the event listener to call that function when the event is heard. That function uses an argument to receive information about the event that called it, allowing the function to use key bits of data during its execution.

To tie it all together, the addEventListener() method puts the listener into service and assigns the function to be executed when the event is heard. Suppose you want a button called rotate_right_btn to listen for a mouse up event and call the function onRotateRight() when the event is heard. The code to accomplish this looks like the following script:

rotate_right_btn.addEventListener(MouseEvent.MOUSE_UP, onRotateRight);
function onRotateRight(evt:MouseEvent):void {
    box.rotation += 20;
}

In the first line, addEventListener() is attached to the button. The method requires two mandatory parameters. The first is the event for which you want to listen. In AS3, similar events are grouped together into classes to make it easier for you to check against their data types. Checking to make sure the incoming event is of type MouseEvent prevents a KeyboardEvent from triggering the listener function.

The MouseEvent class contains constants that refer to mouse events like mouse up and mouse down. This example uses the MOUSE_UP constant to reference the mouse up event.

The second parameter is the function that should be called when the event is received. In this example, it is a reference to the onRotateRight() function, which begins on the second line. The function used in an event listener is just like any other function, with one exception: the argument in a listener function is not optional.

In the following code, for example, the argument is named evt and receives information about the element that triggered the event. You can use information from this argument in the function, which you’ll do in a moment. The argument should be typed to the expected data to improve error checking. In this case, because the function listens for a MouseEvent, that is the data type is used for the argument.

To illustrate this, look at the impact of another mouse event, with more than one listener is in play.

1 myMovieClip.addEventListener(MouseEvent.MOUSE_DOWN, onStartDrag);
2 myMovieClip.addEventListener(MouseEvent.MOUSE_UP, onStopDrag);
3 function onStartDrag(evt:MouseEvent):void {
4     evt.target.startDrag();
5 }
6 function onStopDrag(evt:MouseEvent):void {
7     evt.target.stopDrag();
8 }

In this code, two event listeners are assigned to a movie clip. One listens for a mouse down event and another listens for mouse up. They each invoke different functions. In both functions, however, the target property of the event, which is retrieved from the function argument, identifies which element received the mouse event. This allows the instruction in line 3 to start dragging the selected movie clip, and allows the instruction in line 6 to stop dragging the selected movie clip without specifying the movie clip using its instance name in either case.

This generic approach is very useful because it makes the function much more flexible. It means the function can act upon any appropriate item that is clicked and passed into its argument. In other words, the same function could start and stop dragging any movie clip to which the same listener was added. In the companion source files, the start_stop_drag.fla file shows this by adding the following lines to the previous example:

9 myMovieClip2.addEventListener(MouseEvent.MOUSE_DOWN, onStartDrag);
10 myMovieClip2.addEventListener(MouseEvent.MOUSE_UP, onStopDrag);

You can drag and drop each movie clip simply by adding another movie clip to the exercise and specifying the same listeners.

Now you can use syntax from the Properties, Methods, and Events sections of this chapter to set up interactive control over a movie clip. In the companion source code, you’ll find a file called props_methods_events.fla. It contains nothing more than the example movie clip “box,” and two buttons in the Library that will be used repeatedly to change the five properties discussed earlier. The movie clip contains numbers to show which of its frames is visible at any time, and the instance names of each button will reflect its purpose. Included are move_up_btn, scale_down_btn, rotate_right_btn, fade_up_btn, and toggle_visibility_btn, among others. The start of the main chapter project consists of several buttons that will modify properties of the center movie clip. Figure 6-8 shows the layout of the file.

Figure 6-8. Layout of the props_methods_events.fla file

Starting with movement, you need to define one or more functions to update the location of the movie clip. In this case, you’ll define a separate function for each type of movement.

1 function onMoveLeft(evt:MouseEvent):void {
2     box.x -= 20;
3 }
4 function onMoveRight(evt:MouseEvent):void {
5     box.x += 20;
6 }
7 function onMoveUp(evt:MouseEvent):void {
8     box.y -= 20;
9 }
10 function onMoveDown(evt:MouseEvent):void {
11     box.y += 20;
12 }

You can see that the structure of the functions is consistent. Once you have defined the functions, all you have to do is add the listeners to the appropriate buttons:

13 move_left_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveLeft);
14 move_right_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveRight);
15 move_up_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveUp);
16 move_down_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveDown);

This simple process is then repeated for each of the buttons on stage. The remainder of the script collects the aforementioned properties and event listeners in the same pattern used with the four movement listeners to complete the demo.

17 scale_up_btn.addEventListener(MouseEvent.MOUSE_UP, onScaleUp);
18 scale_down_btn.addEventListener(MouseEvent.MOUSE_UP, onScaleDown);
19
20 rotate_left_btn.addEventListener(MouseEvent.MOUSE_UP, onRotateLeft);
21 rotate_right_btn.addEventListener(MouseEvent.MOUSE_UP, onRotateRight);
22
23 fade_in_btn.addEventListener(MouseEvent.MOUSE_UP, onFadeIn);
24 fade_out_btn.addEventListener(MouseEvent.MOUSE_UP, onFadeOut);
25
26 toggle_visible_btn.addEventListener(MouseEvent.MOUSE_UP, onToggleVisible);
27
28 function onScaleUp(evt:MouseEvent):void {
29     box.scaleX += 0.2;
30     box.scaleY += 0.2;
31 }
32 function onScaleDown(evt:MouseEvent):void {
33     box.scaleX -= 0.2;
34     box.scaleY -= 0.2;
35 }
36
37 function onRotateLeft(evt:MouseEvent):void {
38     box.rotation -= 20;
39
40 }
41 function onRotateRight(evt:MouseEvent):void {
42     box.rotation += 20;
43 }
44
45 function onFadeIn(evt:MouseEvent):void {
46     box.alpha += 0.2;
47 }
48 function onFadeOut(evt:MouseEvent):void {
49     box.alpha -= 0.2;
50 }
51
52 function onToggleVisible(evt:MouseEvent):void {
53     box.visible = !box.visible;
54 }

Finally, you can add an example of a mouse event triggering a method. The final 10 lines of this script will toggle the movie clip between playing and stopped states. Because the stop() and play() methods are not Boolean opposites, you can’t use a single not (!) operator to switch the states. Instead, you need to use a conditional statement that tests the value of a Boolean variable. Each time the play state is reversed, the Boolean variable can be toggled using the not (!) operator to prepare for the next test.

55 var isPlaying:Boolean = true;
56 box.addEventListener(MouseEvent.CLICK, onTogglePlay);
57 function onTogglePlay(evt:MouseEvent):void {
58     if (isPlaying) {
59         box.stop();
60     } else {
61         box.play();
62     }
63     isPlaying = !isPlaying;
64 }

Line 55 creates the variable isPlaying and sets it to true. The default state of the movie clip is playing. Lines 56 through 64 contain the event listener. The listener triggers the onTogglePlay() function when a user clicks the box movie clip.

Line 58 tests to see if isPlaying is true. If so, line 59 stops the movie clip. Otherwise, line 61 plays the movie clip. In either case, the value of isPlaying is reversed (if it was false, it’s set to true, and vice versa).

Frame events are not triggered by user input the way mouse events are. Instead, they occur without intervention as the Flash file plays. Each time the playhead enters a frame that contains a frame script, that script is executed. This means that frame scripts execute only once for the life of the frame, making them excellent for seldom-executed tasks such as initializations. For a frame script to execute more than once, the playhead must leave the frame and return, either because of an ActionScript navigation instruction or a playback loop that returns the playhead to frame 1 when it reaches the end of the Timeline.

However, using an event listener, you can listen for a recurring enter frame event in a movie clip that is independent from the playhead. This type of event can trigger even when the playhead is stopped; this is a great way to run continuous animation. An enter frame event is fired at the same pace as the document frame rate. For example, if the default frame rate is 12 frames per second, the default enter frame frequency is 12 times per second.

The frame_events.fla file in the companion source code demonstrates this event by updating the position of a unicycle every enter frame. It places the unicycle at the horizontal location of the mouse and rotates the wheel child movie clip. Figure 6-9 shows the effect. As the user moves the mouse to the right on the Stage, the unicycle will move to the right, and the wheel will rotate clockwise.

Figure 6-9. Visual depiction of the unicycle movements

Here is the code for this example. The first line adds an enter frame event listener to the main Timeline. The listener function then sets the unicycle’s x location to the mouse’s x location using the mouseX property. It also sets the rotation property of the wheel clip (nested inside cycle) to the same value.

stage.addEventListener(Event.ENTER_FRAME, onFrameLoop);
function onFrameLoop(evt:Event):void {
    cycle.x = mouseX;
    cycle.wheel.rotation = mouseX;
}

If you have experience with prior versions of ActionScript, you’ll probably be excited to hear that the many varied ways of adding an asset to the visual world of Flash have been unified and simplified. If you’re new to ActionScript, the news is even better. You only have to learn one approach to getting an asset into the public eye.

Objects that you can add to the display list are called, appropriately, display objects. For all display objects, you’ll use a variant of new MovieClip()—the new keyword followed by the object class for which you want to create an instance. Other examples include new TextField(), new Video(), new Bitmap(). Even adding an existing movie clip from the Library is consistent with this syntax, as you’ll see in a moment.

While there are many object types that you can add to the display list, you’ll focus on movie clips initially. Just like any other class, the new keyword creates an instance of the display object and you can use the object class (MovieClip) as a data type:

var mc:MovieClip = new MovieClip();

But that’s only the first half of the story. This code creates an object (in this case, a movie clip), but it only places that object in memory. It hasn’t yet become a part of the list of assets the user can see. The second half of the story is adding the object to the display list.

The primary way to add a movie clip to the display list is by using the addChild() method. To add the movie clip you created a moment ago to the main Timeline, you can place this statement after the prior instruction to create the movie clip:

addChild(mc);

Despite its simplicity, this code does imply a destination for the movie clip. By omitting an explicit destination, you cause the movie clip to be added to the scope in which the script was written—in this case, the main Timeline.

You can specify a particular location to which the movie clip will be added, but not all display objects will be happy to adopt a child. For example, neither the Video nor Bitmap display object types can have children. To include a child, the destination must be a display object container. Examples of display object containers include Stage, MovieClip, and Sprite (a one-frame movie clip with no Timeline), but for the purposes of this chapter, you’ll continue to work with movie clips.

So, if you wanted to add the mc movie clip nested inside another movie clip, called mc2, you would provide a destination object for the addChild method to act upon:

mc2.addChild(mc);

You don’t even have to specify a depth (visible stacking order), because the display list automatically handles that for you. In fact, you can even use the same code for changing the depths of existing display objects.

Thus far you’ve either referenced display objects using instance names that have been applied on the Stage (through the Properties panel) or limited the dynamic creation of display objects to empty movie clips.

However, you will likely find a need to dynamically create and use instances of movie clips that already exist in your library. This process is nearly identical to creating and using empty movie clips, but one additional step is required: you must first set up the symbol first by adding a linkage class. In its most basic use, this is nothing more than a unique name that allows you to create an instance of the symbol dynamically.

To see this process, look at the companion source file addChild.fla. In the Library, you will find a unicycle. Select the movie clip in your library, then click the Symbol Properties button (it looks like an “i” at the bottom of the Library) for access to all the symbol properties.

In the resulting dialog, shown in Figure 6-10, enable the Export for ActionScript option and add Unicycle to the Class field.

You will also likely notice that Flash adds the MovieClip class (in this case) to the Base class field for you. This makes it possible to automatically access the properties, methods, and events available to the MovieClip class. For example, you can automatically manipulate the x and y coordinates of your new custom movie clip.

Now that you’ve given your movie clip a class name, you can create an instance of that custom movie clip class the same way you created an instance of the generic movie clip class. Instead of using MovieClip(), however, you will use Unicycle() to create the movie clip. The same call of the addChild() method adds the newly created movie clip to the display list.

var cycle:MovieClip = new Unicycle();
addChild(cycle);

Figure 6-10. Entering a class name for a movie clip in the library Linkage settings

The addChild() method adds the display object to the end of the display list, which always places the child on top of other display objects. In some cases, however, you may need to add a child at a specific position in the display list. For example, you may wish to insert an item into the middle of a vertical stack of display objects.

This example, found in the addChildAt.fla source file, adds a Library movie clip with the class name Ball to the start of the display list with every mouse click. The ultimate effect is that a new ball is added below the previous balls and positioned down and to the right 10 pixels every time the mouse is clicked.

1 var inc:uint = 0;
2
3 stage.addEventListener(MouseEvent.CLICK, onClick);
4
5 function onClick(evt:MouseEvent):void {
6     var ball:MovieClip = new Ball();
7     ball.x = ball.y = 100 + inc * 10;
8     addChildAt(ball, 0);
9     inc++;
10 }

Line 1 initializes a variable that will be incremented with each ball added. Line 3 adds an event listener to the Stage, listening for a mouse click, so that any mouse click will trigger the listener’s function. The function in lines 5 through 10 performs four basic tasks. In line 6, a new Ball movie clip is created.

Line 7 manipulates the x and y coordinates in a single instruction, setting x equal to y, which is equal to the value of an expression. This is handy when both x and y values are the same. In this case, the expression sets the new ball to x and y of 100 and adds a 10-pixel offset for each ball added. For example, when the first ball is added, inc is 0, so the additional pixel offset is 0*10, or 0. inc is incremented at the end of the function, in line 9. The next mouse click that calls the function will update the offset to 1*10, or 10, pixels for the second ball; 2*10, or 20, pixels offset for the third ball; and so on. Most importantly, line 8 adds the ball to the display list, but always at position 0, making sure the newest ball is always on the bottom.

Choosing when to use addChild() and when to use addChildAt() depends entirely on your needs. If you only need to add the display object to the display list, or if you want the object to appear on top of all other objects, use addChild(). If you need to insert the object anywhere below the top of the visual stacking order, use addChildAt() and specify a depth.

Any time you do specify a depth, the new object will be sandwiched between the surrounding objects, rather than overwriting whatever is in the specified depth. The display list can have no gaps in it, so everything above an insertion level is automatically moved up a notch in the list. For example, assume a file started with objects in levels 0 through 9 by virtue of adding 10 objects to the display list. Then assume you need to insert a new display object into level 5. All objects in levels 5 through 9 will automatically move up to levels 6 through 10 to accommodate the insert.

It’s equally important to know how to remove objects from the display list. The process for removing objects is nearly identical to the process for adding objects to the display list. To remove a specific display object from the display list, use the removeChild() method:

removeChild(ball);

To remove a display object at a specific level, use the removeChildAt() method:

removeChildAt(0);

The following example is the reverse of the addChildAt() script discussed in the prior section. It starts by using a for loop to add 20 balls to the stage, positioning them with the same technique used in the prior script. It then uses an event listener to remove the children with each click.

1 for (var inc:uint = 0; inc < 20; inc++) {
2     var ball:MovieClip = new Ball();
3     ball.x = 100 + inc * 10;
4     ball.y = 100 + inc * 10;
5     addChild(ball);
6 }
7
8 stage.addEventListener(MouseEvent.CLICK, onClick);
9 function onClick(evt:MouseEvent):void {
10     removeChildAt(0);
11 }

9      function onClick(evt:MouseEvent):void {
10        if (numChildren > 0) {
11    removeChildAt(0);
12    }
13    }

1 var ball:MovieClip = new Ball();
2 ball.x = 100;
3 ball.y = 100;
4 addChild(ball);
5
6 stage.addEventListener(MouseEvent.CLICK, onClick);
7
8 function onClick(evt:MouseEvent):void {
9     this.removeChild(ball);
10     //ball removed from display list but still exists
11     trace(ball);
12     ball = null;
13     //ball now entirely removed
14     trace(ball);
15
16     stage.removeEventListener(MouseEvent.CLICK, onClick);
17 }

Many of the example scripts in this chapter demonstrate working with children that have been previously stored in a variable. However, you will likely need to find children in the display list with little more to go on than their position or name.

Finding a child by position is consistent with adding or removing children at a specific location in the display list. Using the getChildAt() method, you can work with the first child of a container using this familiar syntax:

var dispObj:DisplayObject = getChildAt(0);

If you don’t know the location of a child that you wish to manipulate, you can try to find it by name using its instance name, instead of using the display list index. Assuming a child has an instance name of circle, you can store a reference to that child using this syntax:

var dispObj:DisplayObject = getChildByName("circle");

Finally, if you need to know the location of a display object in the display list but have only its name, you can use the getChildIndex() method to accomplish your goal.

var dispObj:DisplayObject = getChildByName("circle");
var dispObjIndex:int = getChildIndex(dispObj);

In the preceding discussion, you used DisplayObject as the data type when retrieving a reference to a display object, rather than another type, like MovieClip, for example. This is because you may not know if the child is a movie clip or another type of display object.

In fact, Flash may not even know the data type, such as when referencing a parent movie clip created using the Flash interface (rather than ActionScript). Without the data type information supplied in the ActionScript creation process, Flash sees only the parent Timeline as a display object container.

To tell Flash that the container in question is a movie clip, you can cast it as such; that is, you can change the data type of that object to MovieClip. For example, consider a movie clip created in the Flash Player interface that needs to tell its parent, the main timeline, to go to frame 20. A simple line of ActionScript is all that would ordinarily be required:

parent.gotoAndStop(20);

However, since Flash doesn’t know that gotoAndStop() is a legal method of the display object container (the Stage, for example, can’t go to frame 20, and neither can a sprite), you will get the following error:

Call to a possibly undefined method gotoAndStop
through a reference with static type flash.display:DisplayObjectContainer.

To tell Flash the method is legal for the main timeline, you need to state that the parent is of a data type that supports the method. In this case, the main timeline is a movie clip, so you can say:

MovieClip(parent).gotoAndStop(20);

This will prevent the error from occurring, and the movie clip will be able to successfully send the main timeline to frame 20.

There are specific advantages to using frame numbers with goto methods, including simplicity and use in numeric contexts (such as with a loop or other type of counter). However, frame numbers also have specific disadvantages. The most notable disadvantage is that edits that you make to your file subsequent to the composition of your script may result in a change to the frame sequence in your timeline.

For example, your help section may start at frame 100, but you may then insert or delete frames in a section of your timeline prior to that frame. This change may cause the help section to shift to a new frame, and your navigation script will no longer send the playback head to the help section.

One way around this problem is to use frame labels to mark the location of a specific segment of your timeline. As long as you shift content by inserting or deleting frames to all layers in your timeline, therefore maintaining sync among your layers, a frame label will move with your content.

For example, if your help section, previously at frame 100, is marked with a frame label called “help,” adding 10 frames to all layers in your Timeline panel will not only shift the help content, but will also shift the frame label used to identify its location. So, although you will still be navigating to the “help” frame label after the addition of frames, you will correctly navigate to frame 110.

This is a useful feature when you are relying heavily on timeline tweens for file structure or transitions, or when you think you may be adding or deleting sections in your file. In fact, frame labels free you to simply rearrange your timeline if desired. The capability to go to a specific frame label, no matter where it is, means that you don’t have to arrange your file linearly, and you are free to add last-minute changes to the end of your timeline without having to remember an odd sequence of frame numbers to jump to content.

The sample file, frame_labels_01.fla, demonstrates the use of frame labels instead of frame numbers when using a goto method. It also illustrates another important and useful concept, which is that you can use these methods to control the playback of movie clips as well as the main timeline.

Instead of controlling the playback of a linear animation, frame_labels_01.fla moves the playback head between the frames of a movie clip called pages. This is a common technique for swapping content in Flash because you can keep your main Timeline simple and just jump the movie clip from frame to frame to reveal each new screen. Figure 6-12 displays the “page1” frame of frame_labels_01.fla. The Timeline inset shows the frame labels.

Figure 6-12. The “page1” frame of frame_labels_01.fla

The initial setup of this example requires that you prevent the movie clip from playing on its own so that you can exert the desired control over its playback. There are several ways to do this. The first, and perhaps most obvious, approach is to put a stop() action in the first frame of the movie clip. You will see this technique used often.

The second is to add the stop() method to a main timeline script, but to target a movie clip instead of the main timeline. To do this, precede the method with the object you wish to stop, as shown in line 1 of the following script. In this case, you’re stopping the movie clip called pages.

You’ll look at a third method for stopping movie clips at the end of this chapter, but for now, let’s focus on the simple changes this file introduces. In addition to stopping the pages movie clip in line 1, this script adds listeners to buttons one, two, and three, which cause the movie clip to change frames in lines 8, 11, and 14, respectively.

1 pages.stop();
2
3 one.addEventListener(MouseEvent.CLICK, onOneClick);
4 two.addEventListener(MouseEvent.CLICK, onTwoClick);
5 three.addEventListener(MouseEvent.CLICK, onThreeClick);
6
7 function onOneClick(evt:MouseEvent):void {
8     pages.gotoAndStop("page1");
9 }
10 function onTwoClick(evt:MouseEvent):void {
11     pages.gotoAndStop("page2");
12 }
13 function onThreeClick(evt:MouseEvent):void {
14     pages.gotoAndStop("page3");
15 }

The code is essentially the same as the ActionScript you’ve seen before. To test the effectiveness of using frame labels, simply add or delete frames across all layers before one of the existing frame labels. Despite changing the frame count, you will find that the navigation still works as desired.

Also new to AS3 is the ability to dynamically change the frame rate at which your file plays at runtime. The default frame rate of a Flash CS4 movie is 24 frames per second. Previously, whichever frame rate you chose was the frame rate you were stuck with for the life of your SWF. It’s now possible to update the speed at which your file plays by changing the frameRate property of the stage, as demonstrated in the sample file frame_rate.fla.

This simple script increments or decrements the frame rate by 5 frames per second with each click of a button. You may also notice another simple example of error checking, in the function used by the slower button, to prevent a frame rate of zero or below. Start the file and watch it run for a second or two at the default frame rate of 24 frames per second. Then, experiment with additional frame rates to see how they change the movie clip animation.

1 info.text = stage.frameRate;
2
3 faster.addEventListener(MouseEvent.CLICK, onFasterClick);
4 slower.addEventListener(MouseEvent.CLICK, onSlowerClick);
5
6 function onFasterClick(evt:MouseEvent):void {
7     stage.frameRate += 5;
8     info.text = stage.frameRate;
9 }
10 function onSlowerClick(evt:MouseEvent):void {
11     if (stage.frameRate > 5) {
12         stage.frameRate -= 5;
13     }
14     info.text = stage.frameRate;
15 }

This frameRate property requires little explanation, but its impact should not be underestimated. Other interactive environments have long been able to vary playback speed, and this is a welcome change to ActionScript for many enthusiastic developers, especially animators. Be it for a Matrix parody or a sports game, slow mo has never been easier.

To begin, you wrote a script in Chapter 3 that animated the symbols created by the Deco tool (Figure 6-13).

Figure 6-13. Art created with the Deco tool in Chapter 3

The Deco tool quickly and automatically adds movie clips to a parent movie clip container, arranging the children in circular patterns. However, you did not give each of the child ovals instance names, so you might wonder how they can be controlled with ActionScript.

The answer is by using display list methods and properties. The script you entered in Chapter 3 uses the numChildren property to determine how many ovals are in the parent movie clip, and then loops through that number, gaining access to each child using the getChildAt() method. The combination of these tools makes it possible for the script to manipulate each oval individually.

1 ovals.addEventListener(Event.ENTER_FRAME, onEnter);
2 function onEnter(evt:Event):void {
3     var numOvals:int = ovals.numChildren;
4     for (var i:int = 0; i < numOvals; i++) {
5         ovals.getChildAt(i).rotation += 10;
6     }
7     ovals.rotation = mouseX;
8 }

Line 1 adds an enter frame listener to the parent movie clip, which has an instance name of ovals, which was applied through the Properties panel. Lines 2 through 8 comprise the listener function, onEnter(). This function includes the mandatory event argument, typed to the Event class, and returns no value.

Line 3 checks the number of children in the parent movie clip and places that integer into the numOvals variable.

Lines 4 through 6 contain a for loop that loops through those children one at a time. Each time through the loop, the child at the next highest level in the display list is rotated 10 degrees. That is, the first time through the loop, the loop counter is 0. As such, the child in the ovals movie clip that is at level 0 is rotated. The next time through the loop, the ovals child at level 1 is rotated, and so on.

After the for loop fully executes, the parent movie clip (not the individual oval-shaped children) is also rotated, this time to the same value as the x position of the mouse. The entire process is repeated every time the enter frame event is fired or, by default, 24 times per second.

This means that you can move the mouse left and right to control the rotation of the container movie clip. All the while, the individual ovals inside the container continue to rotate, contributing to an interesting visual effect.

In Chapter 5, you added a script to control the navigation of the portfolio project. With every click of a button, this script populates a variable and sets the portfolio in motion. A corresponding script then sends the playhead to the frame chosen by the button click, and a stop() action halts the playhead on the desired screen.

1 var nextSection:String;
2
3 navigation.home.addEventListener(MouseEvent.CLICK, onNavigate);
4 navigation.gallery.addEventListener(MouseEvent.CLICK, onNavigate);
5 navigation.lab.addEventListener(MouseEvent.CLICK, onNavigate);
6 navigation.help.addEventListener(MouseEvent.CLICK, onNavigate);
7
8 function onNavigate(evt:MouseEvent):void {
9     nextSection = evt.target.name;
10     play();
11 }

Line 1 creates the needed variable and types its data as a string of text.

Lines 3 through 6 add event listeners to the navigation buttons that sit within the navigation bar container. Each button calls the same function when a mouse click is detected.

Lines 8 through 11 define the listener function, which expects a MouseEvent and returns no value.

Line 9 parses the incoming event information to get the name of the target object that received the click, and then puts that name into the nextSection variable. The function then sets the playhead in motion.

At the end of the section, a separate frame script tells the playhead to go to the desired frame and play through the section so the transitions can complete their visual updates.

gotoAndPlay(nextSection);

Finally, after the transitions are complete, the playhead is stopped in the middle of the content frame span by another independent script:

stop();

The next chapter will introduce filters and blend modes, both of which you will apply to portfolio assets.