Calypso88

Today - as is usually the case with these posts - I found myself writing code that I've written a dozen times before. I had some animation keyframed out on the timeline that I wanted to export as a stack of pngs.

I know there are a few tools built in that should be able to do this for me, but in the past I've had lots of trouble getting them to work - I usually end up getting dropped frames and strange behavior for nested MCs and the like.

So today I took a little extra time and made a timeline exporter that should be pretty robust. The basic idea is that we take manual control of the framerate and snapshot each frame, which is saved out to a folder during runtime. In order to pull this off, we need to the flash.filesystem package so your fla needs to be targetting the AIR runtime. In CS5.5 you can change this on the fly under Publish Settings (look for the Player menu up at the top) - I recall that on older versions of Flash you would have to make a new AIR project and copy your animation into it. FWIW it wouldn't be too hard to modify this script to load an external swf file and use that as the animation source if copying things out of one fla into another is too big of a problem.

Anyhow - with your animation in a fla targetting AIR - drop this code into the first frame of the timeline and jump into the configuration block at the top of the script. You'll want to set up your cropping and file path here, and set targetMC to point at whatever you want to capture; it can be a specific MovieClip or you can just set it to "this" and grab the whole stage.

When you have the config options fine tuned, compile the fla (you don't even need to save it) and you'll be prompted for a directory to save into. As soon as you do that, the animation is captured frame by frame and saved off into the folder you chose.

Two things to be aware of in here - first, this script uses recursion in a couple of places. If you're not familiar (or even if you are) that means that the amount of processing going on is going to scale up with how many MCs and other objects the code has to dig through. Anything with a ton of symbols or very deep nesting could get you into trouble. I highly recommend you save your work (in all programs - not just Flash) before testing this! It is very possible to crash the player as well as Flash or even your whole system. You've been warned - use this at your own risk.

Second - the png exporting used here is from as3corelib. I copied the com.adobe.images.PNGEncoder class right into the bottom of the script (with some tiny tweaks) to make the whole thing self-contained. While everything I write for this blog is available under the MIT license unless otherwise noted, the portion of this script from as3corelib is offered under their original license included at the top of that block of code, and also available on the as3 corelib project page here. If you encounter Darron Schall or Mike Chambers - buy those guys a beer or two!

//====================================================
//  WARNING
//====================================================
 
	/**
	 *  WARNING: This script uses recursion.
	 *  For animations with a large number of symbols
	 *  or deep nesting, this may run slowly and
	 *  could time out the script.
	 *
	 *  This script could also crash itself, Flash,
	 *  or your entire computer - please save your work
	 *  before testing. Use at your own risk!
	 */
 
//====================================================
//  CONFIGURATION
//====================================================
 
	//  REMEMBER! If you're getting errors on compile, make sure
	//  the project is set up to export as an AIR app - not a swf!
 
	//  name of the file - {FRAME_NUMBER} will be populated dynamically
	var outputFileName:String = 'demo_{FRAME_NUMBER}.png';
 
	//  fill in the instance name of your animation
	var targetMC:MovieClip = this;
 
	//  dimensions of the images saved out
	var outputWidth:int = 79;
	var outputHeight:int = 79;
 
	//  do you want transparent-pngs or not?
	var transparent:Boolean = true;
 
	//  if not-transparent - what color background?
	var matteColor:uint = 0x000000;
 
	//  Number of characters in the frame number. Ex. 3 = "001", 5 = "00001"
	var frameNumberDigits:uint = 3;
 
	//  Whether we should look for nested animations.
	//  This may be very cpu intensive!
	//  NOTE: Newer versions of Flash do this automatically.
	var useNestedAnimation:Boolean = true;
 
	//  Whether nested animations will loop or stop when finished playing.
	var loopNestedAnimations:Boolean = true;
 
//====================================================
//  DO NOT EDIT BELOW THIS POINT
//====================================================
 
	import flash.filesystem.*;
	import flash.display.*;
 
	//  stop playback - we'll control this on our own from here on out
	stop();
	(useNestedAnimation) ? stopRecursively(targetMC) : targetMC.stop();
 
	//  a few vars we'll need over the frame loop
	var bmd:BitmapData;
	var baseFile:File = new File();
	var fs:FileStream = new FileStream();
 
	//  ask for a directory we can save into
	baseFile.addEventListener(Event.SELECT, saveToDirectoryChosen);
	baseFile.addEventListener(Event.CANCEL, saveToDirectoryAborted);
	baseFile.browseForDirectory('Save image stack to');
 
	function saveToDirectoryChosen(e:Event):void{
		e.target.removeEventListener(Event.SELECT, saveToDirectoryChosen);
		e.target.removeEventListener(Event.CANCEL, saveToDirectoryAborted);
		addEventListener('enterFrame', eFrame);
	}
 
	function saveToDirectoryAborted(e:Event):void{
		e.target.removeEventListener(Event.SELECT, saveToDirectoryChosen);
		e.target.removeEventListener(Event.CANCEL, saveToDirectoryAborted);
		trace('Save directory not chosen - aborting export.');
	}
 
	function eFrame(e:Event):void{
		bmd = new BitmapData(outputWidth, outputHeight, transparent, matteColor);
		bmd.draw(targetMC);
 
		var num:String = String(targetMC.currentFrame);
		while(num.length < frameNumberDigits) num = '0' + num;
 
		var f:File = new File(baseFile.url + '/' + outputFileName.replace('{FRAME_NUMBER}', num));
		trace('Frame ' + num + '\t=>\t' + f.url);
 
		fs.open(f, 'write');
		fs.writeBytes(encode(bmd));
		fs.close();
 
		if(targetMC.currentFrame == targetMC.totalFrames){
			e.target.removeEventListener(e.type, arguments.callee);
			trace('========================================');
			trace(targetMC.totalFrames + ' frames captured over ' + (getTimer() / 1000).toFixed(2) + 'seconds.');
		} else {
			advanceFrame(targetMC as DisplayObjectContainer);
		}
	}
 
	//  WARNING: This is a recursive function - it may bog down or crash on
	//  excessively deep or complicated display trees!
	//  SAVE YOUR FILE BEFORE TESTING!!
	function advanceFrame(doc:DisplayObjectContainer):void{
		if(!doc || doc.numChildren < 1) return;
 
		//  loop through children - recursively advancing each mc we find
		var i:int = doc.numChildren;
		while(i--){
			var dobj:DisplayObject = doc.getChildAt(i);
			if(dobj is DisplayObjectContainer) advanceFrame(dobj as DisplayObjectContainer);
		}
 
		//  then nextframe self
		if(doc is MovieClip && MovieClip(doc).totalFrames > 1){
			if(MovieClip(doc).currentFrame == MovieClip(doc).totalFrames){
				if(loopNestedAnimations) MovieClip(doc).gotoAndStop(1);
			} else {
				MovieClip(doc).nextFrame();
			}
		}
	}
 
	//  WARNING: This is a recursive function - it may bog down or crash on
	//  excessively deep or complicated display trees!
	//  SAVE YOUR FILE BEFORE TESTING!!
	function stopRecursively(doc:DisplayObjectContainer):void{
		if(!doc) return;
		if(doc is MovieClip) MovieClip(doc).stop();
 
		var i:int = doc.numChildren;
		while(i--){
			var dobj:DisplayObject = doc.getChildAt(i);
			if(dobj is DisplayObjectContainer) stopRecursively(dobj as DisplayObjectContainer);
		}
	}
 
//====================================================
//====================================================
//  Below here is the PNGEncoder Class from Adobe's
//  as3corelib - embedded directly here for so you
//  can quickly paste this into a .fla without
//  setting up import paths or project structure.
//
//  Class and scope structure commented out,
//  no changes made to functionality.
//
//  @see: https://github.com/mikechambers/as3corelib
//====================================================
//====================================================
 
/*
  Copyright (c) 2008, Adobe Systems Incorporated
  All rights reserved.
 
  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions are
  met:
 
  * Redistributions of source code must retain the above copyright notice,
    this list of conditions and the following disclaimer.
 
  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.
 
  * Neither the name of Adobe Systems Incorporated nor the names of its
    contributors may be used to endorse or promote products derived from
    this software without specific prior written permission.
 
  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
  IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
//package com.adobe.images
//{
	import flash.geom.*;
	import flash.display.Bitmap;
	import flash.display.BitmapData;
	import flash.utils.ByteArray;
 
	/**
	 * Class that converts BitmapData into a valid PNG
	 */
//	public class PNGEncoder
//	{
		/**
		 * Created a PNG image from the specified BitmapData
		 *
		 * @param image The BitmapData that will be converted into the PNG format.
		 * @return a ByteArray representing the PNG encoded image data.
		 * @langversion ActionScript 3.0
		 * @playerversion Flash 9.0
		 * @tiptext
		 */
	    /*public static*/ function encode(img:BitmapData):ByteArray {
	        // Create output byte array
	        var png:ByteArray = new ByteArray();
	        // Write PNG signature
	        png.writeUnsignedInt(0x89504e47);
	        png.writeUnsignedInt(0x0D0A1A0A);
	        // Build IHDR chunk
	        var IHDR:ByteArray = new ByteArray();
	        IHDR.writeInt(img.width);
	        IHDR.writeInt(img.height);
	        IHDR.writeUnsignedInt(0x08060000); // 32bit RGBA
	        IHDR.writeByte(0);
	        writeChunk(png,0x49484452,IHDR);
	        // Build IDAT chunk
	        var IDAT:ByteArray= new ByteArray();
	        for(var i:int=0;i < img.height;i++) {
	            // no filter
	            IDAT.writeByte(0);
	            var p:uint;
	            var j:int;
	            if ( !img.transparent ) {
	                for(j=0;j < img.width;j++) {
	                    p = img.getPixel(j,i);
	                    IDAT.writeUnsignedInt(
	                        uint(((p&0xFFFFFF) << 8)|0xFF));
	                }
	            } else {
	                for(j=0;j < img.width;j++) {
	                    p = img.getPixel32(j,i);
	                    IDAT.writeUnsignedInt(
	                        uint(((p&0xFFFFFF) << 8)|
	                        (p>>>24)));
	                }
	            }
	        }
	        IDAT.compress();
	        writeChunk(png,0x49444154,IDAT);
	        // Build IEND chunk
	        writeChunk(png,0x49454E44,null);
	        // return PNG
	        return png;
	    }
 
	    /*private static*/ var crcTable:Array;
	    /*private static*/ var crcTableComputed:Boolean = false;
 
	    /*private static*/ function writeChunk(png:ByteArray,
	            type:uint, data:ByteArray):void {
	        if (!crcTableComputed) {
	            crcTableComputed = true;
	            crcTable = [];
	            var c:uint;
	            for (var n:uint = 0; n < 256; n++) {
	                c = n;
	                for (var k:uint = 0; k < 8; k++) {
	                    if (c & 1) {
	                        c = uint(uint(0xedb88320) ^
	                            uint(c >>> 1));
	                    } else {
	                        c = uint(c >>> 1);
	                    }
	                }
	                crcTable[n] = c;
	            }
	        }
	        var len:uint = 0;
	        if (data != null) {
	            len = data.length;
	        }
	        png.writeUnsignedInt(len);
	        var p:uint = png.position;
	        png.writeUnsignedInt(type);
	        if ( data != null ) {
	            png.writeBytes(data);
	        }
	        var e:uint = png.position;
	        png.position = p;
	        c = 0xffffffff;
	        for (var i:int = 0; i < (e-p); i++) {
	            c = uint(crcTable[
	                (c ^ png.readUnsignedByte()) &
	                uint(0xff)] ^ uint(c >>> 8));
	        }
	        c = uint(c^uint(0xffffffff));
	        png.position = e;
	        png.writeUnsignedInt(c);
	    }
//	}
//}

This probably brands me as an old-school AS2 crank, but I have to admit that I'm not the biggest fan of the FlashBuilder debugger. Don't get me wrong, I use it daily and it's miles ahead of the Flash Pro version; but for my money, there is still a lot of mileage left in the old trace console.

To really get good utility out of tracing, I find that I write the same helper methods over and over again in every project. The big one being a function for converting collections (Objects, Arrays, etc) to a readable format. I took a little time over the last week and tried to get this implementation as bulletproof as possible, and I'm finally pretty happy with where it is.

I'm intending to add this to T-Rex Arms either as a top level utility function, or else as a helper in the Console. In the meantime, you can drop it into a project wherever you need an eye on your data.

/**
 *	Attempts to convert any object to a human-readable string format.
 *	Ordered collections (Arrays and Vectors) are listed in Array notation: [1, 2, 3]
 *	Associative arrays are listed in Object notation between square braces: ["a":1, "b":2, "c":3]
 *	Unordered collections (Objects and Dictionaries) are listed in Object notation: {a:1, b:2, c:3}
 *
 *	This function will use recursion to deep-trace nested objects. For
 *	better control of this, there is a maxLevelsDeep parameter that will
 *	limit the number of levels deep the trace can go. A value of 0 allows
 *	no nesting (ex: {a:[object Object]}), a positive value specifies the
 *	number of layers down permitted, and a negative value will recurse
 *	indefinitely.
 *
 *	WARNING: attempting to stringify large or deep objects
 *	can create timeouts. Using extremely deep objects or objects with circular
 *	references can trigger stack overflow errors. This utility should only be
 *	used during development - not on production code!
 *
 *	@param data Any Object, collection, or piece of data to conver to a String.
 *	@param maxLevelsDeep The maximum recursion allowed. Default is 3 layers deep.
 *	@return A string representation of the data passed in.
*/
function stringify(data:*, maxLevelsDeep:int = 3):String{
	if(data == null) return 'null';
	if(data == undefined) return 'undefined';
	if(data is String) return '"' + data + '"';
	if(data is Boolean) return (data) ? 'true' : 'false';
	if(data is Number) return Number(data).toString();		//  this will catch int and uint as well
 
	//  if this condition triggers we're dealing with something not listed above but not an object...mystery primitive?
	if(!data || (!(data is Object) && !'constructor' in data)) return data + '';
 
	var s:String = '', i:int = 0, len:int = 0, alen:int = 0, key:*, val:*, o:Object, a:Array, v:Vector.<*>, isAssociative:Boolean, toStr:String;
 
	if(data is Array){
		a = data as Array;
		len = a.length;
		s = '[';
 
		//  to detect associative arrays, we look for any keys that are not
		//  type int, and we look for more elements than there are indices
		for(key in a){
			if(!(key is int) || ++alen > len){
				isAssociative = true;
				break;
			}
		}
 
		if(isAssociative){
			//  confirmed that we are dealing with an associative array...
			//  we need to parse this by key
			for(key in a){
				val = a[key];
				s += (key is String) ? '"' + key + '":' : key + ':'; 
 
				//  this block of checks is more verbose but it guards us against a lot of unnecessary recursion...
				if(val == null)				s += ', ';
				else if(val == undefined)	s += 'undefined, ';
				else if(val is String)		s += '"' + val + '", ';
				else if(val is Boolean)		s += (data) ? 'true, ' : 'false, ';
				else if(val is Number)		s += Number(val).toString() + ', ';
				else if(maxLevelsDeep)		s += stringify(val, maxLevelsDeep - 1) + ', ';
				else if(val is Array || val is Vector.<*> || val is Vector.<int> || val is Vector.<uint> || val is Vector.<Number>) s += '[' + val + '], ';
				else						s += val + ', ';
			}
 
		} else {
			//  this is a normal array - we can parse by index
			if(!len) return '[]';
			for(i = 0; i < len; ++i){
				val = a[i];
				if(val == null)				s += ', ';
				else if(val == undefined)	s += 'undefined, ';
				else if(val is String)		s += '"' + val + '", ';
				else if(val is Boolean)		s += (data) ? 'true, ' : 'false, ';
				else if(val is Number)		s += Number(val).toString() + ', ';
				else if(maxLevelsDeep)		s += stringify(val, maxLevelsDeep - 1) + ', ';
				else if(val is Array || val is Vector.<*> || val is Vector.<int> || val is Vector.<uint> || val is Vector.<Number>) s += '[' + val + '], ';
				else						s += val + ', ';
			}
		}
 
		if(s.length < 3) return '[]';
		if(s.substr(s.length - 2, 2) == ', ') s = s.substring(0, s.length - 2);
		return s + ']';
	}
 
	if(data is Vector.<*> || data is Vector.<int> || data is Vector.<uint> || data is Vector.<Number>){
		//  The number types (Number, int, uint) don't seem to upcast to
		//  work as Vector.<*> so we need some extra cases here...
		s = '[';
		v = data;
		len = v.length;
		for(i = 0; i < len; ++i){
			val = v[i];
			if(val == null)				s += ', ';
			else if(val == undefined)	s += 'undefined, ';
			else if(val is String)		s += '"' + val + '", ';
			else if(val is Boolean)		s += (data) ? 'true, ' : 'false, ';
			else if(val is Number)		s += Number(val).toString() + ', ';
			else if(maxLevelsDeep)		s += stringify(val, maxLevelsDeep - 1) + ', ';
			else if(val is Array || val is Vector.<*> || val is Vector.<int> || val is Vector.<uint> || val is Vector.<Number>) s += '[' + val + '], ';
			else						s += val + ', ';
		}
 
		if(s.length < 3) return '[]';
		if(s.substr(s.length - 2, 2) == ', ') return s.substring(0, s.length - 2) + ']';
		return s + ']';
	}
 
	//  At this point we're dealing with either a complex Object...
	s = '{';
	o = data as Object;
 
	for(key in o){
		s += key + ':';
		val = o[key];
		if(val == null) 			s += 'null, ';
		else if(val == undefined)	s += 'undefined, ';
		else if(val is String)		s += '"' + val + '", ';
		else if(val is Boolean)		s += (data) ? 'true, ' : 'false, ';
		else if(val is Number)		s += Number(val).toString() + ', ';
		else if(maxLevelsDeep)		s += stringify(val, maxLevelsDeep - 1) + ', ';
		else if(val is Array || val is Vector.<*> || val is Vector.<int> || val is Vector.<uint> || val is Vector.<Number>) s += '[' + val + '], ';
		else						s += val + ', ';
	}
 
	if(s.length < 3){
		if(Object(o).constructor && Object(o).constructor != Object){
			if('toString' in o && o['toString'] && o['toString'] is Function){
				try{
					//  we only attempt this on complex data types with a
					//  defined toString method that didn't stringify above...
					toStr = o.toString();
					if(toStr.length > 2) return toStr;
				} catch(err:Error){}
			}
 
			//  no toString() - no visible attributes, and not an Object
			//  lets just send back the class...
			return Object(o).constructor + '';
		}
 
		//  This should only trigger for raw Objects with nothing in them...
		return '{}';
	}
 
	if(s.substr(s.length - 2, 2) == ', ') return s.substring(0, s.length - 2) + '}';
	return s + '}';
}

I set it up to handle all of the collection types: Arrays, Associative Arrays, Vectors, Dictionaries, and Objects, in addition to the primitive data types. If the input doesn't fall into those categories, it will still try to read any public attributes visible to a for-in loop.

This function is also set up for deep recursion (read the header comment) for nested or multi-dimensional collections. I hope someone else out there gets some use from this - and as always, if you find any bugs please let me know. Finally, if you want to explicitly add support to a class, just give it a toString() method. And now for some examples!

var someObj:Object = {a:1, b:2, c:3};
trace(stringify(someObj));
//  {a:1, b:2, c:3}

var someObj:Dictionary = new Dictionary();
someObj[stage] = new Date();
someObj['foo'] = 'bar';
trace(stringify(someObj));
//  {[object Stage]:Mon Dec 5 15:43:59 GMT-0800 2011, foo:"bar"}

var someObj:Vector.<BitmapData> = new Vector.<BitmapData>();
someObj.push(new BitmapData(1, 1));
someObj.push(new BitmapData(2, 2));
someObj.push(new BitmapData(3, 3));
trace(stringify(someObj));
//  [[object BitmapData], [object BitmapData], [object BitmapData]]

var someObj:Array = [0, 1, 2];
someObj[5] = 'five';
trace(stringify(someObj));
//  [0, 1, 2, , , "five"]

var someObj:Array = [];
someObj['foo'] = {a:1, b:2};
someObj['bar'] = {c:3, d:4};
trace(stringify(someObj));
//  ["bar":{d:4, c:3}, "foo":{a:1, b:2}]

In the past few years I've worked with engineers from a lot of different backgrounds, which has really helped me define my own coding philosophy. It's also taught me to sanitize my data at every possible point of failure. In development this has saved me countless hours of trying to track down little bits of weirdness - I can't count the number of times a little data checking has removed a weird bug symptom on a production app when I didn't have the time to dig into deep systems and track down the original source of the bug.

This is obviously a subject as broad as there are devs in the world so I'm not going to claim this is foolproof for every situation - I'll just say that it's my go-to method for catching a lot of bugs as they get written, before they can crash the application.

//  A function expecting a generic Object with
//  "key" and "value" attributes.
//  ex. {key:'foo', value:'bar'}
public function someFunc(o:Object):void{
	if(!o || !(o is Object)){
		Console.error('Received invalid argument, expected [object Object], received ' + o);
		return;
	}
 
	if(!'key' in o || !'value' in o){
		Console.error('Malformed Object received: ' + stringify(o));
		return;
	}
 
	if(!o.key || !(o.key is String) || !o.value || !(o.value is String)){
		Console.warn('Empty parameters encountered: ' + stringify(o));
	}
 
	//  here, we know we have a valid object to process
}

A couple of things: I use the Console class from T-Rex Arms all the time now for debugging - in this example, those calls can be replaced with traces. Second, I use a stringify function to convert complex data types to readable strings - I'm polishing that function and I should post that code in the nearish future; until then you can just breakpoint those lines when they get executed.

The actual nuts and bolts of this are happening in the if-then conditions. The first checks that we have an argument at all. This will catch null, undefined, 0, NaN, false Booleans, and empty strings. This is always my first line of defense because it protects against null pointer errors later in the function. The second half of that condition is making sure we're at least dealing with an Object in some capacity - no primitive types.

The next if-then is specific to checking Objects - this is where things will diverge pretty quickly for different types of data. I deal with a lot of JSON objects coming from a server or through javascript so I always make sure my attributes exist before I start calling them.

Lastly I like to verify that the data in the attributes exist and is what I'm expecting. This is another spot where things will get pretty detailed as the data gets more complex.

If this were coming from javascript (read: Unfucking the ExternalInterface) I will use the rest operator to allow any possible value(s) to come in, before I start sanitizing. This ensures that even if a malicious call is injected, I can catch it and fail gracefully instead of locking up the application.

public function someFuncCalledByJavaScript(...args):Boolean{
	if(!args || args.length < 1){
		Console.error('JS call received with no data: expecting 1 arg');
		return false;
	}
 
	if(!args[0] || !(args[0] is Object)){
		Console.error('JS call received invalid argument, expected [object Object], received ' + o);
		return false;
	}
 
	var o:Object = args[0] as Object;
 
	//  now check the expected keys and values as before...
 
	return true; //  let JS know it did good.
}

So that's the basic checking I use. And here are some shorthands I use when I trust the data source a little better but just want to make sure things are kosher before processing them.

public function someStringFunc(s:String):void{
	if(s && s.length) //  do stuff
}
 
public function someNumFunc(n:Number):void{
	if(n && !isNaN(n)) //  do stuff
}
 
public function someIntFunc(i:int):void{
	if(i && !isNaN(i) && i > 0) //  do stuff
}

I pushed my iPad build of FoamPlucker.com to the app store on Sunday evening and it got approved last night. If you don't use Sabol foam trays to store small, oddly shaped things, then it's probably not a useful app for you - but as far as developing AS3 for iOS deployment - I learned a lot.

FoamPlucker.com

On the app store

I always jump at the chance to write a utility in AIR to help other members of my team. The short turnaround and direct communication between engineer and consumer really reminds me how hard it is to see software from the end user's perspective, and how much a small feature or bug can make or break someone's day.

One little feature I really like to include is the Application Updater built into AIR. I just implemented this a couple days ago so I wanted to document it while the pitfalls are fresh in my mind.

Start out by going into your application XML (usually AppName.xml in the default package) and find the version number. In AIR 2.5 and later this tag is <versionNumber>, before that it was just <version>; you can find the schema you're using at the end of the url in the second line of the file - something like this:

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<application xmlns="http://ns.adobe.com/air/application/2.6">
 
	<!-- Adobe AIR Application Descriptor File Template.
		...
	-->
 
	<versionNumber>1.2</versionNumber>
 

For the updater to work, the installed versions of the app will look for an xml manifest (somewhere on your webserver) to compare its own version to. Here is an example of what that file looks like:

<!--?xml version="1.0" encoding="utf-8"?-->
<update xmlns="http://ns.adobe.com/air/framework/update/description/2.5">
 
	<versionNumber>1.2</versionNumber>
	<url>http://www.static.path.to/my/Application.air</url>
 
	<description>
		1.2
		Bug fixes in the UI.
		Fixed intermittent NPE on startup.		
 
		1.1
		Optimized save/load performance.
		Reduced CPU load while rendering.
 
		1.0
		First version of the application - core functionality.
	</description>
 
</update>

Again, if you're on AIR 2.5 or later, use the 2.5 schema and the <versionNumber> tag, if you're on an earlier SDK, use the 1.0 schema and the <version> tag. The url in here is a direct link to the updated .air file, and the description text will show up as "Release notes" during the upgrade. Save this file out to a webserver somewhere and copy the address for the next step.

WARNING: As soon as you upload this file, people will start getting prompted to update - make sure the new app is ready!

Now that the xml is set up - you can handle the rest in ActionScript. As soon as your application starts up, you'll want to call this code:

var updater:ApplicationUpdaterUI = new ApplicationUpdaterUI();
 
//  point to the xml manifest on the server
updater.updateURL = "http://www.static.path.to/my/update_descriptor.xml"
 
updater.isCheckForUpdateVisible = false;
updater.isDownloadUpdateVisible = true;
updater.isDownloadProgressVisible = true;
updater.isInstallUpdateVisible = true;
 
updater.addEventListener(UpdateEvent.INITIALIZED, function(e:UpdateEvent):void{
	e.target.removeEventListener(e.type, arguments.callee);
	updater.checkNow();
});
 
updater.initialize();

Export a release build and upload the finished file to where the update descriptor is expecting it and you're finished. The next time you increment the version number in the manifest and app.xml, your users will be prompted to upgrade the next time they start the app.