New in version 1.2:

ActionScript has an amazingly functional event model. For many uses it is the most appropriate option. But at the same time it does have a performance overhead and can easily get the garbage collector out of shape if you’re not meticulous about cleaning up after yourself. But worst of all is having to read the execution order as it jumps up and down your class. There are alternatives out there that are getting positive feedback, like Robert Penner’s AS3 Signals and several frameworks like PureMVC and Robotlegs have their own internal notification models. But not all types of notification lend themselves to complex implementations like these. Sometimes a simple callback function is just the right thing. Code readability and Performance are two benefits you can reap. Strictness is another.

Here’s an example:

public function loadData ( url:String ) : void
{
	_dataParser = new DataParser();
	_dataParser.dataAvailableCallback = _notifyDataLoaded;		
	_dataLoader = new DisposableXMLLoader();
	_dataLoader.successCallback = _dataParser.setData;
	_dataLoader.load( url );
}

DisposableXMLLoader is a library class of mine that wraps the extra lines of code needed to use a URLLoader in Flash. Nothing fancy, just code I don’t need to see all the time. It also cleans up after itself after the load operation. Most of the time, only one object is interested in knowing when the load operation completes, so DisposableXMLLoader simply has public member variables named successCallback and errorCallback. The successCallback is called with the loaded XML document as it’s only argument, and errorCallback will receive whichever ErrorEvent occurred.

DataParser is a class most of my projects have in the model package. It’s sole purpose is to retrieve, cast and return data from XML in the form of primitive datatypes or value objects. It is the only class in my application that is allowed knowledge of the XML document’s structure. It also sports a public member variable to hold the callback function that is called when it is ready to start fetching data from the XML.

Using the traditional AS3 event model, the above example would be written something like this.

public function loadData ( url:String ):void
{
	_dataParser = new DataParser();
	_dataParser.addEventListener( DataParserEvent.DATA_AVAILABLE , _onDataAvailable );
	_dataLoader = new DisposableXMLLoader();
	_dataLoader.addEventListener( XMLLoaderEvent.DATA_LOADED , _onDataLoaded );
	_dataLoader.load( url );
}
 
private function _onDataLoaded ( e:XMLLoaderEvent ):void
{
	_dataParser.setData( _dataLoader.getData() );
}
 
private function _onDataAvailable ( e:DataParserEvent ):void
{
	_notifyDataLoaded();
}

In fact this would probably be even more complex because if I wasn’t using callbacks, I would probably have used a standard URLLoader instead. Wiring up one of those for both success and error handling would produce about twice as many lines of code.

To be honest, I usually don’t really care that much about performance. Most of what I do is not that intensive anyway. But I do care about clean code and what I love about the callback approach is how compact it all becomes and the fact that I can see the whole execution order in just 5 lines of code. If I wanted, I could compress the code even more by adding the callbacks as constructor arguments, but I prefer the explicitness of that extra line.

Just remember to null the reference to the callback after you call it.

In AS2 we had the implicit callee object inside a function scope that would carry a reference to the currently executing function. In AS3 a bit more hacking is required. Whenever an error is thrown, you notice the stack trace below it. this contains all you need for debugging purposes and we can massage it a bit to present it in a more focused fashion.

This stack trace is produced whenever a new Error object is instantiated and with the “throw” keyword in front of it, it’ll show up like above. No error dialog is spawned if you don’t throw the error instance, but the stack trace is still produced, and you can reference it with the getStackTrace method. After that, it’s all parsing to get to the bits you want.

For instance, I wanted to display just the class name and line number. This will do the trick:

var location:String = new Error().getStackTrace().match( /(?<=\/)\w+?.as:\d+?(?=])/g )[1].replace( ":" , ", line " );
trace( location );

This will output something similar to this (depending on the location it was called from):

ComponentView.as, line 89

I used this to create a nullFunction that can be inserted in place of undefined function references (see below for the class) Olog displays it like this:

Here’s the class:

package com.oyvindnordhagen.framework.nullobj
{
	import no.olog.Olog;
 
	/**
	 * @author Oyvind Nordhagen
	 * @date 3. sep. 2010
	 */
	public function nullFunction ( ...args ):void
	{
		var location:String = new Error().getStackTrace().match( /(?<=\/)\w+?.as:\d+?(?=])/g )[1].replace( ":" , ", line " );
		trace( location );
		var text:String = "Null Function Reference";
		text += (args && args.length > 0) ? " with arguments " + args.join( ", " ) : "";
		text += " at " + location;
		Olog.trace( text , 2 );
	}
}

Use coding standards and best practices

Proper method names, argument names, argument types and return values are crucial to the mere mortals trying to use your API. Keep an eye on your naming schemes! Use the common denominator of data types when you can and create specialized value objects when necessary. This method signature might make perfect sense to you at a time of writing:

1

getCoords( arg1:*, arg2:*, ar3:*):Object

…but please clean that up when you release it to the general public! Answer me this: What kind of coordinates are we requesting? What kind of input is expected and what are their types? And what the hell does that generic return type contain exactly?? Might I suggest something like:

1

getCityCoordinates( region:String, country:String, city:String):Coordinates

You might think this kind of thing is trivial and basic. And it is, hence my bafflement when I read stuff like the first example in library released as the official API for one of the more common social media RIAs. You couldn’t imagine how many APIs out there break away from such common sense.

Clean up after yourself!

There are libraries out there without a single line terminated by a semi colon. As we know, the semis are optional, but they can cause the dreaded “internal build error/classes may not be nested” situation in Eclipse-based IDEs which usually eats up at least half a day of valuable time. I’ve had it happen to me, and needless to say I don’t consider semi colons to be optional. I use FDT to write my code and I have it set up to present me with an error whenever it comes across an unterminated line.

Other known culprits of internal build error are empty constructs like if-, for-, while and switch statements in addition to empty classes and interfaces. If there are incomplete sections in the API, pull them out and make sure the rest of the code doesn’t reference them.

Write proper ASDocs

How many libraries out there merely repeat the method signatures in the ASDocs? Then what’s the point? Most sane people use advances IDEs that will present ASDocs even inline with the code hinting, so make the most of it when the function and argument names cannot convey the full purpose of a property, event or method. To demonstrate, I will give an example from the ASDocs of my own logger utility, the Olog. I will not be humble in this case, because Olog’s ASDocs are in fact immaculate.

The main logic is spread across 10 classes, but there’s only two access points to the log console; the specialized event type and the Olog class itself. The Olog class serves a single purpose: It is the interface, the Application Programming Interface. It serves as the entry and exit point and the position of all the documentation. The core of the module is not as pretty, but that’s my problem. The Olog class consists of well named functions and getters and setters, all with comprehensive and highly cohesive ASDocs. In a sense you could say that this class’ primary purpose is to act as the black surface coating in the black box principle; it’s there to stop the reader from digging deeper, or should I say to make it totally unnecessary to dig deeper. Most of the methods have a single line in them, a call to another core method. This allows this class to focus on the task of providing decent documentation. The ASDocs are generated from this file.

This is a method from within the core of Olog:

1
2
3
4
5
6
7

internal static function newTimeMarker(name:String = null, origin:Object = null):int
{
	var n:String = (name) ? name : "Operation";
	var o:String = Otils.parseOrigin( origin );
	var t:int = getTimer( );
	return _runTimeMarkers.push( [n, t, o] ) - 1;
}

But from the outside of the box it appears like this:

1
2
3
4
5
6
7
8
9
10
11

/**
* Creates a timing marker that you can later complete by calling completeTimeMarker() to
* output the time in between.
* @param name String reference to use when the marker completes an results are displayed.
* @return An integer ID to use as argument when calling completeTimeMarker().
* @see completeTimeMarker()
*/
public static function newTimeMarker(name:String = null, origin:Object = null):int
{
	return Ocore.newTimeMarker( name , origin );
}

Thats a ratio of 5:2 of respectively documentation and actual code! By using the Olog class as a dedicated API layer, I’m able to use that class as both a source of proper ASDocs and a structural reference for myself.

Now, pretty please…?

Normally, whenever you do this:

var mic:Microphone = Microphone.getMicrophone();

The Flash Player automatically opens this panel to ask the user to allow the microphone to be connected:

Of course this panel is never invoked if the user has the settings set to always allow or always deny, but very few do.

When this sucker never presented itself, I naturally thought that I was doing something wrong. Let’s face it, that’s the most probable cause. But after a while I noticed that the problem was specific to Firefox on the Mac. Knowing that SWFObject has had it’s issues with FIrefox in the past, I tried swapping it out for the jQueryFlash plugin, and voilà! How the JavaScript insertion method of the flash content could possibly cause it is beyond me. Honestly I don’t have the JS knowledge or interest to investigate either, seeing as I had a solution.

With SWFObject 1.5 there was a problem causing the stageWidth and stageHeight to be 0 for a certain time after the movie was loaded. That might be relevant in this case as well, but the microphone dialog was supposed to open long after the movie was fully loaded. That kinda rules it out.

So now you know. Don’t spend an entire night on this, like I did.

Get the Flash plugin for jQuery here:
http://jquery.lukelutman.com/plugins/flash/

Olog (formerly, AILogger formerly OKtrace, formerly text field on stage..) is a logging utility I have been using since the early days. The previous version, AILogger has been the most feature rich to date. But over the years a need to rewrite the whole thing has been growing more and more urgent. It actually started life as an AS1 text field on stage, and was then made into an AS2 class which was then refactored for AS3. But after a while it became evident that it had been patched up too many times to do new things and was in desperate need of some overhaulin’.

It’s about time it took its name from its father as well, so I’m abandoning the scheme of naming it after my employer. (OKTrace = Okular, AILogger = Allegro Interaktiv). It has always been my pet project, so I’m taking it with me everywhere I go from now on. I also wanted a short name, seeing as I’ll be typing it a lot, so Olog it is (the “O” from Oyvind).

So this time it’ll be different, I promise! Olog 0.9 is actually AILogger 1.2 and then some in terms of features, but the first step in making it was “File > New”. It’s completely rewritten, and no copy-paste this time. It has been tagging along during my latest project and so it has seen plenty of action already. I’ve tested it quite thoroughly, but it’s hard to say what happens when you try to live on your own for the first time. That’s why I have humbly versioned it 0.9b for now.

New features

Here are some new things you might like:

• Full featured window interface. Minimize/maximize/close buttons, double click on title bar to minimize. Moveable and resizable.
• Selective line numbers, time-since-movie start and clock time for each line. These can all be turned of or off during run time.
• Filtering of log levels. Pressing number keys 0-5 filters the log to show only those severity levels (color). Esc to escape.
• Automatic update check. Olog will check for a new version once a week if you let it and notify you if there’s a newer version.
• Save log to text/XML.
• Persistent window state. Position, size, minimized/maximized state is remembered so you don’t have to keep moving it out of the way each time you compile.
• Run time markers. Set a new named point-in-time marker, which you can later complete to display load/execution times.
• Support for AILoggerEvents, but Olog has it’s own OlogEvent as well for loosely coupled logging.
• Stacking of repeated messages.
• Full ASDoc documentation.

The olog page on my blog has all the links you need, direct ZIP download, SVN repo access, asdoc documentation, Google Code homepage and even a simple demo. I’ll love to hear it if you have feedback!

Today I had the dreaded “1131: Internal build error” in Flash Builder coupled with the “Classes must not be nested error” despite no classes actually being nested. Googling around, I found a few posts that provide some tips towards a solution. The most frequent two of which are empty switch statements and ActionScript lines that are not properly terminated with a semicolon. The project in questing uses over 100 classes, so I decided to create a RegExp for use in “Find In Files” to search for lines that were not properly terminated.

As an extra caveat, many types of lines in programming are not supposed to be terminated, so the RegExp is quite long and I have not been able to test it any more than the said 100-class project I’m working on.

NOTE: This might macth some multiline ASDoc comments, empty lines and method argument lists spanning multiple lines as well.

(?sim)(?<!/\*)^\t*((?!\{|\}|@)(?!function|import|class|embed|SWF|if|else|switch|case|while|for|event|try|catch|finally|package|default|//|/\*|\*/)[^;])+$(?!.*\*/)

Here are the posts I found:

• flex’d: “Internal Build Error” or “Classes Must Not Be Nested” error
• Inside RIA: Fixed: “An internal build error has occurred” with FB3 & Galileo
• Tink: An internal build error has occurred (switch statement)
• Michael Imhoff: Internal Build Error
• judah’s blog: Internal Build Error

EDIT: Added “default” to the RegExp. If anyone has any improvements to this, please let me know. Especially on how to make it not match so many empty lines.

Download SlowLoader.as

It works very much the same way as the Loader class with the only difference being that you add your event listeners directly to the SlowLoader instance instead of the contentLoaderInfo instance of the Loader instance. Other than that it dispatches the same events as the Loader class does so it should be fairly simple to swap it for a regular Loader when you’re done. I’ve also included and example class. Here’s an excerpt of it:

1
2
3
4

var l:SlowLoader = new SlowLoader();
l.addEventListener(ProgressEvent.PROGRESS, _updateProgress);
l.addEventListener(Event.INIT, _showImage);
l.load(new URLRequest("file.jpg"), 512, 0.9);

NOTE: SlowLoader was developed for my own use, which means that it dispatches AILoggerEvents for printing log messages from it. AILogger is also included in the ZIP file and you can read more about it here. If you do not wish to use it, feel free to strip these lines out of the class.

As some of you might know, I’m in layoff from my job as a flash developer at Allegro Interaktiv. I’ve been thinking hard and well about what I want to spend this period of four months doing. I will be freelancing a little if I can (in agreement with my employer of course), spend time with my family, and also catch up on a few forsaken hobbies.

But this sudden abundance of free time obviously creates a pefect climate for getting up to speed on new Flash libraries and dig deeper into the ones I already know. Like the AS3 core classes. That’s why I’ve given my self a perhaps rediculous challenge; to read the complete ActionScript Language Reference back to back over the next four months. This is clearly perversely nerd-like and all that, but here’s why.

The case for reading it all

Actually I’ve been thinking about it for a few years. You see every time I look up a class or a method in the dictionary, I usually read one or two paragraphs more than I need. Often I learn something new that’s been sitting just below the surface of what I already know. At times the AS3 language reference is not even that badly written and the examples are usually useful. So instead of googling for tutorials about particle engines, Papervision and what not, I decided that before trying to gain something completely new I’d be better off getting to know the old annoying aunt intimately. Well not in that sense… sorry, you know what I mean.

You should too!

I’m not saying you really should join me in this preposterous endeavour, but I am serious in that many tend to overlook what a great resource the AS3 Language Reference really is. So the essence is really that you can learn a lot from what you already have at a single keyboard command (shift-F1 in Flash that is). Look up some random class name that you’ve never used an find out what it’s for. You might be glad you did.

In the mean time, you can follow my progress here at the blog, and if you follow me on Twitter.

• Added public describe method to log all properties of an object
• Added support for CODE_TRACE, these lines are color coded gray.
• passwordDisabled property renamed to disablePassword
• stampLinesWithSender property renamed to disableSenderLabel
• Fixed support for CODE_EVENT log coloring
• Supports new paramteter origin in AILoggerEvent to specify the sender of a log message
• Better handling of logged ErrorEvents
• Now recognizes logged color numbers and displays it’s HEX code and colors the line with that color

Get it here