This blog has moved to a new location! http://iqandreas.github.com/

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:
http://iqandreas.isbetterthanyou.org/DebugText/DebugText_1.0.0.zip
(If anyone prefers "rar" or any other compression, just ask)

And the Documentation can be viewed directly in the browser at:
http://iqandreas.isbetterthanyou.org/DebugText/Documentation/


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


The blog entry with more details can be found at:
http://iqandreas.blogspot.com/2009/12/debug-text-has-been-updated-now-with.html





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.


Usage
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()"

Sample
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
DebugText.remove(stage);

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;

trace(allNames);
//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;

trace(allOutput);
//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?

Fixing Vector Support in FlashDevelop

More and more of my projects are becoming entirely FlashDevelop based, as 98% of the time, I don't need to see the stage. If I do, I code everything in FlashDevelop, and debug it with Flash.

Sadly, I ran into a snag when FlashDevelop didn't want to recognize the Vector class, at least not with code completion. The solution was actually quite simple.

Make sure you have the intrinsic AS file
Browse to the directory where you have FlashDevelop stored (in my case "C:\Program Files\FlashDevelop\".

Continue browsing through to "\Library\AS3\intrinsic\FP10\".
If you have the same setup as me (the default install path) the folder should now read:
C:\Program Files\FlashDevelop\Library\AS3\intrinsic\FP10\

If that folder contains Vector.as, you are good to go on to the next step, otherwise, you either need to update to the newest FlashDevelop, and/or the newest stable release of the Adobe Flex SDK (big file)


Make sure your projects are being treated as Flash 10 and not Flash 9
Finally, (and this was the part that wasn't working for me) on the menu bar, choose Tools > Settings, or press F10.

When the dialog appears, go to "AS3Context", and make sure the "Default Flash Version" is set to 10, instead of the default 9.


While you are in there, take the time to make sure other settings are set to your preference, such as class paths and the SDK location.


If it's still not working for someone, post a comment, and I'll try to debug it.