Debugging
is similar to running your applications. However, when you debug you
control when the application stops at specific points in the code
and whether you want it to monitor important variables, and you
can test fixes to your code. Both running and debugging use a configuration
to control how applications are launched. When you debug your application,
you run the debug version of the application file.

Starting a debugging session

To
begin a debugging session, you run the application launch configuration
in the Flash Debug perspective.

Debug an application

In the Flex Package Explorer, select
the project to debug.

Select the Debug button from the main workbench toolbar.

Note: The Debug button has two elements: the main action
button and a drop-down list that shows the application files in
the project that can be run or debugged. When you click the main
action button, the project’s default application file is debugged.
You can alternatively click the drop-down list and select any of
the application files in the project to debug. You can also access
the launch configuration dialog box and create or edit a launch
configuration by selecting the Debug command.

If your project
has not been built yet, Adobe® Flash® Builder™ builds
and runs it in debug mode.

Your application appears in your default web browser or the
stand-alone Flash Player and you can then use the Flash Builder
debugger to interact with it.

When a breakpoint is reached, the Flash Debug perspective
is activated in the workbench.

Start a debugging session in the plug-in configuration

The Debug
command works differently in the plug-in configuration of Flash Builder.
Instead of running the selected project, it debugs the most recently launched
configuration. You can also select from a list of recently launched configurations.

Adding and removing breakpoints

You use breakpoints to suspend the execution of your application
so you can inspect your code and use the Flash Builder debugging
tools to explore options to fix errors. You add breakpoints in the
code editor and then manage them in the Breakpoints view when you
debug your applications.

You add breakpoints to executable lines of code. The debugger
stops only at breakpoints set on lines that contain the following:

MXML tags that contain an ActionScript event handler,
such as <mx:Button click="dofunction()" ...>

ActionScript lines such as those enclosed in an <mx:Script> tag
or in an ActionScript file

Any executable line of code in an ActionScript file

You can set breakpoints as you write code or while you debug.

Set a breakpoint in the code editor

Open a project
file that contains ActionScript code.

Locate the line of code on which you want to set a breakpoint,
and double-click in the marker bar to add a breakpoint.

The
marker bar is along the left edge of the code editor.

A breakpoint
marker is added to the marker bar and to the list of breakpoints in
the Breakpoints view of the Flash Debug perspective.

When
the debugger encounters a breakpoint, the application is suspended,
the Flash Debug perspective is displayed, and the line of code is
marked with a breakpoint. The line of code is highlighted in the
code editor. You then use the debugging commands to interact with
the code. (See Managing the debugging session in the Debug view).

Remove a breakpoint in the code editor

In the marker
bar, double-click an existing breakpoint.

The breakpoint
is removed from the marker bar and the Breakpoints view of the Flash
Debug perspective.

Setting Conditional Breakpoints

You can specify conditions for breakpoints to stop the
debugger from executing when specific conditions are met. When you
set a conditional breakpoint, you specify an ActionScript expression
that is evaluated during the debugging session. You configure the
conditional breakpoint to halt execution for any of the following
conditions:

The expression evaluates to true.

The value of the expression changes.

A specified Hit Count has been reached.

Setting a conditional breakpoint

From the context menu for a breakpoint, select Breakpoint
Properties.

In the Breakpoint Properties dialog, specify any of the following:

Enabled

Toggle to enable or disable the breakpoint.

Hit Count

Select Hit Count to enable a counter for
the breakpoint. Specify a number for the Hit Count.

If you
specify both Hit Count and Enable Condition, the Hit Count is the number
of times that the specified condition is met (either evaluates to
true or the value of the condition changes).

If you specify
Hit Count only, then Hit Count is the number of times the breakpoint
has been reached.

Enable Condition

Select Enable Condition and enter
an ActionScript expression to evaluate. See Examples of expressions for information on types of expressions supported
for evaluation.

Note: Flash Builder checks the syntax of the expression
and notifies you of syntax errors. If you have an assignment operator
in the expression, Flash Builder displays a warning.

Suspend when:

Specify when to halt execution, either
when the expression for the condition evaluates to true or the value
of the expression changes.

Managing breakpoints in the Breakpoints view

In the Breakpoints view you manage breakpoints
during a debugging session. You can remove, disable and enable,
or skip them.

The following commands are available from the Breakpoints view
toolbar (as shown left to right):

Opens the file (if it is not already open)
that contains the breakpoint in the code editor and highlights the
line of code on which the breakpoint was set. You can also simply
double-click the breakpoint to display it in the code editor.

Skip All Breakpoints

Skips all breakpoints.

Expand All

Expands all breakpoints.

Collapse All

Collapses all breakpoints.

Link With Debug View

Links to Debug view.

Remove breakpoints in the Breakpoints view

You can remove one,
a few, or all of the breakpoints in the Breakpoints view from the
Breakpoints toolbar

Select one or more breakpoints
from the list of breakpoints, and then click Remove Selected Breakpoints.

You
can also remove all the breakpoints in the Breakpoints view in a
single action.

Remove all breakpoints from the Breakpoints view

In the
Breakpoints view, click Remove All Breakpoints.

Managing the debugging session in the Debug view

The Debug view is the control center
of the Flash Debug perspective. You use it to control the execution
of the application, to suspend, resume, or terminate the application,
or to step into or over code.

The Debug view provides the following debugging commands, which
are available from the Debug view toolbar (as shown left to right):

Suspends the application so that you can
inspect, step into the code, and so on.

Terminate

Terminates the debugging session.

Disconnect

Disconnects the debugger when debugging
remotely.

Step Into

Steps into the called function and stops
at the first line of the function.

Step Over

Executes the current line of the function
and then stops at the next line of the function.

Step Return

Continues execution until the current function
has returned to its caller.

Drop to Frame

This command is not supported in Flash Builder.

Use Step Filters

This command is not supported in Flash Builder.

Using the Console view

The Console view displays the output
from trace statements placed in your ActionScript code and also
feedback from the debugger itself (status, warnings, errors, and
so on).

The Console view provides the following commands, which are available
from the Console view toolbar (as shown left to right):

Button/Command

Description

Terminate

Terminates the debugging session.

Remove Launch

Clears all launched debugging sessions.

Remove All Terminated Launches

Clears all terminated debugging sessions.

Clear Console

Clears all content from the Console view.

Scroll Lock

Prevents the Console view from scrolling.

Show Console When Standard Out Changes

Displays the Console when writing to standard
out

Show Console When Standard Error Changes

Displays the Console when writing to standard
error

Pin Console

Prevents the console from refreshing its
contents when another process is selected.

Display Selected Console

Displays the selected Consoles

Open Console

Opens new console and displays pop-up menu
to select other console views.

Managing variables in the Variables view

The Variables view displays the variables
that the currently selected stack frame defines (in the Debug view).
Simple variables (name and value) are displayed on a single line.
The icons displayed with the variables provide visual cues about
the type of variable.

Complex variables can be expanded to display their members. You
use the Variables view to watch variables by adding them to the
Expressions view and to modify the value of variables during the
debugging session. You can also set watchpoints in the Variables
view, as described in Using Watchpoints.

All superclass members are grouped in a separate tree node; by
default you see only the members of the current class. This helps
reduce excess numbers of variables that are visible at one time
in Variables view.

The Variables view provides the following actions, which are
available from the Variables view toolbar (as shown left to right):

Change the value of a variable

Right-click (Control-click on Macintosh) to display the context
menu and select Change Value.

Enter the new value and click OK.

The variable contains
the new value.

Modified variables are displayed in red.

Find variables

To
locate a variable or variable member in the Variables view, with
the Variables view selected, begin entering the name of the variable
you’re looking for. You can also use the wildcard character (*)
to search for words that occur anywhere within a variable name (for
example, “*color”).

Icons representing variables in the Variables view

The Variables view uses icons and overlays to provide visual
cues to the types of variables that are being displayed. See Icons representing language elements for a list of icons and their
meaning.

Using the Expressions view

Use the Expressions view to watch variables
you selected in the Variables view and to add and evaluate watch
expressions while debugging your applications.

While debugging, you can inspect and modify the value of the
variables that you selected to watch. You can also add watch expressions,
which are code expressions that are evaluated whenever debugging
is suspended. Watch expressions are useful for watching variables
that may go out of scope when you step into a different function
and are therefore not visible in the view.

The Expressions view provides the following commands, which are
available from the Expressions view toolbar (as shown left to right):

Command

Description

Show Type Names

Shows the object types for items in the
Expressions view.

Show Logical Structure

This command is not supported in Flash Builder.

Collapse All

Collapses all expressions in view.

Remove Selected Expressions

Removes the selected variable or watch expression.

Remove All Expressions

Removes all variables and watch expressions
from the Expressions view.

You can also hover the mouse pointer over an expression or variable
in the source editor to see the value of that expression or variable
as a tooltip. You can add the expression to the Expressions view
by right-clicking and selecting Watch from the menu.

Examples of expressions

The Flash Builder Debugger supports a wide range of simple
and complex expressions. The following table lists examples of expressions
that can be evaluated during a debugging session. This is not the
complete list of expressions supported, but just a sampling of what
you can do.

Examples of supported expressions

Expression

Description

myString.length

Returns the length of a string.

myString.indexOf(‘@’)

Tracks the index of the ‘@’ character.

"constant string".charAt(0)

Tracks the character at a specific position
in a string. String constants are supported.

employees.employee.@name

employees is an XML variable. This type
of expression is useful for debugging E4X applications.

x == null

Reserved words representing values in expressions.

user1 === user2

Most ActionScript operators are supported.

MyClass.myStaticFunc()

Functions resolved to a class.

this.myMemberFunc()

Functions resolved using the keyword this.

String.fromCharCode(33)

String is actually a function, not a class,
and String.fromCharCode is actually a dynamic member of that function.

myStaticFunc()

Can be valuated only if myStaticFunc is
visible from the current scope chain

myMemberFunc()

Can be valuated only if myMemberFunc is
visible from the current scope chain.

Math.max(1,2,3)

Math functions are supported.

mystring.search(/myregex/i)

Regular expressions are supported.

["my", "literal", "array"]

Creation of arrays.

new MyClass()

Instantiation of classes.

"string" + 3

Correctly handles string plus Integer.

x >>> 2

Logical shift operations supported.

3.5 + 2

Performs arithmetic operations correctly.

Limitations of expression evaluation

There are some limitations to expression evaluation.

Namespaces are not supported.

Inline objects are not supported.

The keyword super is not supported.

Fully qualified class names are not supported.

For
example, you cannot evaluate mx.controls.Button.

You can refer
to the unqualified class name. For example, you can specify Button
to refer to mx.controls.Button.

If a class name is ambiguous
(two classes with the same name in different packages,) then you
cannot control which class will be evaluated. However, you can specify:

getDefinitionByName("mx.controls.Button")

Most E4X expressions can be evaluated, but E4X filter expressions
are not supported.

For example, you cannot evaluate myxml.(@id=='3')).

You cannot call functions that are defined as a variable.

Using Watchpoints

When debugging an application, you can set watchpoints
on specific instances of variables to halt execution when the watched
variable changes value. Because watchpoints are set on a specific
instance of a variable, you cannot set the watchpoint in the code
editor. Instead, you set a watchpoint from the Variables view during
a debugging session.

When setting watchpoints, keep in mind the following:

When a debugging session ends, all watchpoints are removed.

You cannot set watchpoints on getters, but you can set them
on the field of a getter.

For example, you cannot set a watchpoint
on width, but you can set a watchpoint on _width.

You cannot set watchpoints on local variables, but you can
set watchpoints on members of local variables, as illustrated in
the following code fragment.

public class MyClass
{
// These are fields of a class, so you can set a watchpoint on
// 'memberInt', and on 'memberButton', and on 'memberButton._width':
private var memberInt:int = 0;
private var memberButton:Button = new Button();
public function myFunction():void {
// You CANNOT set a watchpoint on 'i', because it is local:
var i:int = 0;
// You CANNOT set a watchpoint on 'someButton', because it is local;
// but you CAN set a watchpoint on 'someButton._width':
var someButton:Button = new Button();
...
}

Execution halts for a watchpoint when the original value
of an object instance changes.

This differs from using an
expression in a conditional breakpoint to halt execution whenever
a variable changes value.

Setting watchpoints

In a debugging
session, there are two ways to set a watchpoint:

In
the Variables view, open the context menu for a variable, and select Toggle
Watchpoint

From the Flash Builder Run menu, select Add Watchpoint.

From
the Add Watchpoint dialog, select the variable you want to watch.

The
Variables view displays a “pencil icon” to indicate that a watchpoint
has been set on that variable.

Note: If you attempt to set a watchpoint
on a getter, Flash Builder opens a dialog suggesting a valid variable
for the watchpoint. If you delete the suggested variable, the dialog
lists all valid variables for the object.

Using Run to Line

Flash Builder provides the Run to Line command to break
out of a loop during a debugging session.

While debugging, you might find that your code is executing a
loop that repeats many times. To break out of this loop, use the
Run to Line command, available from the Run menu.