This blog has moved to a new location!

Wednesday, October 28, 2009

DebugText - Onscreen "trace" replacement

Debug text has been updated!
And, DebugText now has it's very own hosting thanks to a very helpful contributor. :) Follow this link for the current version:
(If anyone prefers "rar" or any other compression, just ask)

And the Documentation can be viewed directly in the browser at:

The ZIP file includes the class, ASDoc documentation, and and some example usage.

The blog entry with more details can be found at:

It's not much, but because trace is not always available (like when preloading external SWFs), and the process of creating new textFields all the time is a bit of a hassle.

The DebugText class will create a small textField on the screen that displays whatever you "trace" out, and instead of several lines, one line is enough. It's just a quick little thing I made in a few minutes, and I definitely plan on expanding on it in the future.

Place the AS file directly into your Global Classpath. It can be moved to a specific package, but then an import statement is required at the top of every class that uses DebugText.

It is possible to create a new DebugText instance, but it is not recommended. Instead, use the static function "add" to trace output onto a specific DisplayObject (such as the stage or a new or specific sprite)

The first parameter is the container for the DebugText. Note that you can trace to several different locations completely separate to one another by just passing in different values for container. Calling the "add" function several times with the same container passed in will not create multiple instances of DebugText, instead it will add text to the existing DebugText instances.

Since DebugText is a textField, the font can be changed by referencing that DebugText instance which can be made available from either "DebugText.getDebugText(container)" or the instance that is returned from "add()"

ActionScript Code:
//Outputs to the stage: Hello World!
DebugText.add(stage, "Hello World!");

//The third parameter lets you timestamp the output, but is by default set to false
//Outputs to stage: [0012428] Collision detection completed.
DebugText.add(stage, "Collision detection completed.", true);

//Removes the DebugText instance from the stage, and removes all references for garbage collection

In this example, a lot of items are going to be traced out at once:
ActionScript Code:
var nameArray:Array = ["Andreas", "Brad", "Cedric", ... ];

//Limits to a maximum of 15 lines on the screen at once
DebugText.maxDisplayedLines = 15;

//Trace out all of the names in an array
//Because of the previous line, even if there are more than 15 names in the array,
//only the LAST 15 names will still be visible.
for (var i:int = 0; i < style="color: rgb(0, 0, 255);">length; i++)
DebugText.add(stage, "[" + i + "]" + nameArray[i]);

//To save everything that has been recorded by a specific DebugText instance,
//use the "listOutput" property
var allNames:String = DebugText.getDebugText(stage).listOutput;

//Outputs the following:
// 1 Andreas
// 2 Brad
// 3 Cedric
// etc...

//For verbose output of ALL DebugText instances,
//use the static DebugText.listOutput.
var allOutput:String = DebugText.listOutput;

//Outputs the following:
// [00001291] [object Stage] 1 Andreas
// [00001292] [object Stage] 2 Brad
// [00001292] [object Stage] 3 Cedric
// etc...

One more sample use, here you can trace out directly onto the button when it is hovered over, and hovered out:
ActionScript Code:
btn1.addEventListener(MouseEvent.ROLL_OVER, onOver);
btn2.addEventListener(MouseEvent.ROLL_OVER, onOver);
btn3.addEventListener(MouseEvent.ROLL_OVER, onOver);
// etc...

btn1.addEventListener(MouseEvent.ROLL_OUT, onOut);
btn2.addEventListener(MouseEvent.ROLL_OUT, onOut);
btn3.addEventListener(MouseEvent.ROLL_OUT, onOut);
// etc...

DebugText.maxDisplayedLines = 1;

function onOver(ev:Event)
DebugText.add(ev.currentTarget, "OVER");
function onOut(ev:Event)
DebugText.add(ev.currentTarget, "OUT");

TODO (Future updates):
  1. Allow the textField to dock to a specific part of the screen instead of just the default top left
  2. Allow each instance to have a different max characters
  3. Allow each instance to "clear screen" of all existing text
  4. Treat each trace string as an object instead of a string, allowing additional information to be added such as time when traced
  5. Allow users to add monitoring to specific properties, so when that property value changes, the new value is updated on the list (this is reserved for my LiveDebug project, still work in progress)

I didn't add these features yet because it's difficult, but only because I don't need these features yet, but if anyone has any need for them, I can easily add them.

Any more suggestions for improvement?

No comments:

Post a Comment