The Nordhagen

Log console for Flash applications

Introduction

AILogger is just that; a logger. Like many others. It’s a tool that’s been with me for several years and it has saved the day many times over. It started life as a text field on stage to write messages to in lieu of the trace statement unavailable once an application is on a server. It has evolved into a flexible and easy to use tool that makes monitoring and bug hunting just a little bit easier.

Download

Download AILogger here. (Current version: 1.2.1)

AILogger is also available as a repository on Google Code

Screenshots

Implementation

At it’s simplest, this is what you need to do:

var logger:AILogger = new AILogger();
addChild(logger);
logger.log(”Hello Planet!”);

This will give you the standard version of the logger that fills the available space within the application.

Use

The logger can be invoked by right clicking the application ad choosing “Show AILogger”, like so:

…or you can just hit SHIFT+Enter. Repeat to close.

Once open, you can use the up and down arrows to scroll and home and end buttons to jump to the beginning and end of the log.

Advanced logging

The constructor has this signature:

function AILogger ($password:String = “”, $width:uint = 0, $height:uint = 0)

$pasword: Optional password to ensure authorized access to the logger. When supplied, the first time you invoke the logger, a password prompt like this will show up:

Type in the password you gave the constructor. Focus is already set to the input field, just begin typing. The text you enter will remain red as long as it’s wrong and it turns green when you’ve typed the complete correct password. Hit enter and the logger shows up.

$width / $height: Optional dimentions for the logger. Handy if you want to be able to use the application while observing the log at the same time.

The log function has the following signature:

function log($msg:Object, $severity:int = AILoggerEvent.CODE_INFO, $appendLast:Boolean = false):void

$msg: What you want to appear in the logger. It can be basically anything. It does not need to be a string. If this parameter is something not natively handled by the logger, it will try to make the best of it with the insignia “(recovered)” preceeding it.

Tip: If the $msg parameter is recognized as a HEX color value (say 0xff0000) the log line will be colored with that color, and both the raw toString and HEX code will be displayed.

$severity: AILogger supports four levels of severity designated in the log window by their color. The severity levels are defined in the supporting AILoggerEvent class as numbers from 0 through 4. These are the different variations:

CODE_INFO: Default, black/hvite text.
CODE_WARNING: Orange text.
CODE_ERROR: Red text. Logging Errors or ErrorEvents automatically yelds this severity.
CODE_SUCCESS: In case you wanna shout it, this turns the text green.
CODE_EVENT: Blue text, logging events defaults to this code
NEW CODE_TRACE: Gray text to signify lower importance

$appendLast: This Boolean lets you append the message to the last line logged.

The log function also makes sure that you don’t waste screen space when repeating the same message in a row. If the same message is logged repeatedly (i.e. in a for-loop) the number of times it has been repeated will be displayed in parenthesis after the message. I.e. “Hello Planet (16)” means you logged “Hello Planet” 16 times.

Options

There are a few options you can use to control and customize the logger.

inverseColorScheme – (true/false): Sets the logger theme to a white-on-black appearance that comes in handy on top of very bright content. Or if you just want to play it Matrix-style

disablePassword – (true/false): Lets you disable the password prompt even thought you have supplied a password. Note: Passing nothing or an empty string to the constructor also effectively disables the password prompt.

detailedLogging: Gives you in general more information when logging complex data types like arrays, events, errors and unrecognized types. This last one will display as a full XML description of the object being logged, which can easily fill up the entire window, so you might want to use this for specific debugging.

coloring: Turns log line severity coloring on or off.

NEW! disableSenderLabel: Disables the part in log lines after ~ which is the origin of the log message

enableContextMenu – (true/false): Enables or disables the ability to open the logger from the Flash Player context menu.

isVisible: Returns whether the logger is open or not.

Public Methods

In addition to writing log lines, there’s a handful of other utility methods you can use.

describe($obj:Object,  $objectName:String = “”): Lets you pass in any object and the result is a list of properties belonging to that object. Use the $objectName argument to insert a custom name above to help distinguish the information in the log window. See DESCRIBE under AILoggerEvent for screenshot.

header($text:String): Lets you insert a headline with empty lines before and after to signify an important phase in the program.

cr($numLines:uint = 1): Inserts the desired number of empty lines.

toggle(): You guessed it.. Toggles the logger on or off. Password prompt enabled if so configured.

getLogText(): Returns the full contents of the logger.

AILoggerEvent

This is the supporting event class you can use for loose coupling. It has pretty much the same signature as the log() method. The log method can be used as an event handler for these events. It also contains the constants for the severity codes.

Event types:

LOG: Regular logging, just like calling the log() method directly

DESCRIBE: Lists all available properties of the object being the msg parameter. Looks like this:

Event signature:

function AILoggerEvent($type:String, $message:Object, $appendLast:Boolean = false, $severity:uint = 0, $origin:Object = null, $bubbles:Boolean = false, $cancelable:Boolean = false)

Tip:

Use the origin parameter to identify where a log message came from. Typically you just enter “this” when dispatching the AILoggerEvent, and the class name appears in the log.

The legal issues

There aren’t any. You are free to use this as you see fit, no more, no less. The only thing I ask of you is that you leave the credits in there and if you feel like making changes/additions to it, please suggest them to me, so I can make an assesment as to whether or not it should be included in the version avaiable here.

Suggestions

Please leave a comment!

Lastly; thanks to Jensa for thinking this was worthy of being shared with the community