mostly a codeBlog

A few months back I finally got to clean up some of my classes in an old project. I realized that it was way overdue with a custom PictureLoader Class, a lot of the clutter that made my classes hard to read was try catch and Event handling. When loading a simple piece of graphics into an AIR app(Flash, Flex also of course) you will go through at least these steps:

1. declare loader, url and eventListener.
2. write listener method
3. start loading
4. catch complete event and add the loader to the displayList

Ok, not that much work and only a bit of clutter, however I am programming these AIR apps for a 52″ touch screen, meaining no mouse or keyboard, and any exception not caught will result in the UI being rendered useless and me having to VPN into the system and restart it. I really do not want to do this so here is the list that everyone should abide by when loading anything

1. declare loader, url and eventListener for ProgressEvent, IOErrorEvent and CompleteEvent
2. write listener methods for all of the above events
3. wrap the loader into a try/catch block to catch exceptions
4. catch complete or error event and remove all the EventListeners
5. cast the content of the loader into the appropriate type
6. copy this new content into a new object so that the loader can be null’ed and memory freed up

Ok, suddenly a lot of work and subsequently heaps of clutter. This is a result of the Event driven way of ActionScript 3.0 but a small price for the OOP architecture it now builds upon. I wished to encapsulate all the Event logic into the loader and have that deal with it, the Event code adds clutter. The solution uses the same approach as the Proxy Class so if You tried extending that this will make perfect sense. The main idea is to instantiate a PictureLoader object and pass it the methods that should be executed when events happen and let the PictureLoader handle all garbage collection and event clutter (Ok I’ll stop using the word clutter now, promise).

/**
* Author: Ricki Gregersen www.rickigregersen.com
* GPL: All code is snatch and grab
*/
package com.rickigregersen.loaders
{
	import flash.display.Bitmap;
	import flash.display.Loader;
	import flash.events.Event;
	import flash.events.IOErrorEvent;
	import flash.events.ProgressEvent;
	import flash.net.URLRequest;

	public class PictureLoader extends Loader
	{
		private var pic:Bitmap;
		private var loader:Loader
		private var percent:int;
		private var failFunction:Function;
		private var progressFunction:Function;
		private var successFunction:Function;

		public function PictureLoader()
		{
			//the worlds blankiest blank...
		}
		public function loadPicture(url:String, success:Function = null,  progress:Function = null, fail:Function = null):void
		{
			//set the local functions to your global functions
			failFunction = fail;
			progressFunction = progress;
			successFunction	= success;
			//make the needed objects ready
			pic = new Bitmap();
			loader = new Loader();
			//Add a listener for all the different events the could be fired
			loader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, pictureProgress, false, 0, true);
			loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, pictureFailed, false, 0, true);
			loader.contentLoaderInfo.addEventListener(Event.COMPLETE, pictureLoaded, false, 0, true);
			//Wrap the load method in a try-catch to catch any wildcard errors that could break the VM
			try{
				loader.load(new URLRequest(url));
			}catch(error:Error){
				pictureFailed();
			}
		}
		//getters for the percent loaded and the picture
		public function get progress():int
		{
			return percent;
		}
		public function get picture():Bitmap
		{
			return pic;
		}
		//Functions to catch the events
		private function pictureProgress(event:Event):void
		{
			percent = (loader.contentLoaderInfo.bytesLoaded / loader.contentLoaderInfo.bytesTotal) * 100;
			//call the parents progressFunction to alert it that a loadProgress has happend
			progressFunction();
		}

		private function pictureLoaded(event:Event):void
		{
			//cast the picture into a bitmap, before this the picture is of type "loader.content"
			pic = (Bitmap)(event.target.content);
			//remove the eventlistener
			loader.contentLoaderInfo.removeEventListener(Event.COMPLETE, pictureLoaded);
			loader.contentLoaderInfo.removeEventListener(IOErrorEvent.IO_ERROR, pictureFailed);
			loader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS, pictureProgress);
			//make sure to free the memory and null the loader
			loader.unloadAndStop(true);
			loader = null;
			//call the parents pictureLoaded function to alert it the picture was loaded and ready to be picked up
			successFunction();
			//successFunction(pic); could have been used, just send the parent function a reference to the picture.
			//But I like getter/setters. As long as the method in the parent accepts a bitmap as input you don't have to worry about it
			//in here.
		}
		private function pictureFailed(event:Event = null):void
		{
			//Loading failed, so clean the loader and alert the parent
			loader.contentLoaderInfo.removeEventListener(Event.COMPLETE, pictureLoaded);
			loader.contentLoaderInfo.removeEventListener(IOErrorEvent.IO_ERROR, pictureFailed);
			loader.contentLoaderInfo.removeEventListener(ProgressEvent.PROGRESS, pictureProgress);
			loader.unloadAndStop(true);
			loader = null;
			failFunction();
		}
	}
}

This is how it is used, notice that this is complete with all the logic for listening for the complete, progress and error events.

			import com.rickigregersen.loaders.PictureLoader;

			private var picLoader:PictureLoader;
			private var pic:Bitmap;
			private var container:Sprite;

			private function init():void
			{
				picLoader = new PictureLoader();
				picLoader.loadPicture("assets/picture.png", picLoaded, picProgress, picFailed);
			}

			private function picProgress():void
			{
				trace(picLoader.progress);
			}
			private function picLoaded():void
			{
				pic = picLoader.picture;
				rawChildren.addChild(pic);
			}
			private function picFailed():void
			{
				trace("error loading picture");
			}

The functions passed to the PictureLoader are not mandatory, they are all set to null as default.

This means that the really short version of using this Class is like this:

			import com.rickigregersen.loaders.PictureLoader;

			private var picLoader:PictureLoader;
			private var pic:Bitmap;
			private var container:Sprite;

			private function init():void
			{
				picLoader = new PictureLoader();
				picLoader.loadPicture("assets/picture.png", picLoaded);
			}

			private function picLoaded():void
			{
				rawChildren.addChild(picLoader.picture);
			}

The use of rawChildren.addChild(picLoader.picture) is because this originates from a UIComponent in Flex so all other places you would use addChild.

So when building Components or just Classes that handle lots of Events and loading of external assets, this approach is something to consider.