Although not an advanced debugging technique, at one time or another a developer will find a need to trace (also referred to as log) messages from within an application. For this purpose, Flash Player exposes a global trace() method. You can log messages from anywhere within an application simply by calling the trace() method and passing any parameter of type string:

trace("application initialized");

Trace messages are typically displayed by attaching the debugger to an application. With an active FDB debug session, trace messages will be displayed in the console. With Flex Builder, launching a debug session will automatically do this and trace messages will be shown in the Console panel in the debugging perspective (see Figure 18-6).

Figure 18-6. Flex Builder Debugger Console panel

One of the great benefits of using the trace statement in this manner is the ability to receive the messages in real time while an application is running. The trace() method also supports passing in arrays or multiple arguments (rest-style arguments). This can be very useful in dumping data for informational purposes—for example, if you wanted to be able to easily track what children are currently in the Display Child list.

Example 18-1 contains two children. When you click the buttonOne button, the clickHandler() function is called and an array of children is displayed in the output window.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[

            private function clickHandler():void
            {
                trace("Childrent: "+this.getChildren());
            }

        ]]>
    </mx:Script>
    <mx:Button id="buttonOne" click="clickHandler()" label="Dump Data"/>
    <mx:Label id="labelTwo"/>
</mx:Application>

As with other debugging methods we have seen thus far, using the trace() function requires the Flash Debug Player. Although often you will just use the Flex Builder Debugger to output trace messages, with the debug version of the player you have the option of outputting the trace messages to a file. You may want to use this feature if you are having a hard time isolating user-reported bugs by having the user configure his machine to log all trace calls to a file and allow you to review the logfiles at a later time for clues on what sequence of events may have caused the bug. This also is useful for when a tester isolates a bug in an application and provides corresponding log information.

By default, installing the Debug Player does not enable trace logging. You will need to configure the player to enable logging. The configuration filename is mm.cfg. Under Windows XP it is located at C:Documents and Settings<user_name>, on Windows Vista it is located at c:users<user_name>, on Linux it is located at /home/<user_name>, and under Mac OS X it is located at /Library/Application Support/Macromedia/. For other operating systems and a full list, consult the Flash Player documentation.

First review your operating-system-specific path for an existing mm.cfg. If none already exists, you will need to create one in the location appropriate for your operating system. The configuration file is a plain-text file that supports several options. Most important, you will be interested in the ErrorReportingEnable, MaxWarnings, and TraceOutputFileEnable configuration properties.

A basic mm.cfg file that enables the trace output includes the following:

TraceOutputFileEnable=1

Once the configuration file is updated and saved to the proper location with the filename mm.cfg, the Flash Debug Player will log trace messages to flashlog.txt in the folder specific to your operating system. Under Windows XP, it will be located at C:Documents and Settings<username>Application DataMacromediaFlash PlayerLogs, under Windows Vista it is at C:Users<username>AppDataRoamingMacromediaFlash PlayerLogs, under Mac OS X it is at /Users/<username>/Library/Preferences/Macromedia/Flash Player/Logs/, and under Linux it is at /home/<username>/.macromedia/Flash_Player/Logs/.

Along with enabling trace logging, the Debug Flash Player can also log all runtime errors to the same logfile. You can enable error reporting using ErrorReportingEnable:

TraceOutputFileEnable=1
ErrorReportingEnable=1