Packageuk.msfx.utils.tracing.fp10
Classpublic class Tr
InheritanceTr Inheritance Object

Tr.ace() is a library for managing trace statements within AS3 (Flash Player 10 Version).

Tr.ace() is a static Class that uses the Singleton design pattern so you only need to define it's settings once within your application and you're all set.

With Tr.ace() you can manage all your output statements, restricting or ignoring your applications traces to specific users and/or even specific Classes. Or you can toggle tracing off entirely.

The output using Tr.ace() can also be formatted with timestamps, linebreaks, the name of the user tracing, the Class the trace resides within and can be automatically copied to the clipboard.

For those using FlashDevelop you can prefix your username with "0:", "1:", "2:", "3:", or "4:" to trace in a different colour within the FlashDevelop output console, as shown with the 'FLASH_DEVELOP' username included.

UPDATE 1.1: The Tr.ace() library has been extended to feature Tr.aceArray(...) and Tr.aceObject(...), two functions to neatly format Arrays and Objects within the output console.

UPDATE 1.2: The Tr.ace() library has been extended again to feature Tr.aceMulti(...), a function to trace an unlimited number of arguments all on one line.

UPDATE 1.3: Updated to support Flash Player 9 (removed clipboard functionality from fp9 branch).

UPDATE 1.4: The Tr.ace() library has been extended to include a 'console' in the form of a textfield that all your traces are output to. For those working off the FP10 branch a new 'log' feature has also been integrated allowing you to output the traces to a .txt file.

UPDATE 1.5: To make the library more accessible and less "verbose" for simple quick use the username and class are now OPTIONAL parameters.

UPDATE 1.6: Rearchitectured Clipboard (FP10 Branch only) and Logging functionality to work together more sensibly. To copy to clipboard you must now call Tr.copyLogToClipboard(). You can also clear the log using Tr.clearLog()

UPDATE 2.0: Introduced TrConsole for both FP9 and FP10 branches allowing user to have a "console window" within the published SWF. Console supports resizing, repositioning, clearing the log, copying log to clipboard and saving the log to a text file.



Public Properties
 PropertyDefined By
  arrayAndObjectLinebreaks : Boolean
[static] Toggle whether a line break will be added at the beginning and end of a Tr.aceArray() or Tr.aceObject() call.
Tr
  console : TextField
[static] Manually assign a Textfield as a "console" to output the traces to (not recommended).
Tr
  enabled : Boolean
[static] Toggle whether the output is on or off.
Tr
  ignoreClasses : Array
[static] An Array of Classes (Class) that you wish the output to ignore.
Tr
  ignoreUsers : Array
[static] An Array of Users (String) that you wish the output to ignore.
Tr
  restrictToClasses : Array
[static] An Array of Classes (Class) that you wish the output to be restricted to.
Tr
  restrictToUsers : Array
[static] An Array of users (Strings) that you wish the output to be restricted to.
Tr
  useLineBreaks : Boolean
[static] Toggle whether the output has line breaks between each trace.
Tr
  useTimeStamp : Boolean
[static] Toggle whether each trace features a timestamp (HH:MM:SS:MS).
Tr
Public Methods
 MethodDefined By
  
Tr()
Static Class, Unused Constructor.
Tr
  
ace(output:*, user:String, withinClass:Class = null):void
[static] Function to trace to the output console.
Tr
  
aceArray(output:Array, user:String, withinClass:Class = null):void
[static] Function to trace the elements of an Array to the output console, in a neatly formatted manner.
Tr
  
aceMulti(user:String, withinClass:* = null, ... values):void
[static] Function to trace multiple values out to the console.
Tr
  
aceObject(output:Object, user:String, withinClass:Class = null):void
[static] Function to trace the properties of an Object to the output console, in a neatly formatted manner.
Tr
  
clearLog():void
[static] Clear the current log
Tr
  
[static] Copy the current log to the Clipboard Requires Flash Player 10+
Tr
  
saveLog():void
[static] Save the current Tr.ace(...) log out to a text file.
Tr
Property Detail
arrayAndObjectLinebreaksproperty
arrayAndObjectLinebreaks:Boolean

Toggle whether a line break will be added at the beginning and end of a Tr.aceArray() or Tr.aceObject() call.


Implementation
    public static function get arrayAndObjectLinebreaks():Boolean
    public static function set arrayAndObjectLinebreaks(value:Boolean):void
consoleproperty 
console:TextField

Manually assign a Textfield as a "console" to output the traces to (not recommended). Use TrConsole instead.


Implementation
    public static function get console():TextField
    public static function set console(value:TextField):void
enabledproperty 
enabled:Boolean

Toggle whether the output is on or off.


Implementation
    public static function get enabled():Boolean
    public static function set enabled(value:Boolean):void
ignoreClassesproperty 
ignoreClasses:Array

An Array of Classes (Class) that you wish the output to ignore.

Example:

To ignore the output from only your ClassName1 class you would use the following:

Tr.ignoreClasses = [ClassName1];

or to ignore from multiple classes

Tr.ignoreClasses = [ClassName1, ClassName2];


Implementation
    public static function get ignoreClasses():Array
    public static function set ignoreClasses(value:Array):void
ignoreUsersproperty 
ignoreUsers:Array

An Array of Users (String) that you wish the output to ignore.

Example:

To ignore the output from the DEFAULT user you would use the following:

Tr.ignoreUsers = [TrUsers.DEFAULT];

or to ignore from multiple users

Tr.ignoreUsers = [TrUsers.DEFAULT, TrUsers.MATT];


Implementation
    public static function get ignoreUsers():Array
    public static function set ignoreUsers(value:Array):void
restrictToClassesproperty 
restrictToClasses:Array

An Array of Classes (Class) that you wish the output to be restricted to.

Example:

To restrict the output from only your ClassName1 class you would use the following:

Tr.restrictToClasses = [ClassName1];

or to restrict to multiple classes

Tr.restrictToClasses = [ClassName1, ClassName2];


Implementation
    public static function get restrictToClasses():Array
    public static function set restrictToClasses(value:Array):void
restrictToUsersproperty 
restrictToUsers:Array

An Array of users (Strings) that you wish the output to be restricted to.

Example:

To restrict the output from the DEFAULT user you would use the following:

Tr.restrictToUsers = [TrUsers.DEFAULT];

To restrict to multiple users you would simply do this:

Tr.restrictToUsers = [TrUsers.DEFAULT, TrUsers.MATT];

NB: I suggest you add your username(s) to the TrUsers class rather than entering a String each time (removing the risk of typos).


Implementation
    public static function get restrictToUsers():Array
    public static function set restrictToUsers(value:Array):void
useLineBreaksproperty 
useLineBreaks:Boolean

Toggle whether the output has line breaks between each trace.


Implementation
    public static function get useLineBreaks():Boolean
    public static function set useLineBreaks(value:Boolean):void
useTimeStampproperty 
useTimeStamp:Boolean

Toggle whether each trace features a timestamp (HH:MM:SS:MS).


Implementation
    public static function get useTimeStamp():Boolean
    public static function set useTimeStamp(value:Boolean):void
Constructor Detail
Tr()Constructor
public function Tr()

Static Class, Unused Constructor.

Method Detail
ace()method
public static function ace(output:*, user:String, withinClass:Class = null):void

Function to trace to the output console.

Examples:

Tr.ace("This is a trace statement", TrUsers.MATT, ClassName);

Tr.ace(4 + 21 + variableName, TrUsers.YOUR_USERNAME, AnotherClassName);

Parameters

output:* — The output that you wish to trace to the console
 
user:StringOPTIONAL: The name of the user tracing the output
 
withinClass:Class (default = null)OPTIONAL: The name of the Class the output is being traced from

aceArray()method 
public static function aceArray(output:Array, user:String, withinClass:Class = null):void

Function to trace the elements of an Array to the output console, in a neatly formatted manner.

Examples:

Tr.aceArray(["array", "test", 101, true], TrUsers.MATT, ClassName);

var dummyArray:Array = ["array", "test", 101, true]; Tr.aceArray(dummyArray, TrUsers.YOUR_USERNAME, AnotherClassName);

Parameters

output:Array — The Array that you wish to trace to the console
 
user:StringOPTIONAL: The name of the user tracing the output
 
withinClass:Class (default = null)OPTIONAL: The name of the Class the output is being traced from

aceMulti()method 
public static function aceMulti(user:String, withinClass:* = null, ... values):void

Function to trace multiple values out to the console.

The User and Class are requested first since nothing can preceed '...values'.

Example:

Tr.aceMulti(TrUsers.DEFAULT, ClassName, "string to trace", 1.2 + 4.5, ["array", "to", "trace"]);

Parameters

user:StringOPTIONAL: The name of the user tracing the output
 
withinClass:* (default = null)OPTIONAL: The name of the Class the output is being traced from
 
... valuesOPTIONAL: The values that you wish to trace to the console

aceObject()method 
public static function aceObject(output:Object, user:String, withinClass:Class = null):void

Function to trace the properties of an Object to the output console, in a neatly formatted manner.

Examples:

Tr.aceObject({"a" : 1, "b" : 2, "c" : 3], TrUsers.MATT, ClassName);

var dummyObject:Object = {"array test" : [1, 2, 3], "numbers" : 123.456, "obj" : {"a" : 1, "b" : 2, "c" : 3} }; Tr.aceObject(dummyObject, TrUsers.DEFAULT, AnotherClassName);

Parameters

output:Object — The Object that you wish to trace to the console
 
user:StringOPTIONAL: The name of the user tracing the output
 
withinClass:Class (default = null)OPTIONAL: The name of the Class the output is being traced from

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

Clear the current log

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

Copy the current log to the Clipboard

Requires Flash Player 10+

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

Save the current Tr.ace(...) log out to a text file.

Log file will be time stamped by default in the format "DD-MM-YYYY-HHMM".