You can perform testing, in its most basic form, by the simple act of running a SWF file in the Flash authoring tool (Control→Test Movie, or Control→Test Scene). If invalid code causes the compiler concern, it alerts you by sending an announcement to the Compiler Errors panel. This alert occurs without any effort on your part. In fact, errors brought to light in this way are the sort that keep a SWF file from compiling in the first place, so a user never sees this category of errors.

The Compiler Errors panel gives you a brief description of each error, and lets you know where to find it, including relevant asset names and scene, layer, frame, and line numbers. For more information on this panel, see the section Exploring the Compiler Errors Panel later in this chapter.

The Flash authoring tool lets you configure the degree to which the Compiler Errors panel displays its messages. This is determined by a pair of modes called Strict Mode and Warnings Mode, which can be set on a per-FLA file basis under File→Publish Settings→Flash→Settings.

Once a SWF file compiles, it is finally capable of trying to carry out the instructions you’ve given it. Even so, your technically valid code may not be written according to the recommended best practices of Adobe. As an example, consider type declaration, which is optional in ActionScript 3.0. It’s possible and valid to declare variables without including a post colon suffix:

// type declared
var worthANickel:int = 5;

// type not declared
var worthADime = 10;

However, omitting the type declaration keeps you from benefiting from ActionScript 3.0’s improved efficiency in Flash Player 9 and higher. For example, in ActionScript 3.0, the int type (a 32-bit signed integer) takes up less system memory than the Number type (a 64-bit double precision non-integer). If you choose to refrain from explicitly specifying a variable’s data type, Flash has no choice but to request as much memory as it reasonably can, on the chance that the variable might be a string, a date, or some other object that requires more RAM. For this reason alone, although type declarations are not required, they’re definitely a good idea. Compiler warnings provide a good reminder of recommended best practices like this one, and they also appear in the Compiler Errors panel.

In addition, some of these warnings are geared toward developer education. Certain programming concepts, sometimes specific to ActionScript, seem intuitive right away, while others may sink in only after months of experience. For example, the default value of many data types is null; that is, variables that have been declared and include type declarations but have not yet been assigned a value.

var str:String;
trace(str); // Displays: null

var d:Date;
trace(d); // Displays: null

var mc:MovieClip;
trace(mc); // Displays: null

If you compare any of these to null with an if statement, the expression evaluates to true:

var str:String;
if (str == null) {
    trace("default value is null");
} else {
    trace("default value is something else");
}
// Displays: default value is null

If you’re new to Flash programming, you might assume that the default value for all data types is null, but as it turns out, instances of Boolean, int, uint, and Number are by default false, 0, 0, and NaN (Not a Number), respectively.

In the following example, the comparison of the default value of a Boolean to null is actually interpreted as false:

var b:Boolean;
if (b == null) {
    trace("default value is null");
} else {
    trace("default value is something else");
}
// Displays: default value is something else

In practice, this means your ActionScript might not always behave as you had intended. Many compiler warnings help steer you in the right direction.

Finally, a number of compiler warnings relate specifically to ActionScript 2.0–3.0 migration issues. You may consider these Help docs migration warnings a collection of freebie insider tips!

Runtime errors occur, by definition, at runtime—in other words, after a SWF file has passed the rounds of compiler errors and warnings. Because of this, runtime errors are often a bit harder to track down than the sort described earlier. After all, the ActionScript involved has already passed the test: it’s valid, and has already been converted to bytecode. At that point, the scenes, layers, and line numbers shown in compiler errors and warnings are effectively meaningless. For this reason, notifications of runtime errors do not (cannot!) provide an X-marks-the-spot treasure map to erroneous ActionScript. In fact, the code itself might actually be just fine. The culprit may well be a malformed external file. Don’t let that alarm you, though. While not as precise as compiler errors and warnings in terms of location, runtime error messages do try to show where they originated.

Figure 11-1 shows an example error in which a SWF file attempts to load an XML document that provides file data for a slideshow. In this case, the ActionScript is correct; it’s the XML that contains an error (one of the elements, <slide>, is missing its matching end-tag, </slide>). Because this SWF file is being tested in the Flash authoring tool, the runtime error is displayed in the Output panel.

Figure 11-1. A runtime error, displayed in the Output panel

Helpfully, this message indicates that the trouble happened during the execution of a function named loadHandler() in the main timeline, as seen in the first line that starts with the word “at.” Further hints—the mention of EventDispatcher and URLLoader/onComplete()—suggest that loadHandler() is an event handler. These are all signposts that should at least give you a head start as you re-examine your source files. Given the error’s description, “the element type ‘slide’ must be terminated...,” and the hints on where to look, you have considerably more information to go on than in previous versions of Flash, which provided only compiler errors and warnings.

To a certain extent, runtime errors are only as helpful as your naming conventions and coding practices. For example, the ActionScript that loads the XML in Figure 11-1 might look something like this:

var myXML:XML = new XML();
var xmlLoader:URLLoader = new URLLoader();
xmlLoader.load(new URLRequest("slideshow.xml"));
xmlLoader.addEventListener(Event.COMPLETE, loadHandler);

That last line of code associates a custom function, loadHandler(), with an Event.COMPLETE event. This event is dispatched when the xmlLoader instance finishes loading the slideshow.xml file. The loadHandler() function might look like this:

function loadHandler(evt:Event):void {
    myXML = XML(evt.target.data);
    myComboBox.dataProvider = new DataProvider(myXML);
}

There’s certainly nothing wrong with that function—it’s valid ActionScript—but because the error message mentions loadHandler() by name, you know where to find it in the source file’s frame script. The lack of any obvious errors in the function itself may nudge you into looking at the XML file, where the error actually occurs.

In this scenario, the warning message’s guidance is helpful because loadHandler() is defined as a named function. This event handler might just as well have been written as a function literal, also known as an anonymous function, in which the function’s code appears directly as a parameter of addEventListener() (changes in bold):

var myXML:XML = new XML();
var xmlLoader:URLLoader = new URLLoader();
xmlLoader.load(new URLRequest("slideshow.xml"));

xmlLoader.addEventListener(
    Event.COMPLETE,
    function (evt:Event):void {
        myXML = XML(evt.target.data);
        myComboBox.dataProvider = new DataProvider(myXML);
    }
);

If so, the runtime error inevitably becomes less clear, simply because the event handler function no longer has a name.

TypeError: Error #1085: The element type "slide" must be
    terminated by the matching end-tag "</slide>".
    at MethodInfo-392()
    at flash.events::EventDispatcher/dispatchEventFunction()
    at flash.events::EventDispatcher/dispatchEvent()
    at flash.net::URLLoader/onComplete()

This time, the function formerly known as loadHandler() is referenced as MethodInfo-392(). Cryptic? Perhaps. The compiler automatically assigns a name to the anonymous function. Ultimately, everything must have a reference, so Flash does what it needs to in order to keep track of the instructions you’ve given it. Bear this trait in mind as you program, and avoid anonymous functions if you want to improve the clarity of your error messages.

The trace() function bears some similarity to good old low-tech paper sticky notes. Regardless of how powerful (and portable) PDAs and cell phones have become, replete with programmable reminders, alarms, and automated email dispatches, nothing beats the convenience of those stick-anywhere yellow notes. They’re lightweight, informative, and reusable. Likewise, the trace() function makes a terrific and uncomplicated tool.

In short, the trace() function sends information to the Output panel. The information it sends is entirely up to you. Doing so is as easy as passing an expression to the function as a parameter. To ensure that a button is responding to mouse clicks, for example, you might pass in a simple confirmation string.

myButton.addEventListener(MouseEvent.CLICK, onClick);
function onClick(evt:MouseEvent):void {
    trace("This button is working!");
}

Of course, you’re not limited to strings. The trace() function is great for bringing all sorts of things to light, from the current value of a custom variable to the contents of an XML node; from the position of a movie clip (for example, the MovieClip.x property) to an object’s data type when used with the is operator.

var s:Sprite = new Sprite();
trace(s is Sprite); // Displays true
trace(s is Number); // Displays false

Be aware that trace() always outputs a string, no matter what expression you feed it. When passed any object, the function essentially invokes the Object.toString() method defined for that object (remember, all objects in ActionScript inherit from the Object class, which means all objects have a toString() method).

So, has anything changed for this elementary debugging tool in ActionScript 3.0? The answer is yes, even though it’s a small update. Sometimes it’s the little things that can make your day! The trace() function now accepts multiple parameters, separated by commas. If you’re heavily into using trace(), this can save you a degree of typing.

var n:Number = 42;
var b:Boolean = true;
var d:Dictionary = new Dictionary();
trace(n, b, d); // Displays 42 true [object Dictionary]

In previous versions of ActionScript, the same output would have required a bit of string wrangling:

trace(n + " " + b + " " + d);
// Displays the same, but tedious to type

Runtime errors are available only in ActionScript 3.0, which means they’re available only as of Flash Player 9. Returning to the example shown earlier (Figure 11-1), if the same SWF file is embedded in an HTML document and viewed in a browser, the error message appears in a dialog box presented to the user, as shown in Figure 11-2. In ActionScript 2.0 or 1.0, something like this would likely have failed silently—meaning, the user may have seen partial elements of the user interface, but none of the slideshow photos. In fact, in such a scenario, it might not even be absolutely clear that something has gone wrong. The website may simply come across as incomplete or abandoned. ActionScript 3.0 fixes that. Because runtime errors are visually obvious—that dialog box is hard to miss!—the developer sees and addresses errors before the SWF file goes public.

Figure 11-2. A runtime error, displayed in a browser

Double-clicking a Compiler Errors panel line item is the quickest route to accessing and fixing problematic code. Here’s a quick example.

Admittedly, the numbers assigned to compiler errors, warnings and runtime errors aren’t self-explanatory. Compiler errors range from 1000 to 1209, warnings from 1009 to 3607, and runtime errors from 1000 to 2157. The numbers are completely arbitrary (at least, to non-Adobe employees), so you can’t easily group them by some pattern or mnemonic device, such as, “Ah, those 1-800 phone numbers are the toll free ones.” While you may eventually find yourself recognizing the numbers of a handful of your own pet errors, the bottom line is that you’ll want to pay attention to their descriptions. As a note of encouragement, even if the numeric assignments don’t have much inherent meaning, they’re great for using as search terms at the Adobe website, Google, and your favorite tech blogs.

These errors and warnings are listed in the ActionScript 3.0 Language Reference (search Help for “compiler errors,” “compiler warnings,” and “run-time errors”). Skim through the documentation’s Code Message heading for any of these terms, and you’ll see that for the most part, the messages themselves are fairly straightforward. True, not all of them necessarily make sense when they occur. That trait is demonstrated later in this chapter with “Compiler Error: 1037: Packages cannot be nested.” But even that message comes together after an explanation, and a fair number of errors and warnings feature a Description heading in the same table that shows the Code Message heading. The content of that Description column, when it does appear, may overlap with the Description column of the Compiler Errors panel. Even so, it often elaborates, including code samples.

One of the most helpful things you can bear in mind when interpreting errors and warnings is that ActionScript 3.0 is an object-oriented language—this version more so than any other. The ActionScript 3.0 Language and Components Reference is neatly organized into a structure that matches the hierarchy of the application programming interface (API) of Flash itself; in other words, in a structure that matches the very composition of the language. If an error or warning mentions a class file you don’t think you’re using, look up that class and investigate its placement in the class hierarchy (essentially a family tree). You might, for example, see a compiler error concerning the DisplayObject class, even though you suspect the issue is related to a button symbol. As Figure 11-6 shows, the DisplayObject class listing, like all class listings, shows a collection of hyperlinks just below the main heading.

Figure 11-6. A class listing in the ActionScript 3.0 Language Reference

These links include Package, Inheritance, and Subclasses. The Package heading tells what major branch of the API this class belongs to (in this case, the flash.display package). The Inheritance heading tells what classes this class inherits from. Here, it’s easy to see that all DisplayObject objects are also instances of EventDispatcher—they feature all the functionality of that class, plus functionality of their own—and are also instances, ultimately, of the Object class. The Subclasses heading tells what classes further extend this class by inheriting from it. In this hypothetical scenario, you’re looking for something that seems like a button, because your hunch tells you a button symbol is at fault. Of the choices shown, InteractiveObject seems like the best bet. Certainly, it won’t always be this easy, but be sure to always let your fingers do the walking through the documentation.

The documentation is the closest resource and often the quickest way to find your bearings. Clicking InteractiveObject brings you to the listing for that class, whose own Subclasses heading includes an entry called SimpleButton, which in fact is the class that defines button symbols.

Coming from any level of ActionScript 2.0 experience, you may find yourself “stuck” with old habits that were perfectly fine before, perhaps even recommended best practices. New syntax changes things. Some changes are relatively obvious, because they get abundant coverage in the Adobe Developer Connection (http://www.adobe.com/devnet/); the improved ActionScript 3.0 event handling model comes to mind. Other changes may show up on your doorstep at midnight unannounced, pushing their way past you to the fridge, thanking you in advance for a place to crash—through mouthfuls of your last leftover pizza. Here’s a list of some of most common gate-crashers.

Compiler Error: 1037: Packages cannot be nested.

var codeSample:ExampleCode = new ExampleCode();

package {
    import flash.display.Sprite;
    import flash.display.CapsStyle;
    import flash.display.LineScaleMode;
    public class Graphics_moveToExample extends Sprite {
        public function Graphics_moveToExample():void {
            graphics.lineStyle(3, 0x990000, 0.25, false, ¬
                 LineScaleMode.NONE, CapsStyle.SQUARE);
            graphics.moveTo(10, 20);
            graphics.lineTo(20, 20);
            graphics.moveTo(30, 20);
            graphics.lineTo(50, 20);
            graphics.moveTo(60, 20);
            graphics.lineTo(80, 20);
            graphics.moveTo(90, 20);
            graphics.lineTo(110, 20);
            graphics.moveTo(120, 20);
            graphics.lineTo(130, 20);
        }
    }
}

function Graphics_moveToExample():void {
    graphics.lineStyle(3, 0x990000, 0.25, false, ¬
         LineScaleMode.NONE, CapsStyle.SQUARE);
    graphics.moveTo(10, 20);
    graphics.lineTo(20, 20);
    graphics.moveTo(30, 20);
    graphics.lineTo(50, 20);
    graphics.moveTo(60, 20);
    graphics.lineTo(80, 20);
    graphics.moveTo(90, 20);
    graphics.lineTo(110, 20);
    graphics.moveTo(120, 20);
    graphics.lineTo(130, 20);
}
Graphics_moveToExample();

// Assumes a movie clip symbol with the instance name mcBox
mcBox._x = 400; // Displays compiler warning

Compiler Warning: 1058: Migration issue: The property _x is no
longer supported. Use the DisplayObject.x property instead.

ReferenceError: Error #1056: Cannot create property _x on flash.display.Sprite.

mcBox.x = 400; // Updates movie clip's horizontal position

// Last keyframe of a movie clip symbol in the main timeline
this.parent.play();

Compiler Error: 1061: Call to a possibly undefined method play
    through a reference with static type flash.display: ¬
     DisplayObjectContainer.

// Last keyframe of a movie clip symbol in the main timeline
(this.parent as MovieClip).play();

MovieClip(this.parent).play();

for (var i:int = 0; i < someUpperLimit; i++) {
    // loop code here
}
// Displays compiler error
for (var i:int = 0; i < someArray.length; i += 2) {
    // loop code here
}
Compiler Error: 1151: A conflict exists with definition
    variable name in namespace internal (or relevant namespace).

Compiler Warning: 3596: Duplicate variable definition.

for (var i:int = 0; i < someUpperLimit; i++) {
    // loop code here
}
for (i = 0; i < someArray.length; i += 2) {
    // loop code here
}

if (someUndeclaredVariable) { // Displays compiler error
    // variable exists
} else {
    // variable does not exist
}

// Displays compiler error
if (someOtherUndeclaredVariable != null) {
    // variable exists
} else {
    // variable does not exist
}

Compiler Error: 1120: Access of undefined property variable name.

var aNullObject:Object; // Declared, but not given a value
if (aNullObject.someProperty) { // Runtime error
    // property exists
} else {
    // property does not exist
}

TypeError: Error #1009: Cannot access a property or method 
of a null object reference.

var aNullObject:Object; // Declared, but not given a value
if (aNullObject && aNullObject.someProperty) {
    // property exists
} else {
    // property does not exist
}

var aNullObject:Object;
try {
    if (aNullObject.aProperty) {
        // property exists
    }
} catch (e:Error) {
    // property does not exist
    trace("Caught error: " + e);
} finally {
    // trace("bad reference!");
}

How do you eat an elephant? One bite (or maybe one byte!) at a time. This adage has been a gentle encouragement since Lao Tzu first rendered it as The journey of a thousand miles begins with one step. In short, and in terms of programming, it speaks to breaking down large problems into smaller components, and then repeating the process until the first step (or first bite) becomes clear. In development environments, that first step, no matter how long the journey, tends to be easier when it’s small. Remember, testing early and testing often helps to keep you from getting overwhelmed.

When you do encounter an error or warning you truly can’t make heads or tails of, your situation is ready for troubleshooting. Troubleshooting is a “divide and conquer” approach to problem solving, in which your main aim as a developer is to isolate potential sources of the trouble at hand and, by a process of elimination, find the actual causes and fix them. The trace() statement, mentioned earlier in this chapter, is a good entry point into the troubleshooting process. Two other tools, the Compiler Errors panel and Output panel, are just as important and may be the instruments that alerted you to the trouble in the first place. The most powerful tool in your arsenal is the mechanism that lets you see into a SWF file’s inner workings at runtime. It’s called the debugging workspace, and it’s only available for ActionScript 3.0 documents.

In ActionScript 3.0 FLA files, debugging is possible only with documents that actually contain ActionScript. That trait may seem self-evident, but the ActionScript 2.0 Debugger panel can be displayed regardless of the presence or absence of code. If you select Debug→Debug Movie for a codeless ActionScript 3.0 file, you see an alert box warning: “You cannot debug this SWF because it does not contain ActionScript.” Can’t argue with that.

To demonstrate the debugging environment, you need a bit of code. The slightest smattering will do.

Figure 11-9. A very basic debugging session

Breakpoints

In order to get the most out of a debugging session, you need to add breakpoints. A breakpoint is a special toggle that lets you pause the execution of code inside a SWF file. Breakpoints are easy to add, both to timeline or external ActionScript. Just locate the desired line number, and then click to the left of it, in the gutter, until a red circle appears (Figure 11-10).

Figure 11-10. Adding a breakpoint

To remove a breakpoint, click the red circle to make it disappear. Alternatively, you can right-click (Ctrl-click) to the left of a line and select Toggle Breakpoint from the context menu, which adds or removes a red circle. To remove all breakpoints at once, select Remove Breakpoints in This File. Flash CS4 is smart enough to remember your breakpoints even after you close the authoring tool, whether they appear in timeline or class code. You may add as many breakpoints as you wish. In the next few steps, you’ll learn how they work.

1. Continuing with the same FLA file, use the Actions panel to add a breakpoint to the left of line 1, which contains the trace() function.

2. Select Debug→Debug Movie to re-enter the debugging workspace. Note the difference among the panels: Flash Player no longer shows, because it hasn’t yet opened (the breakpoint in the first line of code has halted the movie). In addition, both the Debug Console panel and the Variables panel now display information, as seen in Figure 11-11 (click the + sign or arrow triangle inside the Variables panel to open the nodes shown).

   In the upper left, the Debug Console panel displays an interesting bit of information in an area known as the call stack: Untitled_fla::MainTimeline/frame1. The call stack shows the currently executing method, in an ordered list of all methods under execution. Here, the list displays only one item because only one method is executing. Unless you associate a FLA file with a custom document class (see Chapter 6), an automatic document class is assigned by default. This class is named MainTimeline, and keyframe scripts are considered methods of that class, which explains the MainTimeline/frame1 reference, functionally equivalent to the more familiar syntax MainTimeline.frame1(). In complex movies, you may see many entries in the call stack, as potentially numerous methods call each other, and then remove themselves as execution completes.

   The Variables panel displays the properties of the object currently in scope, which is still MainTimeline. Click the + sign or arrow triangle next to the word this, and you see the familiar properties of the MovieClip class, which is the data type of the main timeline in this scenario. The values of these properties reflect the current state of the main timeline as movie clip. The currentLabels property, for example, is an empty array, because the main timeline hasn’t been given any frame labels. The x and y properties are 0 and 0, because the main timeline is inherently positioned in the stage’s upper-left corner.

   Note

   The expressions after some properties, for example (@120aec1), are hexadecimal representations of their addresses in memory.

3. In the Debug Console panel, click the green arrow button. Two things happen when you do: first, Flash Player appears; second, the Output panel displays the trace() message, “Just a bit of code.” The buttons along the top of the Debug Console panel let you control the playback of your breakpoints (Figure 11-12).

   The green arrow resumes normal play of the SWF file until the next breakpoint is encountered. The red X closes the current debugging session. The remaining three arrow buttons let you Step Over, Step In, and Step Out of your breakpoints.

   • Step Over causes the debugger to move to the very next line of code and pause, as though it has encountered a breakpoint. By clicking this button repeatedly, you can step through your code line by line, keeping an eye on the Variables panel to see how values change.

   • Step In jumps to any function or method referenced on the current breakpoint, and then steps through the code of that function or method line by line.

   • Step Out moves the debugger immediately to the exit point of the current function or method, typically where the function or method returns a value.

Figure 11-11. The debugger workspace, halted on a breakpoint

Figure 11-12. Debug Console panel buttons, with a new method in the call stack

Here’s a slightly more complex—but still very simple—example that demonstrates the Debug Console panel and Variables panel in action.

Figure 11-13. A simple application in need of troubleshooting

Figure 11-14. The call stack showing two methods, with properties of the current scope below

If nothing jumps out at you, then you may have to repeat the process a few times. This is the patient discipline of a good troubleshooter. The clues really are right in front of you.

Eventually, you see the float variable get assigned a number greater than 4, which gets rounded up to 5 and assigned to the index variable in line 13. The trouble with 5 in this scenario is that the _replies property, an Array instance, has a total of five elements. Arrays start their count at zero, as shown in the Variables panel in step 12, which displayed elements 0 through 4. There is no element 5. Aha!

The cause of that occasional number 5 is the Math.ceil() method in line 13, which always rounds up. Change that method to this (change in bold):

var index:int = Math.floor(float);

Math.floor() always rounds down, which ensures that index is always a number between 0 and 4.

Flash is a medium designed for the Web. Even with the advent of the Adobe Integrated Runtime (AIR), it’s safe to say that most Flash content is currently displayed in a browser—and browsers don’t feature the Flash debugging workspace. In spite of this inevitable gap, you can bridge published SWF files past their browser host environments in order to communicate with the Flash authoring tool. The process is called remote debugging.

To allow Flash CS4 to remotely debug a SWF file, you need to indicate your intent by selecting the checkbox at File→Publish Settings→Flash→Permit debugging. Adding that checkmark enables a Password input field (Figure 11-15) intended to let you password protect a SWF file to ensure that only you can debug it. Unfortunately, this password field is only supported by ActionScript 2.0 documents. The Permit debugging option saves breakpoints and other debug information into the compiled SWF file, which can increase file size. In light of this, when it’s time for deployment, you may want to disable remote debugging and perhaps enable Omit trace actions in the same preferences dialog box.

Figure 11-15. Configuring a SWF file for remote debugging

With remote debugging enabled, select Debug→Begin Remote Debugging Session→ActionScript 3.0. The debugging workspace appears, and the Output panel displays the message “Waiting for Player to connect...”. At this point, launch the SWF file in a browser and then right-click (Ctrl-click) and select Debugger. You need a debug version of the Flash Player ActiveX control or plug-in for this to work, as described in the next section (you may also use the debug version of the standalone Flash Player). The SWF file connects with the authoring tool and debugging continues as before.

The Flex documentation has a trick that explains how to configure the debug version of Flash Player to log trace() statements to a local text file. Fortunately, it works for Flash too, and it doesn’t involve the debugging workspace. In order to make use of this technique, you’ll have to install the debug version of Flash Player as an ActiveX control or plug-in. You can find the necessary files within the installation folder of Flash CS4:

These files are also available from the Adobe website:

At this point, when you view a SWF file in a browser that has the debug version of Flash Player installed, any trace() statements in that SWF file are written to a text file named flashlog.txt. This text file is cleared and restarted each time you view the SWF file in a new browser session. The location of flashlog.txt used to be configurable, but this changed with version 9.0.28.0 of Flash Player. The current location is: