Give Credit Where Credit is Due

As mentioned above, the Tilde Console is built almost exclusively using code from the PushButton Games Engine and all due credit goes to the original developers for their fine work. My contribution to the source has been minimal. Because of the nature of their work, games developers are the very best in the business at getting every last drop of performance out of their code and that fact is evident throughout the work of the PushButton team. It was a personal pleasure working with their code which is clearly the work of professionals: it is elegant, readable and although eminently clever, always easy to follow.

I'd like to thank the PushButton team for making their excellent work freely available and for the many tricks I've picked up while working my way through their code. If you are at all interested in learning how to write well-optimized Actionscript code, I strongly suggest that you check out their promising project.

Adding The console To Your Project

The simplest way to integrate the console into an application is to add the following line to your Application "creationComplete handler:

Logger.startup(Logger.LOGGER_UI_MODE);

This will add the event listener for the tilde key (i.e. "~") which toggles the console and will cause all deferred Logger calls to be processed. The other mode is called "LOGGER_TRACE_MODE" which only provides debugging trace logging functionality and not the graphical UIConsole.

The Logger can be explicitly turned off (which also frees up memory by discarding any deferred trace statements and blocks any subsequent Logger calls from being handled) by adding this line to your application:

Logger.disable();

The Console Display

As you can see in the example image, the console color-codes the trace statements by severity. There are five levels, including the vanilla "print" level which has no severity and is always displayed, regardless of the Logger's verbosity setting. The colors are as follows: grey for DEBUG, green for INFO, orange for WARN and red for ERROR. Plain old print calls are displayed in white.

To log an entry, add the following to your source:

Logger.error(<the class that's logging>, <the name of the method where the loggincall is made, as a String>, <the statement to log, as a String);

e.g.

Logger.error(MyClass, "myMethod", "This is an error log entry!");

Built-In Commands

The commands that come built-in are the following:)

Adding Custom Commands

One of the most powerful pieces of functionality included is the ability to wire callback functions into the console. These functions are then available at run-time as commands in the console, indistinguishable from the built in commands. It is even possible to feed parameters to these functions.

Here is an example of how this is done:

Note that though the method takes a parameter, if none is provided, the default will be used. If you don't provide a default then, no harm no foul, an exception will be traced at the "ERROR" level in the console.

How I Use It

In my most recent Flex projects, I've set up the application to be configured at run-time from XML-based resource bundles. This allow me to set up an application to run in different contexts, based on the contents of a configuration file. For instance, the application can be set to run in either "LIVE" or "TEST" context. Furthermore, the console is only activated and the callbacks are only ever declared in "TEST" mode. 

Having access to the trace has been a godsend during quality assurance and user acceptance testing because we don't ever use the debugging Flash Player for this kind of testing. By using the console, if a failure does occur, testers can still provide developers with the application trace as part of their bug report. This trace can often reveal specifics about an error that are otherwise invisible to the user and that would be irretrievable in a non-debugging Flash Player.

Where To Get It

The source code is available through Google code at: http://code.google.com/p/tildeconsole/ It is licensed through the MIT open source license which you'll find included in the project.

Compiling it for yourself is the best way to go but if you prefer you can grab one of the following untested SWC binaries: Flex 3.3  Flex 3.4  Flex 3.5. I'll try and upload a Flex 4.0 SWC as soon as I have time to build one.

Since seeing is believing, I also intend to make a test application available in the next few days so that people can see the console in action before downloading the project. I'll worry about that later because for now I really have to get some well-deserved rest.

[June 21, 2010 - Update: Check out the Tilde Console demo application here.]

Thanks for dropping by and please feel free to leave me a comment. It's always gratifying to hear from my visitors.