As an example of ActionScript 3.0’s strictness, consider one of programming’s most basic building blocks: variables. Since its introduction in ActionScript 1.0, the var keyword has been optional (but always recommended!) for timeline code. The following lines work just fine in a FLA file configured for ActionScript 1.0 or 2.0 and placed in a frame script:

lumps = 2;
trace("I'll have " + lumps + " lumps, please.");
// Displays: I'll have 2 lumps, please.

Ideally, this variable should be declared with the var keyword:

var lumps = 2;

but before ActionScript 3.0, the compiler can (and does) declare lumps automatically. While convenient on one level, this relaxed approach can lead to unexpected behavior. How? The var keyword does more than merely announce new arrivals; it defines variables in terms of a specific scope, which, in a few words, determines a variable’s “point of view,” its availability to other objects. Take a look at this revision (changes in bold):

function sample() {
    lumps = 2;
    trace(lumps); // Displays: 2
}
sample();

trace("I'll have " + lumps + " lumps, please.");
// Displays: I'll have 2 lumps, please.

Here, the lumps variable is declared and traced inside a custom sample() function, which is immediately called after the function is defined. This is followed by a second trace() statement outside the function that also references lumps. Because of the omission of the var keyword, both traces are successful, even if the developer’s intention is to keep this variable corralled to its function. Add a second function, and all three scopes can still see the variable:

function sample() {
    lumps = 2;
    trace(lumps); // Displays: 2
}
sample();

trace("I'll have " + lumps + " lumps, please.");
// Displays: I'll have 2 lumps, please.

function test() {
    trace(lumps); // Displays: 2
}
test();

This sort of spillover can be detrimental in cases where typical naming conventions overlap among numerous functions. For example, if a temporary string, str, is used to manipulate data in one function, havoc could ensue in another if the same variable name is used elsewhere. Think of how often n, i, or x are used to represent numeric values!

You’re much better off purposefully declaring a variable in its intended scope. If spillover happens to be the desired effect, it’s still possible ... it just depends on where the variable’s scope occurs. Note the output differences in these revisions. In the first example, the variable is only available to one function; in the second, the variable is available to two functions and the timeline. First, when lumps is scoped to the sample() function:

function sample() {
    var lumps = 2;
    trace(lumps); // Displays: 2
}
sample();

trace("I'll have " + lumps + " lumps, please.");
// Displays: I'll have undefined lumps, please.

function test() {
    trace(lumps); // Displays: undefined
}
test();

Second, when it’s scoped to the main timeline:

var lumps = 2;

function sample() {
    trace(lumps); // Displays: 2
}
sample();

trace("I'll have " + lumps + " lumps, please.");
// Displays: I'll have 2 lumps, please.

function test() {
    trace(lumps); // Displays: 2
}
test();

To underscore the notion of ActionScript 2.0 as a transitional language, consider that undeclared variables aren’t allowed in classes, even if they do sneak by in timeline code. When compiled, this no-frills ActionScript 2.0 class generates a compiler error, “There is no property with the name ‘lumps’.”:

class Sample {
    public function Sample() {
        lumps = 2;
        trace("I'll have " + lumps + " lumps, please.");
    }
}

You can address this error by preceding the lumps variable with the var keyword, which scopes it to the class’s constructor function, Sample(), or by declaring the variable as a class property, which scopes it to the whole class, available to any method:

class Sample {
    private var lumps:Number;
    public function Sample() {
        lumps = 2;
        trace("I'll have " + lumps + " lumps, please.");
        demo();
    }
    private function demo():Void {
        trace(lumps); // Also available here
    }
}

In ActionScript 3.0, FLA files, as a whole, are associated with something called a document class, which defines the main timeline’s functionality. While you may optionally write your own document class, you certainly don’t have to. By default, the compiler automatically generates one for you. This default document class is called MainTimeline and extends the MovieClip class. On the surface, nothing has changed. The main timeline is still a movie clip, as it always has been, but under the hood, a new structure is in place. The main timeline is now defined by a class, which means that even timeline variables must be formally declared, just as they were in ActionScript 2.0 classes.

In an ActionScript 3.0 FLA file, the following, now-familiar keyframe script generates the compiler error “1120: Access of undefined property lumps” because of the missing var keyword:

lumps = 2;
trace("I'll have " + lumps + " lumps, please.");

Adding var corrects the situation:

var lumps = 2;
trace("I'll have " + lumps + " lumps, please.");

Holding to a stricter standard encourages you to give more thought to the code you write. Variables are just the beginning.

In ActionScript 2.0, all classes and functions in the Flash Player API were global. These classes were aimed specifically at functionality provided by the Flash Player runtime, over and above the core functionality outlined in the ECMAScript specification. In this free-for-all, if you wanted to refer to the MovieClip class in your code, you could do so without using an import directive, even inside a custom class. An obvious benefit is that you could save a bit of typing:

import MovieClip; // This line is not needed,
                  // because the MovieClip class
                  // is already understood
var mc:MovieClip = this.createEmptyMovieClip("myClip", 0);

In ActionScript 3.0, only core classes are considered global, in the sense that they belong to the top level of the overhauled packages hierarchy. Packages are an organizational means of arranging classes into groups, usually based on similar functionality. The lion’s share of ActionScript 3.0 classes is now arranged into such packages. The remainder, global functions and core classes, is listed under the All Packages→Top Level classes topic in the ActionScript 3.0 Language and Components Reference.

As with ActionScript 2.0, top-level classes don’t require the import directive—either in timeline code or custom classes—but in contrast to how it used to be, MovieClip is now categorized under flash.display.MovieClip, and must be imported when used in external class files:

package {
    public class SampleClass {
        import flash.display.MovieClip;
        public function SampleClass() {
            var mc:MovieClip = new MovieClip();
            // Additional code here ...
        }
    }
}

In frame scripts, classes in the flash package join top-level classes in not requiring an import compiler directive. This line, for example, works just fine on its own in an ActionScript 3.0 frame script:

var mc:MovieClip = new MovieClip();

The concepts of packages and importing are discussed in greater detail in the section Major Syntax and Structure Changes in this chapter. The subject is worth touching on at this point, however, because it helps prepare you for the massive organizational shift you’ll find in the documentation’s ActionScript 2.0 Migration table. This new structure’s benefit may not be self evident, but it does reinforce a developer’s motivation to program with purpose.

Here’s an example of how the new packages arrangement can lead to better focus. Before ActionScript 3.0, you had numerous ways to load external assets into a SWF file. The loadMovie() function was among the first and is still in surprisingly wide use in ActionScript 2.0, as indicated by Adobe support forum questions. In the beginning, this function was capable only of loading external SWF files, but this changed as successive versions of Flash Player added support for other dynamically loadable file types, including JPEG, GIF, and PNG. Note that a hint of potential confusion has already raised its head for newcomers: this function, loadMovie(), expressly alludes to a “movie.” This is a term commonly used to describe SWF files, but doesn’t suggest support for images, even though loadMovie() easily loads image files in recent versions of Flash Player. ActionScript 3.0 helps clear up such pitfalls in semantics.

Consider the following code exercises from the standpoint of an evolutionary journey—a journey that, comparatively speaking, begins in somewhat ambiguous terms and develops into ActionScript that more clearly states its purpose.

On the face of it, the URLRequest class, seen in the previous example, acts as nothing more than a container for storing file locations. It seems to be a five-dollar way of saying “sample.png,” much like “salutations” is a five-dollar way of saying “hello.” So what’s the point? Is URLRequest really necessary? What was wrong with the simple string approach of earlier functions and classes? To answer these questions, think again of the overhauled ActionScript 3.0 packages structure.

Before ActionScript 3.0, the MovieClip class supported a loadMovie() method, which was practically equal in purpose to the standalone loadMovie() function. Wait a minute! Were there formerly two versions of loadMovie()? There were. This sort of redundancy was frequent in older ActionScript. There were also two versions of gotoAndPlay()—both function and method—and many others, besides. This duplication was introduced in Flash 5, when the MovieClip class began taking ownership of movie-clip–related functionality. Longstanding functions became MovieClip methods overnight, yet the function versions remained for backward compatibility.

The trouble is, this duplication sometimes went too far. The loadMovie() method, especially, is a case in point. Because the MovieClip class defines movie clip objects, these objects should certainly be able to do the things a movie clip symbol can do: display animated timelines, move around the stage, change dimensions, and so on—but the act of loading is a categorically distinct discipline.

It makes good sense to coordinate the traits and functionality of loading into an object that specializes in the field, so to speak. In ActionScript 3.0, precisely this sort of thoughtful arrangement has occurred. As a subject matter expert on loading, the Loader class should indeed feature an impressive array of loading related skills. In this light, it’s not surprising that Loader should work in collaboration with a subject matter expert on HTTP requests, which is what the URLRequest class is. More than just a fancy way of describing file locations, URLRequest objects have the potential to manage an HTTP request’s header, its method (GET versus POST), its POST data, MIME content type, and so on.

This sort of rich granularity is echoed throughout the ActionScript 3.0 API. For example, in the previous code exercise, the event handler was associated with the Loader.contentLoaderInfo property of the myLoader instance. As it happens, this property points to an instance of yet another class, LoaderInfo, which specifically manages byte data and other information about SWF files and image files. This class’s skill set paves the way for the bytesLoaded and bytesTotal properties used by the progress event handler. Again, each step is categorized neatly.

This sort of approach wasn’t unheard of, by the way, in older versions of ActionScript. It just wasn’t as prevalent. The TextFormat class, for example, compartmentalizes formatting from the text fields it collaborates with (relevant code in bold).

// ActionScript 2.0
var tf:TextField = this.createTextField("sampleText", ¬
     0, 10, 50, 100, 20);
tf.selectable = false;
tf.autoSize = "center";

var styling:TextFormat = new TextFormat();
styling.font = "Blackadder";
styling.color = 0xBA1424;
styling.letterSpacing = 1.5;

tf.setNewTextFormat(styling);
tf.text = "Cooperation!";

For good measure, here are another two examples that show how ActionScript 3.0 expands on this sort of helpful compartmentalization.

In ActionScript 1.0 and 2.0, the MovieClip class featured a handful of methods collectively known as the Drawing API. You could reference a movie clip directly by its instance name and invoke, say, lineTo() and curveTo() to draw shapes at runtime. In ActionScript 3.0, this same Drawing API has been reallocated to a more suitable Graphics class, which is now associated with movie clips by way of the MovieClip.graphics property:

// ActionScript 2.0
myClip.lineTo(300, 200);

// ActionScript 3.0
myClip.graphics.lineTo(300, 200);

In ActionScript 3.0, the Sound class collaborates with three new classes—SoundChannel, SoundTransform, and SoundMixer—to manage audio-related functionality. These duties were previously consigned to the Sound class alone. Previously, the concept of sound channels was managed by a non-intuitive association between a Sound instance and a movie clip. In order to separate audio into individual “channels,” you had to feed individual movie clip instance names to each use of the new Sound() constructor. It was an easy procedure to miss, and developers often wondered why adjusting the volume of one Sound instance affected the volumes of others. Now, the improved, decentralized functionality calls on specialized companion classes as needed.

// ActionScript 2.0
var mySound:Sound = new Sound();
mySound.loadSound("music.mp3", true);
mySound.setVolume(50);
mySound.stop();

// ActionScript 3.0
var mySound:Sound = new Sound();
mySound.load(new URLRequest("music.mp3"));

var myChannel:SoundChannel = mySound.play();
var myTransform:SoundTransform = myChannel.soundTransform;

myTransform.volume = 0.5;
myChannel.soundTransform = myTransform;
myChannel.stop();

By delegating functionality to numerous classes, the new API keeps its objects lean and focused. MovieClip instances are no longer burdened with loading tasks or the Drawing API, but all the same, are easily associated with companion classes that handle those duties. The concept goes even further: if you want some of the basic characteristics of a movie clip but don’t need internal animation—that is, if you don’t need to shuttle around a movie clip’s playhead with gotoAndPlay()—then you now have the option of using the Sprite class instead, which doesn’t carry the overhead of a timeline. Ultimately, this makes your tools more refined, giving you functionality that suits the object at hand, and leaving the extra tasks to other objects.

It is no longer possible to attach event handlers directly to objects, such as movie clips, buttons, and components. This is a significant change, because on() and onClipEvent() have been popular for years. Using direct attachment, you could previously program a button to respond to a mouse click, for example, by selecting the button symbol on the stage, opening the Actions panel, and then typing something like this:

on (release) {
  // Desired code here
}

This was optional as recently as ActionScript 2.0—an alternate approach to referencing event handlers by instance name. In ActionScript 3.0, the object in question must have an instance name, which is what uniquely identifies that symbol or component as something ActionScript can speak to. In contrast, direct attachment didn’t require instance names because the intended recipient of your instruction was self-evident.

You can supply an instance name to an object by selecting it on the stage, and then typing the instance name into the Property inspector. Assuming an instance name myButton, here’s how ActionScript 3.0 associates the occurrence of a mouse release with a function to be trigged by that occurrence:

myButton.addEventListener(MouseEvent.MOUSE_UP, function);

If you think of the Timeline as a grid, this code appears in a frame script that aligns vertically in the same “column”—the same frame—as the button it refers to. The term function in the previous line of code refers to an actual function definition, such as the following arbitrarily named mouseUpHandler():

myButton.addEventListener(MouseEvent.MOUSE_UP, ¬
    mouseUpHandler);

function mouseUpHandler(evt:MouseEvent):void {
    // Desired code here
}

The evt parameter refers to an instance of the MouseEvent class, which features numerous useful properties you can optionally reference inside the function. To find out what events are available for a button symbol, look up the SimpleButton class in the ActionScript 3.0 Language and Components Reference. Click the “Show Inherited Events” hyperlink in the Events section, and take your pick. One of these is mouseUp, and if you click on that, the Help panel shows that the mouseUp event belongs to the MouseEvent class and is referenced with the MouseEvent.MOUSE_UP constant. (A constant is simply a variable whose value doesn’t change. Many classes store properties and events as constants in this way. By using the constant, instead of the string “mouseUp”, you gain the benefit of code coloring to show you’ve entered the right code.) In the same way, the MovieClip class entry indicates what events are available for movie clips, the ComboBox class shows events for the ComboBox component, etc.

These functions still show up in hundreds of online tutorials, but they’re no longer supported. Ever since ActionScript 1.0, their purpose has been simplified by dot notation. Consider a movie clip symbol with the instance name myClip. To set its width using setProperty(), you would refer to the instance name like this:

setProperty(myClip, _width, 200);

The updated approach is much easier on the eye (note the change from _width to width):

myClip.width = 200;

The procedure for pulling assets from the library at runtime has changed. It still requires linkage information, but instead of a linkage identifier, ActionScript 3.0 requires a linkage class, which is designated by the same Symbol Properties dialog box you’re used to. Right-click (Ctrl-click) on an asset in the library, and then choose Properties. When the dialog box opens, click the Advanced button if it’s showing. This expands the Symbol Properties dialog box to its full extent. Select Export for ActionScript, and then enter a name into the Class field, as shown in Figure 3-1 (note that the Identifier field is disabled).

Rather than invoking attachMovie() or attachSound() on a related MovieClip or Sound instance, the library asset is attached by way of the new operator:

var mc:myClip = new myClip();

Visual objects, like movie clips and graphics, are then added to the display list, which manages a SWF file’s visual objects:

addChild(mc);

Figure 3-1. Specifying linkage properties

In similar fashion, the MovieClip and TextField classes can now be instantiated directly with the new operator. In both cases, the resultant objects must be added to the display list.

// ActionScript 2.0
var mc:MovieClip = this.createEmptyMovieClip("myClip", 0);

// ActionScript 3.0
var mc:MovieClip = new MovieClip();
mc.name = "myClip"; // traditional instance name
addChild(mc);

In the ActionScript 2.0 version, the MovieClip.createEmptyMovieClip() method is invoked on a timeline with the global this property, but that could be replaced with any valid movie clip reference, which would then become the immediate parent of the new MovieClip instance. The Property-inspector–style instance name (the string "myClip") is a required parameter, as is the second parameter, depth, which here happens to be 0 (the lowest depth). Because createEmptyMovieClip() returns a movie clip reference, the new instance can be referred to in subsequent code either by the myClip instance name or the mc variable.

In the ActionScript 3.0 version, depth is handled automatically (no depth parameter is required) and the Property-inspector–style instance name is optional, as the new object can, in any case, be referenced by the mc variable.

The eval() function crops up often in legacy code and in many online tutorials. In older ActionScript, it was used to evaluate expressions as variables, properties, or objects. When a variable or property name was evaluated, its value was returned. When an object name or reference was evaluated, a new reference to that object was returned. One typical use of eval() was to iterate through sequentially named movie clip instances using a for loop. Here, three movie clips with the instance names mc0, mc1, and mc2 are conveniently set to a horizontal position of 200 all at once:

// ActionScript 2.0
for (var i:Number = 0; i < 3; i++) {
    eval("mc" + i)._x = 200;
}

While eval() is no longer available in ActionScript 3.0, the bracket notation approach to the same task, using the array access operator ([]), still works:

// ActionScript 3.0
for (var i:int = 0; i < 3; i++) {
    this["mc" + i].x = 200;
}

Bracket notation requires that an object reference precede the array access operator. In this case, the object reference is this, which refers to the timeline in which these movie clips appear. If the three movie clips were nested inside the timeline of another movie clip with the instance name container, then the same ActionScript 3.0 for loop would look like this:

for (var i:int = 0; i < 3; i++) {
    container["mc" + i].x = 200;
}

You can iterate through movie clips with an object reference, in which a variable points to a given MovieClip instance, or by Property-inspector–style instance name (that is, the MovieClip._name property in ActionScript 2.0 and the MovieClip.name property in ActionScript 3.0). In ActionScript 3.0, array access operator iteration through MovieClip.name property values only succeeds when those instance names are provided by hand using the Property inspector. The MovieClip.name property indicates the movie clip’s instance name, but is not synonymous with it, as was the case with ActionScript 2.0’s MovieClip._name property. If you prefer to iterate through MovieClip.name values generated by code, make sure to use the DisplayObjectContainer.getChildByName() method to locate those name values in the display list later:

for (var i:int = 0; i < 3; i++) {
    var mc:MovieClip = new MovieClip();
    mc.name = "mc" + i;
    this.addChild(mc);
}

for (i = 0; i < 3; i++) {
    mc = MovieClip(this.getChildByName("mc" + i));
    mc.graphics.lineStyle(3, 0xFF0000);
    mc.graphics.lineTo(0, 20);
    mc.x = 20 * i;
    // Locates dynamically generated movie clips
    // by name property and draws a short vertical
    // line in each
}

You can alternately use the DisplayObjectContainer.getChildAt() method to locate display objects by their index number in a given display list. Both of these methods can be invoked on the main timeline or on movie clips because the MovieClip class inherits from DisplayObjectContainer. Note, however, that the return value of both methods is typed as DisplayObject. For this reason, you may need to cast the return value as MovieClip, as shown in the previous example (MovieClip(object) or object as MovieClip)—otherwise the compiler will not let you to reference MovieClip-specific members, such as currentFrame or scenes.