Packagecom.hexagonstar.util.debug
Classpublic final class Debug

The Debug class is a static class that is used to send debugging information to Alcon. It can be used to simply output information with the trace() method, recursively output objects with traceObj() or inspect objects with the inspect() method, start monitoring the applications framerate with monitor() and to use other debugging assets like a Stopwatch.
To use this class import it into any class that should make use of it and then call any of the debugging methods anywhere in your class.


Example

  import com.hexagonstar.util.debug.Debug;
  
  public class Test extends Sprite {
      public function Test() {
          Debug.monitor(stage);
          Debug.trace("Test");
      }
  }



Public Properties
 PropertyDefined by
  enabled : Boolean
[static] Determines whether the Debug class is currently enabled or disabled.
Debug
  filterLevel : int
[static] The currently used Debugging Filter Level.
Debug
Public Methods
 MethodDefined by
  
Internal Constructor.
Debug
  
clear():void
[static] Clears Alcon's Trace buffer.
Debug
  
delimiter():void
[static] Output's a delimiter String to Alcon's Trace Logger that can be used to quickly seperate different kinds of debug informations, making it easier to read them.
This does the same like sending the DLT signal manually: Debug.trace("[%DLT%]");
Debug
  
forceGC():void
[static] Forces an immediate Garbage Collector mark/sweep.
Debug
  
hexDump(obj:Object):void
[static] Outputs a hexadecimal dump of the specified object to Alcon's Trace Logger.
Debug
  
inspect(obj:Object):void
[static] Inspects the specified Object, Array or Class with Alcon's Object Inspector.
Debug
  
mark(color:uint = 0xFF00FF):void
[static] Places a marker in Alcon's App Monitor graph.
Debug
  
monitor(stage:Stage, pollInterval:int = 500):void
[static] Starts monitoring the application.
Debug
  
pause():void
[static] Pauses Alcon.
Debug
  
stop():void
[static] Stops monitoring the application after it has been started with Debug.monitor().
Debug
  
time():void
[static] Sends a Time & Date stamp to Alcon's Trace Logger.
Debug
  
[static] Outputs the measured Stopwatch time in milliseconds to Alcon's Trace Logger.
Debug
  
[static] Outputs the measured Stopwatch time in seconds to Alcon's Trace Logger.
Debug
  
timerReset():void
[static] Resets the Stopwatch.
Debug
  
timerStart(title:String = ""):void
[static] Starts a Stopwatch to measure a time amount.
Debug
  
timerStop():void
[static] Stops the Stopwatch after it has been started with Debug.timerStart().
Debug
  
timerStopToString(reset:Boolean = false):void
[static] Stops the Stopwatch and immediately sends the measured time to the Trace Logger in the same format like Debug.timerToString().
Debug
  
[static] Sends the measured Stopwatch time to the Trace Logger.
Debug
  
trace(... args):void
[static] Traces out any specified data to Alcon's Trace logger.
Debug
  
traceObj(obj:Object, depth:int = 64, level:int = 1):void
[static] Traces the specified Object, Array or Class recursively to Alcon's Trace logger.
Debug
Public Constants
 ConstantDefined by
  LEVEL_DEBUG : int = 0
[static] The Debug.LEVEL_DEBUG constant defines the value of the Debug Filtering Level.
Debug
  LEVEL_ERROR : int = 3
[static] The Debug.LEVEL_ERROR constant defines the value of the Error Filtering Level.
Debug
  LEVEL_FATAL : int = 4
[static] The Debug.LEVEL_FATAL constant defines the value of the Fatal Filtering Level.
Debug
  LEVEL_INFO : int = 1
[static] The Debug.LEVEL_INFO constant defines the value of the Info Filtering Level.
Debug
  LEVEL_WARN : int = 2
[static] The Debug.LEVEL_WARN constant defines the value of the Warn Filtering Level.
Debug
Property detail
enabledproperty
enabled:Boolean  [read-write]

Determines whether the Debug class is currently enabled or disabled. If this property is set to false the Debug class will not send out any information to Alcon. This can be used to disable the Debug API completely without the need to remove any debugging code.

Implementation
    public static function get enabled():Boolean
    public function set enabled(value:Boolean):void
filterLevelproperty 
filterLevel:int  [read-write]

The currently used Debugging Filter Level. By default this is 0 so that all levels of information are sent to the output. This property can be used to control the filter level from within the Debug class. For example setting this property to Debug.LEVEL_ERROR will only let information of Error and Fatal level pass.

Implementation
    public static function get filterLevel():int
    public function set filterLevel(value:int):void
Constructor detail
Debug()constructor
public function Debug()

Internal Constructor. The Debug class is static and doesn't need to be instantiated. Use any of the methods directly, e.g. Debug.trace();

Method detail
clear()method
public static function clear():void

Clears Alcon's Trace buffer. This does the same like sending the CLR signal manually: Debug.trace("[%CLR%]");

delimiter()method 
public static function delimiter():void

Output's a delimiter String to Alcon's Trace Logger that can be used to quickly seperate different kinds of debug informations, making it easier to read them.
This does the same like sending the DLT signal manually: Debug.trace("[%DLT%]");

forceGC()method 
public static function forceGC():void

Forces an immediate Garbage Collector mark/sweep. This method is only guaranteed to work for use in AIR applications!
It first tries to use System.gc() and if that fails (i.e. when run in Flash Player) it falls back to a different method to cause a garbage collection that is not officially supported by ActionScript. Handle with care when run in a non-AIR-Runtime!

hexDump()method 
public static function hexDump(obj:Object):void

Outputs a hexadecimal dump of the specified object to Alcon's Trace Logger.

Parameters
obj:Object — The object to output as a hex dump.

Example

   var array:Array = ["Sandy", "Beth", "Kayla"];
   Debug.hexDump(array);
   var obj:Object = {n1: "Sandy", n2: "Larry"};
   Debug.hexDump(obj);
   Debug.hexDump(stage);

inspect()method 
public static function inspect(obj:Object):void

Inspects the specified Object, Array or Class with Alcon's Object Inspector. For classes only public properties and methods can be inspected. Also note that uint's are always converted to int's by the Inspector.

Parameters
obj:Object — The Object, Array or Class to inspect.

Example

   var array:Array = [777, 123, "Gerry", "Gail"];
   Debug.inspect(array);
   var obj:Object = {n1: "Bill", n2: "Jenny"};
   Debug.inspect(obj);
   Debug.inspect(new Bitmap());

mark()method 
public static function mark(color:uint = 0xFF00FF):void

Places a marker in Alcon's App Monitor graph. Optionally a color can be specified for the marker.

Parameters
color:uint (default = 0xFF00FF) — The color for the marker.
monitor()method 
public static function monitor(stage:Stage, pollInterval:int = 500):void

Starts monitoring the application. When called starts measuring the currently debugged application's FPS (frames per second) and FRT (frame render time) and sends the values and the current memory consumption amount to Alcon's App Monitor.

Parameters
stage:Stage — The Stage object of the current host application.
 
pollInterval:int (default = 500) — The interval in milliseconds with that framerate- related data is being polled. The lower this value is the faster Alcon's App Monitor will update.
pause()method 
public static function pause():void

Pauses Alcon. With this method Alcon's Trace and File Loggers are brought into Pause mode.
This does the same like sending the PSE signal manually: Debug.trace("[%PSE%]");

stop()method 
public static function stop():void

Stops monitoring the application after it has been started with Debug.monitor().

time()method 
public static function time():void

Sends a Time & Date stamp to Alcon's Trace Logger. This does the same like sending the TME signal manually: Debug.trace("[%TME%]");


Example

   Debug.time();

Output:

Sun Aug 17 2008 03:35:34 PM

timerInMilliSeconds()method 
public static function timerInMilliSeconds():void

Outputs the measured Stopwatch time in milliseconds to Alcon's Trace Logger.

timerInSeconds()method 
public static function timerInSeconds():void

Outputs the measured Stopwatch time in seconds to Alcon's Trace Logger.

timerReset()method 
public static function timerReset():void

Resets the Stopwatch.

timerStart()method 
public static function timerStart(title:String = ""):void

Starts a Stopwatch to measure a time amount. This method can be used to measure the execution time for any code in the host application. Optionally a title can be specified to describe what the Stopwatch is measuring. The stopwatch can be started and stopped several times sequencially and then will list all measured times unless the Stopwatch has been reset with Debug.timerReset().

Parameters
title:String (default = "") — An optional title for the Stopwatch.

Example

   Debug.timerStart("Loop Execution Time");
   for (var i:int = 0; i < 100000; i++) {
       ...
   }
   Debug.timerStop();
   Debug.timerToString();

Output:

*************** [STOPWATCH] **************
* Loop Execution Time
* started [14435ms] stopped [17477ms] time [03042ms]
* total runnning time: 3.042s
*****************************************

timerStop()method 
public static function timerStop():void

Stops the Stopwatch after it has been started with Debug.timerStart().

timerStopToString()method 
public static function timerStopToString(reset:Boolean = false):void

Stops the Stopwatch and immediately sends the measured time to the Trace Logger in the same format like Debug.timerToString().

Parameters
reset:Boolean (default = false) — If true resets the Timer after the result has been output.
timerToString()method 
public static function timerToString():void

Sends the measured Stopwatch time to the Trace Logger. This method automatically formats the values to seconds and milliseconds.

trace()method 
public static function trace(... args):void

Traces out any specified data to Alcon's Trace logger. The data can be of any type e.g. String, Number, Object, Array etc. For tracing Objects and Arrays recursively use the traceObj() method instead. To inspect any object use the inspect() method.
The trace method takes up to two arguments, the first being the data to output and the second an optional integer that determines the filter (or severity) level that the data is being output with. If specified, the filter level must be within the range of existing levels (0 to 4).

Parameters
... args — The data to be traced.

Example

   Debug.trace("Profanity is one language all
       computer users know.");
   Debug.trace("Software never has bugs. It just
       develops random features.", 0);
   Debug.trace(18 + 4, Debug.LEVEL_ERROR);
   Debug.trace(Math.PI, Debug.LEVEL_WARN);

traceObj()method 
public static function traceObj(obj:Object, depth:int = 64, level:int = 1):void

Traces the specified Object, Array or Class recursively to Alcon's Trace logger. Optionally the recursion depth can be set with the depth argument.

Parameters
obj:Object — The Object, Array or Class to output recursively.
 
depth:int (default = 64) — The recursion depth that is used to loop through the objects children.
 
level:int (default = 1) — The filter level with that the trace is made.

Example

   var array:Array = ["Gerry", "Gail", "Garth"];
   Debug.traceObj(array);
   var obj:Object = {n1: "Bill", n2: "Giles"};
   Debug.traceObj(obj, 64, Debug.LEVEL_DEBUG);
   Debug.traceObj(stage, 128);

Constant detail
LEVEL_DEBUGconstant
public static const LEVEL_DEBUG:int = 0

The Debug.LEVEL_DEBUG constant defines the value of the Debug Filtering Level.

LEVEL_ERRORconstant 
public static const LEVEL_ERROR:int = 3

The Debug.LEVEL_ERROR constant defines the value of the Error Filtering Level.

LEVEL_FATALconstant 
public static const LEVEL_FATAL:int = 4

The Debug.LEVEL_FATAL constant defines the value of the Fatal Filtering Level.

LEVEL_INFOconstant 
public static const LEVEL_INFO:int = 1

The Debug.LEVEL_INFO constant defines the value of the Info Filtering Level.

LEVEL_WARNconstant 
public static const LEVEL_WARN:int = 2

The Debug.LEVEL_WARN constant defines the value of the Warn Filtering Level.