Introduction

Debugging a Widget can be a daunting task. Once inside Captivate, the usual trace() function doesn't work. However, CpGears includes a very flexible logging mechanism that can support you during your debugging efforts.

Initializing a Logger

Creating a Logger in CpGears is quite simple. You just need to call the LogManager which is a Static class.

	import cpgears.log.ILogger;
	import cpgears.log.LogManager;

	var mLogger:ILogger = LogManager.getLogger("MyCategory");

Then you can use the logger to output log messages targeting different levels.

	mLogger.debug("This is a debugging message");
	mLogger.info("This is an informative message");
	mLogger.warn("This is a warning message");
	mLogger.error("This is an error message");
	mLogger.fatal("This is a fatal message");

Logger Category

At creation time, a logger is assigned a category. The category is just a way to identify the log message. Usually, developers create a category that is matching the class' package. For example, if I have a class called DemoStaticWidget located in the demo package (folder), I would create a logger like this:

	var mLogger:ILogger = LogManager.getLogger("demo.DemoStaticWidget");

This would help me identify my log message to a specific class. If you want to follow the usual convention and have your log messages associated to the class in which they originate, just provide the this reference when creating the logger.

	var mLogger:ILogger = LogManager.getLogger(this);

Log Factory

By default, all log messages go to the usual trace() function. That works well inside Flash but not when inside Captivate. The CpGears logging mechanism uses Log Factories to redirect the messages. Packed with CpGears, there is a Log Factory created to redirect the log messages to Arthropod. Arthropod is a small debugging application that can show log messages outside of the Flash IDE. You can install Arthropod here.

To send the log messages to Arthropod, just reconfigure the LogManager:

	LogManager.logFactory = new ArthropodLogFactory();

CpGears offers interface for the developers that would like to create log factories.

Composing messages

The CpGears logger supports composing messages using text and variables without having to concatenate them using a + operator. You just need to include in your string a {x} token when x is the argument number. For example:

     var item:String = "files";
     var total:uint = 10;
     var lastAccess:String = "Monday";
     mLogger.debug("User has accessed a total of {0} {1} since last {2}.", total, item, lastAccess);

Would yield: User has accessed a total of 10 files since last Monday.

Example

This is an example of a class that would log messages to the Arthropod application:

package demo {
	import cpgears.log.ArthropodLogFactory;
	import cpgears.log.ILogger;
	import cpgears.log.LogManager;
	import cpgears.StaticWidget;
	import cpgears.views.manager.SimpleViewManager;
	import demo.views.EditView;
	import demo.views.RuntimeView;
	
	/**
	 * ...
	 * @author Whyves
	 */
	public class DemoStaticWidget extends StaticWidget {
		
		private var mLogger:ILogger = null;
		
		public function DemoStaticWidget() {
			LogManager.logFactory = new ArthropodLogFactory();
			super(new StaticWidgetProperties(), new SimpleViewManager(new EditView(), new RuntimeView(), new RuntimeView(), null));

			mLogger = LogManager.getLogger(this);
			
			mLogger.debug("This is a debugging message");
			mLogger.info("This is an informative message");
			mLogger.warn("This is a warning message");
			mLogger.error("This is an error message");
			mLogger.fatal("This is a fatal message");
			
			propertiesDialog.width = 300;
			propertiesDialog.height = 200;
		}
	}
}