Debugging Flex 4 applications – Part 1: Debugging basics

Debugging is the process of finding and fixing bugs, or problems, in your application. Debugging is often a difficult and frustrating task but it can be greatly facilitated with the use of a debugger, a software tool that enables you to monitor and control the execution of the program, step through your code, and monitor and change the values of variables.

Flash Builder 4 has a built-in debugger and debugging perspective that you will learn to use in this three-part tutorial series.

In Part 1, you will:

• Import the ending project and see how the application should work.
• Import the starting project and review the code for the initial, broken Flex drawing application.
• View runtime error messages in the debugger version of Flash Player and in the Flash Builder Console view.
• Use trace() to output debugging information in the Console view.

In Part 2, you will:

• Use breakpoints to halt code execution when a specific line of code is reached.
• Use new conditional breakpoints.
• Use the Breakpoints view to manage breakpoints.
• Control code execution by suspending, resuming, and terminating the application.
• Step through code using the Step Into, Step Over, and Step Return commands.

In Part 3, you will:

• Use the Variables view to inspect the values of variables.
• Change the values of variables during a debug session to test fixes.
• Use the Expressions view to watch the values of specific variables and expressions.
• Use new watchpoints to halt code execution when the value of a specific variable changes.
• Break out of loops and jump to lines of code using the new Run to Line command.

In this section, you import into Flash Builder two Flex projects for an application that draws various shapes as you click and move your mouse. The starting project application does not currently work, the ending project application does. The ending application is for reference. You will debug the starting application in this series of tutorials.

1. If you have not done so already, download and install Flash Builder 4.
2. If you have not done so already, download the starting files and the solution files and unzip them.
3. Open Flash Builder.
4. Select File > Import Flex Project (FXP).
5. In the Import Flex Project dialog box, click the Browse button next to File.
6. In the Open dialog box, browse to where you saved the Flex4DebuggingTutorial_EndProject.fxp file, select it, and click Open.
7. Back in the Import Flex Project dialog box, click Finish (see Figure 1).

8. In the Package Explorer, click on the arrows to expand Flex4DebuggingTutorial_EndProject, src, and (default package) until you see Drawing.mxml (see Figure 2).

9. Double-click Drawing.mxml to open the file.
10. To compile and test the application, click the green Run button on the main toolbar or choose Run > Run Drawing. A browser window will open and you should see your application.
11. Click and drag your mouse to draw.
12. Use the controls in the upper-right corner to change the shape and color, and then draw some more (see Figure 3).

13. Right-click Flex4DebuggingTutorial_EndProject in the Package Explorer, and select Close Project. Closing the project will keep you from accidentally working on the ending files instead of the starting files.
14. Repeat steps 4-9 to import Flex4DebuggingTutorial_StartProject.fxp.
15. Run the application. You should get a runtime error (see Figure 4).

    Note: You will only see the pop-up error message shown in Figure 4 if you have the debugger version of Flash Player. (Typically only Flash and Flex developers have this version). Users with the normal Flash Player will not see the message; their applications will just not work.

16. Click the Dismiss All button.
17. Return to Drawing.mxml (in the starting project!) and examine the code.

The application works by listening for and responding to mouseDown, mouseMove, and mouseUp events. When the user presses the mouse button, a listener is added for moving the mouse. This onMouseMove() listener creates an instance of a shape class (a Circle, Square, or Star from the com.adobe.samples.shapes package), which uses the graphics API to draw a shape at the user's mouse position. When the user releases the mouse button, the onMouseMove() listener is removed so no more shapes are drawn. The application has controls in the upper-right corner to allow the user to select a different shape, change the color, and clear the drawing.

Note: This application was refactored from having all of its code in one file in the Refactoring Flex 4 Applications tutorial.

To debug an application in Flash Builder, you need two things: the debugger version of Flash Player and a debug version of your SWF.

When you install Flash Builder, the debugger version of Flash Player is installed for the different browsers you have installed on your system. You may need to manually install a debugger version of Flash Player, however, if you install a more recent non-debugger version of Flash Player in your browser after installing Flash Builder or if you just want in install a later version than the one that shipped with Flash Builder. You can tell if you need to install the debugger version of Flash Player if you get an error message when you try to debug the application in Flash Builder. You can also check by right-clicking on a SWF in a browser window and looking at its context menu (you will see Debugger in the menu) or by using the flash.system.Capabilities.isDebugger() method in your code. To install the latest debugger version of Flash Player, go to the Flash Player Downloads page, and run the uninstaller and then the appropriate installer for your browser.

When you compile an application in Flash Builder by running, debugging, or explicitly building an application, Flash Builder generates a debug version of the application's SWF file and saves it in the project's bin-debug folder. This SWF is larger than the non-debug version of the application because it includes additional code and metadata that the debugger uses. These are the SWFs you will use when debugging the application. When you are done debugging and ready to deploy your application, remember to create a smaller, non-debug version of the SWF by selecting Project > Export Release Build.

To debug an application, you use the Debug command instead of the Run command by clicking the Debug button in the main toolbar or selecting Run > Debug. The application launches in a browser window just as when you run it, but now if Flash Player encounters any errors or warnings, they are displayed in the Console view of Flash Builder.

1. Click the Debug button on the main toolbar (see Figure 5) or select Debug > Drawing.

A browser window will open and then you should be returned to Flash Builder where you may get a dialog box asking you if you want to switch to the debugging perspective (see Figure 6). If you are not immediately returned to Flash Builder, select its task in your taskbar or dock.

2. If you got the Confirm Perspective Switch dialog box, select Remember My Decision so you don't see this dialog box every time you debug the application and click Yes. Flash Builder switches to its debugging perspective, which has different panels than the development perspective (see Figure 7).

Note: Your panels may be arranged differently than shown here. You can rearrange panels by dragging and dropping them in different locations. You can return to the default layout by selecting Window > Perspective > Reset Perspective.

3. Switch to the development perspective by clicking the Flash tab in the upper-right corner (see Figure 8).

4. Switch back to the debugging perspective by clicking the Flash Debug tab in the upper-right corner (see Figure 8).
5. If you don't see both tabs, click on the edge of the left tab and drag it to the left (see Figure 9).

6. Navigate to the Console view. You should see the runtime error message you saw in the browser when you ran the application (see Figure 10). From the error message, you see that some object that is being referenced has not yet been created.

7. Look at the code in the editor view. Line 18 will be highlighted indicating this is where the error occurred. The arrow in the marker bar next to the line indicates that code execution has been stopped here (see Figure 11). There is a problem trying to assign shapeColor a value of the selectedColor property of a ColorPicker.

8. Locate the declaration of the ColorPicker on line 66. colorSelector is the name of the ColorPicker object.

   The problem on line 18 is that it is executed before the ColorPicker has been instantiated, so colorSelector does not exist and you cannot reference its properties yet.

9. Terminate the debugging session by clicking either of the red Terminate buttons or by selecting Run > Terminate.
10. Change the code on line 18 to give shapeColor an initial value of black:

11. Debug the application again. You should no longer get a runtime error in the browser or in the Flash Builder Console view.
12. Try to draw some shapes.

    No shapes are drawn. You fixed one problem, but there are more to find and fix.

13. Terminate the debugging session.

Next, you need to figure out if the rest of the code is being executed properly. One way to determine if code inside a function is being executed and to examine variable and expression values is to use the trace() method – which you will do here. In the old days of Flash Platform application development before there was an IDE (Integrated Development Environment) with a debugger, this was the only way to debug applications. Now that there is a debugger, you can also check to see if the function is invoked and view variable values at that point by placing a breakpoint inside the function and debugging the application instead. You will use breakpoints in the next part of the series.

To use the trace() method, you pass to it a string, a variable, or an expression to be evaluated. The result is displayed in the Console view when you debug the application.

1. Inside the init() function, trace the string "in init", by inserting the code in bold below:

2. Debug the application and look at the Console view (see Figure 12). You don't see your string. The code inside the init() function is not being executed.

3. Look at the Application tag. The init() function is not being called.
4. Specify init() to be the event handler for the Application's creationComplete event:

5. Stop the debugging session, then debug the application again and look at the Console view (see Figure 13). You will see your string traced; the init() function is now being called successfully.

6. Return to the browser and try to draw some shapes. You still cannot draw any shapes; there are still more bugs to find.
7. Return to Flash Builder and stop the debugging session.

Where to go from here

In this first tutorial, you learned the basics of debugging Flex 4 applications with Flash Builder 4. You used the debugger, the debugging perspective, the Console view, and the trace() method.

In Part 2, you’ll learn how to halt code execution using breakpoints and how to control code execution using Step Into, Step Over, Step Return, and Resume commands.

In Part 3, you'll use watchpoints, the Variables view to examine and change the values of variables, and the Expressions view to watch specific variables and Expressions.