grumblecode

closures in actionscript

2010-03-04T07:35:00.000-08:00

From time to time, I've read that you can use closures in Actionscript, but I've never found a use for them until now. Before I explain that use, let me go over what closures are and how they work.

Normally, local variables die after functions are through running:


function someFunction() : void
{
    var myFriend : String = "Fred";
}

someFunction();
trace( myFriend ); //1120: Access of undefined property myFriend.

But things get wacky when functions return other functions:


function functionMaker() : Function
{
    return function() : void { trace ( "I am a new function!" ) }
}

In the above example, I haven't used any variables. I'll add one shortly. For now, just note that functionMaker's return type is Function and that it, in fact, does return a function. The function it returns in anonymous. That is, it doesn't have a name. We can access it this way:


var aNewFunction : Function = functionMaker();
aNewFunction(); //I am a new function!

functionMaker returns a new (anonymous) function, which we stored in a variable called aNewFunction. We then called the function stored in aNewFunction by following the variable's name with the call operator: ().

You can shorten the above to...

functionMaker()();

That looks odd, but it works. The first call operator calls functionMaker; the second class the function that functionMaker returns.

Let's take another look at the guts of functionMaker:


function functionMaker() : Function
{
    return function() : void { trace ( "I am a new function!" ) }
}

From now on, in the case of functions that return other functions, I'm going to call the main function the outer function and the returned function the inner function:


//outer function
function functionMaker() : Function
{
            //inner function
    return function() : void { trace ( "I am a new function!" ) }
}

What happens if we create a local variable in the outer function and try to reference it from the main body of our code?


function functionMaker() : Function
{
    var food : String = "cheese"?
   
    return function() : void { trace ( "I am a new function!" ) }
}

functionMaker();
trace( food ); //1120: Access of undefined property food.

No surprise. food is a local variable to functionMaker. We can't access it from outside the function. However, what if we try to access it from within the inner function?


function functionMaker() : Function
{
    var food : String = "cheese"?
   
    return function() : void { trace ( "I am a new function, and I love " + food + "!" ) }
}

var aNewFunction : Function = functionMaker();
aNewFunction(); //I am a new function, and I love cheese!

Take a moment to think about what just happened. When we ran the inner function, it spit out the word "cheese" as part of its output, even though that word wasn't stored inside it. It got that word by referencing the outer function's variable. So inner functions have references to the variables in their parent functions.

Now take a closer look at these lines:

1. var aNewFunction : Function = functionMaker();
2. aNewFunction(); //I am a new function, and I love cheese!

functionMaker, the function that contains the value "cheese" finishes running on line one, so under normal circumstances, cheese should be dead by line two. But it's not. And that, kids, is a closure: inner functions have access to the variables in their parent, outer functions even after those outer functions have stopped running!

Not only can they access those variables, they can alter them!


function functionMaker() : Function
{
    var food : String = "cheese"?
   
    return function() : void { food += " crackers"; trace( "I am a new function, and I love " + food + "!" ) }
}

var aNewFunction : Function = functionMaker();
aNewFunction(); //I am a new function, and I love cheese crackers!

There's one last key aspect of closers I haven't explained: From the inner-function's point-of-view, the variable is static. That is, it keeps its value even after the inner function is done running! That means that each time you call the inner function, it can access the last value stores in the variable.


function counterMaker() : Function
{
    var count : int = 0;
   
    return function() : void { trace( count ++ ) }
}

var aNewCounter = counterMaker();
aNewCounter(); //0
aNewCounter(); //1
aNewCounter(); //2
aNewCounter(); //3

Compare this with a stand-alone version of the inner function:


function counter() : void
{
    var count : int = 0;
    trace( count++ );
}

counter(); //0
counter(); //0
counter(); //0
counter(); //0

In the stand-alone version, the variable counter gets reset to zero each time the function is called. It gets incremented in the trace, but by then it's too late. The function is over and its local variable dies. We can use closures to add static variables to functions!

As I said at the top of this article, I had read about closers for years, but I didn't see how they were useful in Actionsctipt, which is an object-oriented language. As such, if I wanted a counter with a static variable, I would make and use one like this:


public class Counter
{
    private var _count : int = 0;
   
    public function next() : { trace( _count++ ) }
}

var counter : Counter = new Counter();
counter.next(); //0
counter.next(); //1
counter.next(); //2
counter.next(); //3

So what made me suddenly want to use a closure? Well, I was trying to do something very specific involving regular expressions. I started with this text:

Photo is of a sunset.
Photo is of my sister.
Photo is of a horse.
Photo is of a birthday party.
... [many other similar lines]
Photo is of a calm lake near the city.

From that, I wanted to output...

Photo1 is of a sunset.
Photo2 is of my sister.
Photo3 is of a horse.
Photo4 is of a birthday party.
... [many other similar lines]
Photo[n] is of a calm lake near the city.

...with each new "Photo" getting an incremented number appended to it.

To start out with a simpler example, let's say that I didn't care about the numbers incrementing. I just want a random number appended to the end of each "Photo" (Photo2, Photo9, Photo3, etc.).


var text : String = "";
text += "Photo is of a sunset.";
text += "Photo is of my sister.";
text += "Photo is of a horse.";
text += "Photo is of a birthday party.";
text += "Photo is of a calm lake near the city.";

var regExp : RegExp = new RegExp( "Photo", "g" );

text = text.replace( regExp, String( Math.round( Math.random() * 10 ) );
trace( text );

That doesn't get me exactly what I want. It doesn't append a random number onto the end of each "Photo". Instead, it replaces each "Photo" with a random number:

6 is of a sunset.
0 is of my sister.
10 is of a horse.
6 is of a birthday party.
3 is of a calm lake near the city.

I could prepend the original string "Photo" onto the random number ...

text = text.replace( regExp, "Photo" + Math.round( Math.random() * 10 );

... but that second parameter is starting to get long, ugly and unreadable. Luckily, the String.replace() method accepts a function as its second parameter:


function appendRandomNumber() : String
{
    return arguments[ 0 ] + Math.round( Math.random() * 10 );
}

var regExp : RegExp = new RegExp( "Photo", "g" );

text = text.replace( regExp, appendRandomNumber );
trace( text );

What happens here is that replace calls the appendRandomNumber method, handing it an array, which the function receives in a variable called arguments. If you want to know everything that's stored in the array, look up String.replace() in help. All we care about here is arguments[0], which contains whatever the regular expression matched: in this case, the word "Photo." The function returns that plus a random number:

Photo4 is of a sunset.
Photo7 is of my sister.
Photo0 is of a horse.
Photo10 is of a birthday party.
Photo6 is of a calm lake near the city.

Putting that idea together with closures, we can hand String.replace() an inner function that uses its parent's static variable to keep count:


function counterAppenderMaker() : Function
{
    var counter : int = 1;
   
    return function() : String { return arguments[0] + counter++ }
}

var regExp : RegExp = new RegExp( "Photo", "g" );

text = text.replace( regExp, counterAppenderMaker() );
trace( text );

Which yields this output:

Photo1 is of a sunset.
Photo2 is of my sister.
Photo3 is of a horse.
Photo4 is of a birthday party.
Photo5 is of a calm lake near the city.

I think this is an elegant solution. To be fair to OOP, there is another way of doing this:


public class AppendCounter
{
    private var _counter : int = 1;
   
     public function doIt() : String
    {
        return return arguments[0] + _counter++;
    }
}

var regExp : RegExp = new RegExp( "Photo", "g" );
var appendCounter : AppendCounter = new AppendCounter();

text = text.replace( regExp, appendCounter.doIt );
trace( text );

I am not advocating closures over objects (or vice versa), but it's nice to know the closure method. Depending on what I'm trying to achieve, it may be clearer to have all the logic in one class rather than referencing a second class (or a global variable) just to increment a counter.

subtleties

2010-01-21T08:26:00.000-08:00

Whew! I just finished a hell of a debugging session. My goal was to make Flash submit a url to tinyurl.com for minification.

My code worked locally (when I ran the swf on my desktop), but it didn't work in the browser. So I was pretty sure it was a security issue. But I couldn't understand why I wasn't getting a response from http://tinyurl.com, because they DO have a crossdomain.xml file. See: http://www.tinyurl.com/crossdomain.xml

hint: if you're smarter than I am, you may be able to guess the problem just via the previous paragraph.

Here's the code that didn't work:


send();

function send() : void
{
   var url : String = "http://www.google.com/search?q=cows";
   var urlLoader : URLLoader = new URLLoader();
   urlLoader.addEventListener( Event.COMPLETE, receive );
   urlLoader.load( new URLRequest( "http://www.tinyurl.com/api-create.php?url=" + url ) );
}

//this callback function never gets called!
function receive( event : Event ) : void
{
   var urlLoader : URLLoader = event.target as URLLoader;
   //output is a text field on the stage
   output.text = urlLoader.data;
}

Here's the working version. Can you spot the difference?


send();

function send() : void
{
   var url : String = "http://www.google.com/search?q=cows";
   var urlLoader : URLLoader = new URLLoader();
   urlLoader.addEventListener( Event.COMPLETE, receive );
   urlLoader.load( new URLRequest( "http://tinyurl.com/api-create.php?url=" + url ) );
}

function receive( event : Event ) : void
{
   var urlLoader : URLLoader = event.target as URLLoader;
   //output is a text field on the stage
   output.text = urlLoader.data;
}

Give up? The difference is in this statement:

BUGGY: urlLoader.load( new URLRequest( "http://www.tinyurl.com/api-create.php?url=" + url ) );

WORKING: urlLoader.load( new URLRequest( "http://tinyurl.com/api-create.php?url=" + url ) );

In case you still don't see it, the buggy version has a www in-front-of the url and the working version doesn't.

tinyurl's crossdomain.xml file is located at http://tinyurl.com/crossdomain.xml NOT http://www.tinyurl.com/crossdomain.xml.

But you'll get to it if you type it the "wrong" way into the browser, because most browser normalize urls. Flash doesn't. To Flash, there is no crossdomain.xml file, because it was specifically looking for one at the www address, and there isn't one there.

The scary thing is that my FIRST assumption was that it was a crossdomain.xml issue, so I watched the Activity Window in Safari as I ran my app (the bad version) in the browser. The Activity window showed that the crossdomain file was being accessed correctly. But apparently that was just the BROWSER accessing it correctly. Flash still thought of it as a bogus file, since it came from a www site.

how long is an mp3?

2010-01-14T08:32:00.000-08:00

I need to know the length (in seconds) of a progressive mp3 before it starts playing. As-far-as I can tell, there are only three ways of getting this information:

1) if it's explicitly stated in some sort of data feed (e.g. an XML playlist), you can, of course, grab that info and hope it's accurate.

2) you can read it from the id3 tags -- the metadata embedded in the mp3 file itself -- and hope THAT'S accurate.

3) you can guestimate length using some simple math.

Option one won't work for me, because my clients are generally not going to enter durations into a data feed.

I spent hours trying to get option two to work, emailing other developers and asking them for advice. I wasn't receiving the id3 data. Someone mentioned to me that I was likely hitting a security wall. It turns out that though a SWF can play mp3s from another domain, it can't access embedded id3 data without permission. See: http://kb2.adobe.com/cps/963/50c96388.html

I figured this was the problem, so I added a crossdomain file and a SoundLoaderContext object to Sound.load(), but I still didn't receive any id3 data. Why? Because there wasn't id3 data in the mp3s I was using -- even though the client assured me that there was.

I realized that I can't count on there being id3 data. Even if there is, there may not be length data, as it's optional which id3 tags are included in an mp3 file (or if any are included at all).

Which lead me to try option three. I patched it together based on various similar solutions I found online:

This code runs in a loop:


if( _duration == 0 && ( bytesLoaded / bytesTotal ) > 0.1) 
{
    _duration =  _sound.length / 1000 / bytesLoaded * bytesTotal;
}

It waits until ten percent (0.1) of the mp3 is cashed and then calculates duration. It's an estimate, because it's based on Sound.length, which is NOT necessarily the length of the whole mp3. It's the length of what's loaded so far.

And you can't simply guess the length from bytesTotal, because depending on the compression/bitrate of the mp3, the same number of bytes could mean different lengths. So the calculation takes into account the known length, the number of bytes loaded so far and the total number of bytes. (Divided by 1000 to convert from milliseconds to seconds.)

How much should I cache before I let Flash do the calculation? Is ten percent enough? (The JW Player uses ten percent.) I tried it with an mp3 which I knew to be 1 minute and 2 seconds. The guestimation was close but not perfect: 00:59 and 1:00 on subsequent runs.

I upped the cached-percent to 0.2, which produced perfect guesses. Also, on my high-bandwidth (but not exceptionally high-bandwidth) connection, it took about a second for 0.2 percent to cache, which is acceptable for my purposes.

But then I tried a one-hour-long mp3. As you might expect, it took quite some time for 20 percent to cache. Totally unacceptable. I changed the percent back to 0.1 and the hour-long mp3 produced a guess in a reasonable amount of time (it took about fifteen seconds to guess). And the guess was only off by one second.

In the end, I am probably going to use a three-pronged approach: first, I will check for duration data in the XML feed, using that if it's there (doubtful). Next, I will try to use id3 data. Failing both those approaches, I will guestimate with a ten-percent cache.

If anyone reading this has a better idea, please let me know!

I am also trying to figure out how to adjust the UI if Flash has to guestimate. When the hour-long mp3 finished playing, the time-duration display said 00:59:00/1:00:00, which doesn't thrill me. Should I fudge the time up to the duration? (if end_time != duratation; then end_time = duration.)

Someone suggested that I keep checking for duration and adjust it as it the guess gets more accurate (which it will as more data gets cached.) I don't know. I think it would be pretty distracting seeing the the duration-readout change. Also, my played-progress bar would jump around, popping to a longer or shorter width.

What do you think?

rethinking constructors -- or what I learned from objective-c

2009-11-13T13:27:00.000-08:00

Like many Flash developers, I've been studying Objective-C in a desperate attempt to ride the iPhone app train. (Though I think it left the station while I was still putting a token in the turnstile.)

One thing I like about Objective-C is its version of constructors, which usually start with the word "init." For instance, a method might be called just init(), or, if it takes arguments, it might be called initWithColor( 0xFF000 ) or initWithColorAndType( 0xFF0000, "large" );

Note: objective-C's syntax is different from Actionscript's, so in reality, the last method call above would look like this: [myObject initWithColor: 0xFF0000 andType: @"large"]; Since this post is about Actionscript, I'll keep everything in AS syntax.

You can, in a sense, overload Objective-C constructors. A class can't have two init() methods. But it can have init(), initWithColor() and initWithColorAndType(). You call the appropriate one, depending on how you want to initialize the object.

I also like the fact that every Objective-C class has a formal interface (defined in its header file). I do that for my Actionscript classes, too.

All of my classes (except DTOs and utilities with static members) implement at least one interface. Often, several classes will share the same interface. But even if a class is a loner, I make an interface file for it. I like this this clean separation between interface and implementation. When you browse my code, you can learn how everything fits together just by reading the interface files.

But you can't define constructors in an interface! That bothers me, because a constructor is -- or can be -- a way of communicating with a class. And if something is part of the way one communicates with a class, it is, by definition, part of that class's interface.

(I can't use my TV until I first turn it on. So the power button is kind of like a constructor. But it would be insane to say that the power button is not part of the TV's interface.)

Traditionally, interface files are only used when they are meant to be shared by multiple classes. In that sense, I get why they can't include constructors. Class A and Class B can't share a constructor, because Class A's constructor must be named A() and Class B's must be named B().

But since I make separate interface files for each class, I'd like to list ALL class inputs and outputs in those interface files.

Here's my solution: I never pass ANYTHING into a constructor. In other words, I would never write a constructor like this:

public function Person( name : String ) { ... }

Instead, person's constructor will look like this:

public function Person() { ... }

I don't care that the Person() method can't be listed in an interface file. It's not used as an interface element. It doesn't suck anything in from the outside world.

That's not to say I won't write a constructor function. I will if the class has any internal housekeeping it needs to do at start-up:

public function Person()
{
_kids = new Array();
}

So how do I specify that this a Person is named "George"?

var dad : Person = new Person();
dad.initWithName( "George" );

If it's also legal to have a nameless person, I would write this:

var dad : Person = new Person();
person.init();

All my classes have at least an init() method, even if it is just a placeholder husk. Want to know if my classes can be initialized any other way? Just check their interfaces:

public class Person implements ILifeform...

public interface ILifeform
{
function init() : void;
function initWithName( name : String ) : void;
function initWithNameAndGender( name : String, isMale : Boolean );
function eat() : void;
function die() : void;
function die() : void;
function addKid( name : String ) : void;
}

One objection to my system might be that initializer-method names could get absurdly long:

initWithWarpDriveShieldsPhotonTorpedosHoloDecksAndTransporters( ... );

To me, that's not an objection -- it's a warning! Even without my system, I would never write code like this:

var myShip : SpaceShip = new SpaceShip( true, false, true, true, false );

The more arguments a method takes in, the harder the code is for me to read, and the more apt I am to make a mistake. I have a loose rule of thumb that methods should take in no more than three arguments (and three is really pushing it).

So I'd change the above long init method to this:

initWithSpecs( specs : SpaceShipSpecs );

And I'd back this up with DTO class called ShipSpecs that had properties like warpDrive, sheilds, etc.

three little tricks

2009-11-13T12:58:00.000-08:00

Here are a couple of tricks I learned form this article:

I try never to access an array's length in a for loop:

for ( var i : int = 0; i < people.length; i++ ) ...

That's bad, because each time the loop iterates, it has to dig into people and access its length property. I get a boost in optimization (without losing clarity) by doing this:

var numPeople : int = people.length;
for ( var i : int = 0; i < numPeople; i++ ) ...

But I'm bothered by the fact that both i and numPeople are throw-away variables (just needed for loop mechanics), yet only one is declared outside the for statement. So here's the trick:

for ( var i : int = 0, numPeople = people.length; i < numPeople; i++ ) ...

I advocate either that or this:

var i : int = 0;
var numPeople : int = people.length;
for ( i; i < numPeople; i++ ) ...

Note: you could also write the for loop this way:

for ( ; i < numPeople ; i++ )...

Trick two:

Let's say you need to loop backwards through an array by index. You could do this:

var arr : Array = [ 10, 20, 30, 40, 50 ];
for ( var i : int = arr.length - 1; i <= 0; i-- )
{
trace( arr[ i ] );
}

//output: 50, 40, 30, 20, 10

or (here's the trick) you could just do this:

var arr : Array = [ 10, 20, 30, 40, 50 ];
var i : int = arr.length - 1;
while( i-- )
{
trace( arr[ i ] );
}

//output: 50, 40, 30, 20, 10

Why does that work? Won't i keep decrementing past zero (-1, -2, -3...)? No, because in the Boolean sense, zero reads as false (all other numbers read as true). So while( 0 ) will stop the loop.

One final trick:

I didn't learn this one from the article I liked to above. I've seen it in various places.

Let's say you want to either set a variable equal to a value read in from an xml file OR, if there is no value in the xml file, you want to set the variable to some default value. (Hint: note the word "or" in the previous sentence.)

Here's what I used to do:

if ( valueFromFile == null ) speed = valueFromFile;
else speed = 10;

or I might have done this:

speed = ( valueFromFile == null ) ? valueFromFile : 10;

or even this:

speed = ( valueFromFile ) ? valueFromFile : 10;

What I hate about all those versions is the stuttering of "valueFromFile." Via the trick, I can eliminate it like so:

speed = valueFromFile || 10;

I love how clean this looks, especially when you're using it with multiple values:

var speed : int = speedFromFile || 10;
var color : uint = colorFromFike || 0xFF00FF;
var name : String = nameFromFile || "George";

getters and setters: no more faux properties

2009-11-13T12:32:00.000-08:00

I am obsessed with making my code as easy to use as possible. One way I do that is to stay consistent whenever I can. If class A's kill() method does the same thing as class B's destroy() method, they shouldn't have two different names. They should both be kill() or destroy().

Adobe is terribly inconsistent (probably due to too many developers working without tight supervision) when deciding if properties should be accessed via methods or faux properties (getters/setters). Is it length or length(). Depends: arrays have length; XMLLists have length(). That always trips me up.

Accessors can present themselves as either properties or methods. For consistency, I've decided to use only one of these. It doesn't make sense to forgo methods, since I have to use methods for other purposes. So I'm forgoing properties.

No more "public function get length()" for me. From now on, I'll use getLength() and setLength(). For Booleans, I'll use isCold() and hasChildren(). Anyone using my classes -- including me -- will no longer have to look up a member to see if it's accessed as a property or method. It will always be a method.

Of course, another clean way of working is to be very rigid about whether a member is something a class has or something a class can do. A class might HAVE length but it can't DO length. I like this distinction in theory, but I'd rather not have to think about it in practice -- especially since some cases are ambiguous: does a book flipTo() page 18 or is its currentPage page 18?

Why You Should Override Clone In Event Subclasses

2009-11-06T10:51:00.001-08:00

When I first learned how to code custom events in Actionscript 3.0, a friend told to override clone() when I subclassed flash.events.Event, but I didn't really understand why. So I ignored his advice.

It didn't seem to matter. I never wrote my own version of clone() and yet I never ran into any problems. But my friend's advice nagged at me. So I asked him why I should override clone(). He explained that if I didn't, clone() would return the standard Event type rather than my custom event type.

Let's say I create an Event subclass called KissEvent:


public calls KissEvent extends Event
{
    public var withTongue : Boolean = true;

 public static const BIG_SMOOCH : String = "bigSmooch";   
 
 ...
}

As usual with events, I can set up a listener for KissEvent:

this.addEventListener( KissEvent.BIG_SMOOCH, onKiss );


function onKiss( kissEvent : KissEvent ) : void
{
 ...
}

The clone() problem occurs if I try to copy the Event via the clone() method it inherited from flash.events.Event:


function onKiss( kissEvent : KissEvent ) : void
{
 var kissEventClone = kissEvent.clone();
 
 trace( kissEvent.withTongue );
 trace( kissEventClone.widthTongue );
}

The first trace, above, will output true. The second will cause an error. Flash will tell me that Event has no such property as withTongue, and in fact it doesn't. Sure, KissEvent has such a property, but clone() doesn't spit out KissEvents; it spits out Events.

public function clone() : Event

And you can't fool it this way:

trace( ( kissEventClone as KissEvent ).widthTongue );

Flash won't allow you to cast the clone as a KissEvent, because KissEvents MUST have withTongue properties. clone() spits out Events, which don't have withTongue properties, so there's no way Flash can convert an Event to a KissEvent. My variable name, kissEventClone, is misleading, because it really just holds an Event, not a kissEvent.

Once my friend explained this to me, I understood the problem, but I had a hard time caring about it. How often do I need to clone an event object? So far in my AS-coding experience, the answer is "never." The problem seems more theoretical than nuts-and-bolts actual.

But a year later, I encountered the REAL problem: double dispatches.

Let me explain: sometimes I create systems in which a listener forwards an event object to another listener. The first listener is a sort of middle-man between the dispatcher and the second listener. The middle man is both a listened and a dispatcher. It listens to the event, and, when it receives it, it dispatches the event to a second listener.

For example, say a game character has to listen for bullets coming at him. If a bullet hits him, he stops the bullet from flying any further and dies. That's the case UNLESS the character is a ghost. If a ghost gets hit by a bullet, it passes right trough him, so he just passes the event on to anything else that might be hit by it. Ghosts, like all characters, listen to Guns. Walls listen to Ghosts, because a Ghost might dispatch a bullet that passed through it, and that bullet might lodge in a wall.


                     event                            event
gun (dispatcher) --------------> ghost (dispatcher) ------------> back wall

Trouble is, a listener can't simply pass on an event. It can only pass on a cloned copy of the event. (That's a built-in "feature" of Flash's event system).


                     event                           event-clone
gun (dispatcher) --------------> ghost (dispatcher) -------------> back wall

Let's say that BulletEvents have a custom property called speed. Since clone() outputs Events (not BulletEvents), speed will be passed from gun to ghost but not from ghost to back wall.


                 event (speed=3)                        clone
gun (dispatcher) ---------------> ghost (dispatcher) -----------> back wall

So if the back wall tries to access speed, it's not going to find anything. Finally understanding the REAL problem, I made sure to override clone() in all my custom events. Here's a toy version of the solution:


public class MyEvent extends Event
{
 public var myName : String;
 
 public static const SOMETHING_HAPPENED : String = "somethingHappened";
 
 public function MyEvent( type : String, myName : String,
        bubbles : Boolean = true,
        cancelable : Boolean = false )
 {
  this.myName = myName;
  super( type, bubbles, cancelable );
 }
 
 override public function clone() : Event
 {
  return new MyEvent( super.type, myName, super.bubbles, super.cancelable );
 }       
}

Notice the overridden clone method. It returns a new MyEvent instance containing all the properties of the current instance. It truly IS a clone!

The one unfortunate thing is that clone() can't return a MyEvent. It must return an Event. That's because the clone() method in the superclass returns Event, and when you override a superclass's method, your new version must return the same type of object. But the returned Event is created by this statement: new MyEvent( super.type, myName, super.bubbles, super.cancelable ), so it DOES contain the myName property. This means we'll be able to use casting to get at myName, as I'll show below.

Now that we have our event, I'll show you the dispatcher/listen chain I have in mind:


                  event( w/myName )                            clone( w/myname)
MyEventDispatcher ---------------> MyEventGrabbler (dispatcher) ------------> Main

Here's the code for MyEventDispatcher:


public class MyEventDispatcher extends EventDispatcher
{
 public function dispatch() : void
 {
  var myEvent : MyEvent = new MyEvent( MyEvent.SOMETHING_HAPPENED, "Fred" );
  dispatchEvent( myEvent );
 }
}

Here's the middle-man code for MyEventGrabber:


public class MyEventGrabber extends EventDispatcher
{
 private var _myEventDispatcher : MyEventDispatcher;
 
 public function MyEventGrabber()
 {
  _myEventDispatcher = new MyEventDispatcher();
  _myEventDispatcher.addEventListener( MyEvent.SOMETHING_HAPPENED, myHandler );
 }
 
 public function startTheEventBallRolling() : void
 {
  _myEventDispatcher.dispatch();
 }
 
 public function myHandler( myEvent : MyEvent ) : void
 {
  dispatchEvent( myEvent );
 }
}

You might have expected the myHandler method to look like this:


public function myHandler( myEvent : MyEvent ) : void
{
 dispatchEvent( myEvent.clone() );
}

While that's perfectly legal, it's not necessary. (Though maybe it's a good idea, as it makes what's happening explicit). When you re-dispatch an event, Flash uses clone() automatically.

Finally, here's the section of the Main class that catches the clone and accesses the myName property:


var myEventGrabber : MyEventGrabber = new MyEventGrabber();
myEventGrabber.addEventListener( MyEvent.SOMETHING_HAPPENED, myHandler );
myEventGrabber.startTheEventBallRolling();

function myHandler( event : Event ) : void
{
 trace( (event as MyEvent).myName ); //Fred
}

Note that I use casting here to make Flash understand that the Event is actually a MyEvent. This casting only works because I overrode the clone() method in MyEvent.

There's one more potential problem that, admittedly, is less serious than the clone() problem. If I replace the above trace with this one...

trace( event );

... I won't see the myName property listed. Instead, I'll see this:

[Event type="somethingHappened" bubbles=true cancelable=false eventPhase=2]

The simple fix is to also override the toString() property in MyEvent, since when you hand trace() an object, it uses that object's toString() method. The simplest override is this:


override public function toString() : String
{
 return "myName=" + myName;
}

But that will just trace out "myName=Fred", whereas what I want is...

[Event type="somethingHappened" bubbles=true cancelable=false eventPhase=2 myName="Fred"]

So I need to append the extra info to the end of the superclass's version of to string:


override public function toString() : String
{
 return super.toString + " myName=" + myName;
}

Which gives me this:

[Event type="somethingHappened" bubbles=true cancelable=false eventPhase=2] myName=Fred

Because I'm anal, I need to get the myName=Fred inside the brackets. I also need to put quotation marks around "Fred," because it's a String. That's all easy to accomplish with a tiny bit of String manipulation. Here's my final version of MyEvent, with a robust toString() method. Note that I have also made a getter for myName, which stops random processes from being able to set myName to values that didn't come from MyEventDispatcher:


public class MyEvent extends Event
{
 private var _myName : String;
 
 public static const SOMETHING_HAPPENED : String = "somethingHappened";
 
 public function MyEvent( type : String, myName : String,
        bubbles : Boolean = true,
        cancelable : Boolean = false )
 {
  _myName = myName;
  super( type, bubbles, cancelable );
 }
 
 public function get myName() : String
 {
  return _myName;
 }
 
 override public function clone() : Event
 {
  return new MyEvent( super.type, _myName, super.bubbles, super.cancelable );
 }
 
 override public function toString() : String
 {
  var superString = super.toString();
  var newProperties : String = ' myName="' + _myName + '"]';
  
  //removes the closing bracket symbol from the end
  //of the event-property list;
  superString = superString.toString().substr( 0, superString.length - 1 );
  
  return superString + newProperties;
 }
        
}

The extra two methods, clone() and toString() add a lot of typing to the previously quick job of creating custom events. So I recommend that you use whatever templating system your IDE supports. If you're able to paste in generalized version of those method, it only takes a few seconds to make the necessary changes to support your particular event.

SWFS on CDNs

2009-10-02T14:54:00.001-07:00

The companies that I work for tend to store swf files on CDNs (Content Delivery Networks) which distributes the file over multiple servers. Each server has a copy of the swf, and the one you get, when you visit the company site, might come from any of them.

This works well except for when I'm making rapid changes to the swf. Each time I make a change, the swf needs to get copied to all of the servers in the network. Until that happens, I can't be sure that everyone is seeing the must current version. Worse, I can't be sure that I'm seeing the most current version. Is my bug fix not working because there's something wrong with it? Or am I seeing the version before the fix.

The best way to deal with this is not to post constant fixes to the CDN. Test on a single-server site and then upload to the CDN when the app is ready to go live. In theory that works -- and in reality it works for most of the dev cycle -- but in this world of "always in beta," there's now less of distinction between the testing phase and the live phase. (Which sucks and is wrong, wrong, wrong, but I don't run the world.)

So inevitably I wind up tweaking the swf after it's gone live and is hosted on the CDN. If I find that a change has not propagated to all of the machines on the network, I have to run through a somewhat lengthy set of steps in a web control panel, to make sure that everyone is getting the latest copy. I only want to do this if necessary. Sometimes all the machines get updated as soon as I upload my changes. How can I tell?

Here's my simple solution:


import flash.ui.ContextMenu;
import flash.ui.ContextMenuItem;

const APP_VERSION : String = "1.0";

var menu: ContextMenu = new ContextMenu();
var contextMenuItem : ContextMenuItem = new ContextMenuItem( "app version: " + APP_VERSION );
menu.customItems.push( contextMenuItem );
this.contextMenu = menu;

I put this in my Document class and change the APP_VERSION every time I upload. Then, when I'm looking at it in the browser, I just need to right click on it to see if I'm looking at the most current version.

procedural programming in an OOP world

2009-09-25T09:22:00.001-07:00

Procedural programming is one damn thing after another. The one place I tend to write procedural code is in initialization modules. For instance, say I'm making a video player. The player needs to first load in an xml file that contains configuration info (width, height, background color, etc); then it needs to load in another xml file, containing a playlist; next it needs to load in external graphics; then it needs to render everything to the stage; finally, it needs to play the first video in the playlist.

What I want to write is something like this:


function init() : void
{
 loadConfigData();
 parseConfigData();
 loadPlaylistData();
 parsePlaylistData();
 loadGraphics();
 renderToStage();
 playVideo( 0 );
}

Alas, asynchronous-loading makes this impossible. My code can't proceed directly from the first step, loadConfigData(), to the second step, parseConfigData(), because it needs to pause and wait for the data to load before it can begin parsing. So I'm forced to use listeners and callback methods.


function loadConfigData() : void
{
 var urlLoader : URLLoader = new URLLoader();
 urlLoader.addEventListener( Event.COMPLETE, parseConfigData );
 urlLoader.load( "config.xml" );
}

function parseConfigData( event : Event ) : void
{
 var urlLoader : URLLoader = event.currentTarget as URLLoader;
 var loadedData : String = urlLoader.data;
 var xml : XML = XML( loadedData );
 
 ...
 
 loadPlaylistData();
}

My nice, neat, compact procedural list becomes an ugly chain of functions that call other functions:


function stepA() : void
{
 //do stuff
 stepB();
}

function stepB() : void
{
 //do stuff
 stepC();
}

function stepC() : void
{
 //do stuff
 stepD();
}

...

This sucks, because in order to get a bird's-eye-view of the initialization procedure, I have to scroll through all the code. If I want to stop a function from running -- say during debugging -- I need to search to find where that function is being called. It would be so much easier if I could just do this:


function init() : void
{
 loadConfigData();
 parseConfigData();
 loadPlaylistData();
 parsePlaylistData();
 //loadGraphics();
 //renderToStage();
 //playVideo( 0 );
}

I decided to solve this problem by creating a class called StepManager, which allows you to run asynchronous code as if it's synchronous. StepManager takes care of the pause between each step. It knows to run step B only after step A has completed.

It's very easy to use. You create a (usually) small class for each step. Then you feed the steps to StepManager like this:


var stepManager : StepManager = new StepManager();
stepManager.addNextStep( StepA );
stepManager.addNextStep( StepB );
stepManager.addNextStep( StepC );

When you're done adding steps, you start them running like this:


stepManager.exectute();

If you want to be informed of when all the steps are complete, you can add an event listener to stepManager:


var stepManager : StepManager = new StepManager();
stepManager.addEventListener( StepEvent.COMPLETE, stepsCompleteHandler );
stepManager.addNextStep( StepA );
stepManager.addNextStep( StepB );
stepManager.addNextStep( StepC );

function stepsCompleteHandler( event : StepEvent ) : void
{
 trace( "All steps complete." );
}

To disable a step, you simply comment out the line of code where you added it to the StepManager:


var stepManager : StepManager = new StepManager();
stepManager.addNextStep( StepA );
stepManager.addNextStep( StepB );
//stepManager.addNextStep( StepC );

Note that StepA, StepB and StepC are classes NOT instances. The StepManager creates instances from the classes you hand it. You just create the classes. Here's the bare bones of what a step class looks like:


import com.grumblebee.utilties.stepmanager.AbstractStep;

    public class StepA extends AbstractStep 
    {
        public function StepA( previousStep : AbstractStep = null )
        {
            super( previousStep );
        }
        
        override public function execute() : void
        {
   //do stuff
         super.stepComplete();
        }
    }

So to make a step, you just extend AbstractStep, write a simple constructor that takes in one argument (previousStep), and override a function called execute. The guts of your step -- whatever you want the step to do -- go in execute().

Each step MUST announce when it's done. It does so by calling super.stepComplete(); (Behind the scenes, stepComplete dispatches an event that's received by the StepManager. When it gets that event, StepManager knows it's okay to move onto the next step.)

Note the previousStep parameter in the constructor. By default, it's set to null. This handles the case of the first step (StepA). There's no step before it, so there can't be a previousStep. But StepManager sends each subsequent step the step that came before it. That way step B can extract any information it needs from step A; Step C can extract information from step B and so on.

Here's a more complete example:

Step A holds url of a text file, which it hands to step B. Step B loads in the contents of the text file, which it hands to step C. Step A looks like this:


public class StepA extends AbstractStep 
{
    public function StepA( previousStep : AbstractStep = null )
    {
        super( previousStep );
    }
    
    public function get urlToLoad() : String
    {
     return "external.txt";
    }
    
    override public function execute() : void
    {
     trace( "Step A: It knows the URL of the text file: " + urlToLoad );
     super.stepComplete();
    }
}

Note that the new method, urlToLoad(). It's public, so that step B can access it. Step B is a little more complicated. It looks like this:


public class StepB extends AbstractStep 
{
  private var _loadedData : String;
  
     public function StepB( previousStep : AbstractStep = null )
     {
         super( previousStep );
     }
     
     public function get loadedData () : String
     {
      return _loadedData;
     }
     
     public function set loadedData( value : String ) : void
     {
      _loadedData = value;
      trace( "Step B: storing this loaded data: " + _loadedData );
     }
     
     override public function execute() : void
     {
      var stepA : StepA = ( previousStep ) as StepA;
      var url : String = stepA.urlToLoad;
      
      trace( "Step B. received this URL from Step A: " + url );
      
      var urlLoader : URLLoader = new URLLoader();
      urlLoader.addEventListener( Event.COMPLETE, loadCompleteHandler );
      urlLoader.load( new URLRequest( url ) );
     }
     
     function loadCompleteHandler( event : Event ) : void
     {
      var urlLoader : URLLoader = event.currentTarget as URLLoader;
      urlLoader.removeEventListener( Event.COMPLETE, loadCompleteHandler );
                 
      loadedData = urlLoader.data;
      
      super.stepComplete();
     }
}

Most of the extra stuff here is just the code to load data from an external text file. One detail worth noting how step B gets the url from step A:


 var stepA : StepA = ( previousStep ) as StepA;
  var url : String = stepA.urlToLoad;

Another detail you should note is that step B stores the data from the external file in a variable called _loadedData. It allows the next step to access that data via a getter method:


public function get loadedData () : String
{
 return _loadedData;
}

Step C looks like this:


public class StepC extends AbstractStep 
{
    public function StepC( previousStep : AbstractStep = null )
    {
        super( previousStep );
    }
    
    override public function execute() : void
    {
     var stepB : StepB = previousStep as StepB;
     trace( "Step C: received text from step B: " + stepB.loadedData );
     super.stepComplete();
    }
}

Note in its execute() method how step C extracts data from step B.

As shown previously, we can now run all these steps like this:


var stepManager : StepManager = new StepManager();
           
stepManager.addNextStep( StepA );
stepManager.addNextStep( StepB );
stepManager.addNextStep( StepC );

stepManager.execute();

Here's the output:

Step A: It knows the URL of the text file: external.txt
Step B. received this URL from Step A: external.txt
Step B: storing this loaded data: Hi, mom!
Step C: received text from step B: Hi, mom!
All steps complete.

In the future, I plan to extend StepManager -- allowing branching as-well-as pause and resume functions. In the meantime, you can download the code (and examples) here:

http://www.grumblebee.com/grumblecode/StepManager.zip

Please let me know if you have any questions or suggestions.

the planning problem

2009-09-17T08:55:00.000-07:00

Tim Consolazio posted about the ass-backwards way managers and clients tend to plan user-interfaces.

a client has an idea for a project; they want this fantabulous application that does this, this and this. They qualify you, and hire you. There you are, ready to look over requirements and wireframes, iterate through them, allocate your resources, get some preliminary milestones approved, and create a draft project plan.

The client hands you a few comps; artist renderings of the end result. "That's what I want".

You're a contractor, so of course, you say "erm...have you considered...". Some internal employee that believes he/she has already foreseen the future is annoyed, but concedes, so they rework the comps. You look it over and say, "hmm...but how about errors and alerts...what about some form of tips or help...what will happen if the user does this..." The designer starts to whine, the client gets tired of hearing you say, "have you considered...", and assigns some internal employee to start pushing you to start dev immediately, believing they because they have shown you a snapshot of the end result, that the plan is ready to go.

I want to throw a chair across the room and shout, "EVEN IF YOU SUCCEED, YOU ARE GOING TO FAIL!".

As a developer, I have to deal with this same frustration. I don't have a solution, but as terrible as it is, I have some sympathy for the people who get exasperated when we say, "Okay, but what about...?" over and over. I'm not saying that they're right (they're not). I'm saying that I understand what motivates them. If there's a solution, it will have to somehow deal with these motivations -- either re-routing them or quashing them.

When you code, it's generally necessary to plan out a large percentage of what you're going to do before you start -- not the details of the algorithms but all major aspects of the functionality you're coding towards. It's far from trivial to change from one sort of UI to another, so the final UI should be pretty well set before coding begins.

Trouble is, I don't think this sort of thinking is natural to most people. (It is to some of us coders, but we are the freaks. I mean that in a good way. Our "freakiness" -- our anal-retentive nature -- is one of the things that makes us good at our jobs.)

Say you're a cave man and you're about to hunt. There are certain things than you definitely plan out beforehand: what weapons to bring, how much food to carry, etc. But you probably don't map out the majority of what you're going to do. You won't say, "first I'm going to look for a leopard; then, if I can't find one after two hours, I'm going to look for a boar..." You'll just go out and hunt, and you'll deal with new situations as they arise. That FEELS right. It's nice to not have to hold too much in your head at once.

I think that's the natural way (most) people think. They have a general end-goal (bring back food to the cave) and a couple of planned steps (leave cave with spear; walk towards woods), but everything else is improvised.

It's hard to work in a vacuum, by which I mean that most people need SOMETHING TO RESPOND TO in order to make decisions. And that something should be as physical as possible. A wireframe is pretty abstract. It's not something that you can interact with. The natural way to know if you need an error dialogue is to enter an incorrect value in an ACTUAL form and react the fact that the form doesn't respond. Most managers are probably able to work this way with all the members of their team except for the programmers. "Jennings, draft a memo about our first-quarter earnings ... Hm. Having read your draft, I now see that you need to add a paragraph about salary increases at the bottom of page five..."

Say I give you a cake recipe. You're reading it over, and I ask, "Do you think we should add more sugar or less?" You'll be tempted to ask, "Can I make the cake the way the recipe says, try it, and get back to you on that?"

(This is a very similar problem to coding, assuming there isn't time or budget to make second cake. Yes, it is MUCH easier to try a first draft and respond to it, but you don't have that luxury. Since you can only make one cake, and since you can't add or remove sugar from a finished cake, your only option is to plan how much sugar to add at the recipe stage. This is necessary but not ideal.)

I deal with pre-planning vs. trying-and-reacting when I direct plays, which is my main activity when I'm not programming. When I'm directing, I'm on the other side of the fence. I try to pre-plan as little as possible.

An actor will say to me, "My scene partner kisses me, and my character is sort of attracted to her but is also married and faithful to his wife. So when I say, 'We can't do this,' do I say it forcefully or sadly?"

I always respond by saying "Choose one option and lets try the scene." Then I react and we do the scene again, often trying the second alternative. This is a MUCH more natural way to work than to pre-plan many steps ahead.

I believe we would code this way if we could. If I could whip up a complex app in an hour, I wouldn't ask all the "but what about...?" questions. I would just code exactly what the wireframe suggested, run it up the flagpole and see what happens. Even if it turned out to be total crap, it wouldn't be a major hassle to start over from scratch and have a second draft done in another hour.

Alas, coding doesn't work like that, so we are forced to think in an un-natural way -- a way that is more about pre-planning than trying and reacting.

There are other human activities that demand this approach. Architecture is one. You can't just jump in and build a foundation without having first planned out the entire building. This is why architects are rare birds. Not everyone is cut out to be one, because not everyone thinks in this way.

I'm one of the rare birds who does, and I find that it affects even the way I converse with people.

Often, people will ask me to do something (not necessarily a programming task), and they'll ask in a vague way -- not fully explaining what they want. For instance, they'll say, "Marcus, would you go get that thing and put it in the closet?"

What's fascinating to me is to watch how other people tend to deal with requests like this. Over the years, I've noticed that they often don't ask "What thing?" and "Which closet do you mean? We have three."

They just form a hypothesis (maybe they do this unconsciously) about what the thing is go get it and they randomly put it in one of the three closets.

The person who make the request later finds the wrong thing in the wrong closet and says, "Sorry, I didn't mean 'put the suitcase in the hall closet', I meant 'put the shoe box in the bedroom closet.'"

What amazes me -- given my personality type -- is that neither party is upset. They both seem comfortable with a form of communication in which they grope forward from a vague concept to a specific one.

Whereas I'm much more comfortable with specifics up front. I don't want to waste my time trying to figure out what the thing is and what closet to put it in. So I say, "Sorry, can you tell me what thing you mean and which closet you want me to put it in?" I'm often surprised when my request for specificity is met with irritation.

But though I'm right to request specificity from the point of view of minimizing confusion and needless work, I'm wrong from the point of view of standard thinking and conversation. My eccentric way of thinking is one of the things that makes me a good coder.

Getting back to the problem, regardless of what's natural, we CAN'T improvise code. There isn't time. We MUST plan out most of the app before coding begins. That may be unnatural for many people, but it just is the way it is.

Like I said at the start, I don't have a solution. But I have found some approaches that minimize the problem.

People who don't think like me hate being boxed in. They hate feeling like they have to come up with a finished plan NOW and that they can't change anything later. I've found that this is generally more of a feeling than an actual business problem. Even if it's unlikely that anything WILL need to change, people still want to feel that they have the option of changing.

So I usually say this, "Once I'm done coding, there will be some things that will be really easy to change if you don't like them. It will take me five minutes to change the background color or the font or the blah blah blah ... but it will be very expensive to change the dropdown menu to a series of check boxes, so we kind of have to figure that out now..."

I get much better results if I dole out some flexibility at the same time as I demand specificity.

We coders also need to keep in mind that non-coders have no idea what's hard to change and what's easy. Why is changing a background trivial while changing a dropdown to a bunch of checkboxes complex? It SEEMS like it should be easy.

We can't make it easy, but we can warn the people we're working for about the fact that it's not easy. When I do this, I usually acknowledge the fact that this reality is less-than ideal: "UNFORTUNATELY, it's going to be really hard to change X later, so are we sure that's the way we want to go?"

For programmers and managers to work well together, managers need to understand that programming requires a unique mindset and some un-common planning requirements; meanwhile, programmers need to understand that they are being hired because they are specially gifted at thinking in a non-standard way. They need to learn how to help their co-workers see why things need to be done in a way that is unnatural to them.

jquery coding practices

2009-09-05T08:14:00.000-07:00

I've been the lynda.com series on jquery. I learned jquery a year ago, didn't use it, and promptly forgot its syntax. So I'm grateful for the refresher.

I am curious about what I see as a common practice amongst seasoned jquery-writers: constant use of chaining and function literals. To be blunt, this looks like bad coding style to me.

This sort of thing I mean:


var whichTag = "h3";
var count = 0;

$("div:not([id=header]) " + whichTag).each(function() { $(this).html("" + $(this).html() )});

I see this chaining/inline-function style everywhere throughout the jquery community. It's in all the books, tutorials, etc. So I am wondering if there's a good reason for it. I may be stuck in my own rigid paradigm and I'm willing to consider other approaches.

Here's how I would write that code:



var whichTag = "h3";
var count = 0;
var tagFilter = "div:not[id=header]" + whichTag;

$each( tagFilter).each( makeAnchor );

function makeAnchor() 
{
        var anchorTag = "";
        var oldTagContent = $html(this);
        $this(html) = anchorTag + oldTagContent;
}

I would love to hear your thoughts. Is there a profound reason for writing (to me) hard-to-read code when writing it in jquery? Or is it just a convention that has cropped up (why?) in the jquery community?

flash uses the brower's cache

2009-09-01T07:44:00.000-07:00

Try this code on the Timeline:




loadEm();

function loadEm() : void
{
 var loader : Loader;
 
 for ( var i : int = 0; i < 10; i++ )
 {
  loader = new Loader();
  loader.contentLoaderInfo.addEventListener( Event.COMPLETE,
                      completeHandler );
  loader.load( new URLRequest( "http://www.nasa.gov/images/content/382654main_s128e006565_full.jpg" ) );
  loader.x = Math.random() * stage.stageWidth;
  loader.y = Math.random() * stage.stageHeight;
  addChild( loader );
 }
}


function completeHandler( event : Event ) : void
{
 var loaderInfo : LoaderInfo =  event.currentTarget as LoaderInfo;
 loaderInfo.removeEventListener( Event.COMPLETE, completeHandler );
 loaderInfo.content.width = 100;
 loaderInfo.content.height = 100;
}

It loads the same image over and over and places each copy in a random spot on the stage. It's a big image. On my broadband connection, it takes about five seconds to appear.

I expected the first copy to take a while to load. But I figured it would get cached, and that the subsequent ones would appear instantaneously. But to my surprise, they didn't. When I compiled a test movie, I found I had to wait for each copy to be loaded as it was pulled individually from the sever.

Then I tried loading the swf into Firefox. Once I ran it in the browser, it behaved as expected: five seconds for the first image and then -- bing! -- the others appeared all at once.

Firebug confirmed that the swf only make one call to the server.

For some reason, I thought Flash had its own internal cache. Apparently it doesn't. It uses the brower's cache.

order matters

2009-08-28T08:07:00.000-07:00

When we code, we constantly have to create instances and set their parameters. How should we order statements when we're creating several instances of the same type? Should we create the instances first and then set their parameters?


var mercury : Planet = new Planet();
var venus : Planet = new Planet();
var earth : Planet = new Planet();
var mars : Planet = new Planet();

mercury.moons = 0;
venus.moons = 0;
earth.moons = 1;
mars.moons = 2;

Or should we group together each instance's creation and settings?


var mercury : Planet = new Planet();
mercury.moons = 0;

var venus : Planet = new Planet();
venus.moons = 0;

var earth : Planet = new Planet();
earth.moons = 1;

var mars : Planet = new Planet();
mars.moons = 2;

Or should we group together constructor calls and settings but leave variable declarations separate:


var mercury : Planet;
var venus : Planet;
var earth : Planet;
var mars : Planet;

mercury = new Planet();
mercury.moons = 0;

venus = new Planet();
venus.moons = 0;

earth = new Planet();
earth.moons = 1;

mars = new Planet();
mars.moons = 2;

I prefer this last approach. It's easiest to read and it groups together the parts of the code I'm most likely to change in tandem. But it's not always possible:


var planets : Array = new [ new Planet(), new Planet(), new Planet(), new Planet() ];

for each ( var planet : Planet in planets ) planet.moons = Math.floor( Math.random() * 10 );

Also, I'd consider a different type of ordering if parameters values of one instance are related to parameter values of another instance:


var mercury : Planet;
var venus : Planet;
var earth : Planet;
var mars : Planet;

mercury = new Planet();
mercury.moons = 0;

venus = new Planet();
venus.moons = 0;

earth = new Planet();
earth.moons = 1;

mars = new Planet();
mars.moons = 2;

mercury.distanceFromSun = 30000000;
venus.distanceFromSun = mercury.distanceFromSun + 30000000;
earth.distanceFromSun = venus.distanceFromSun + 30000000;
mars.distanceFromSun = earth.distanceFromSun + 50000000;

As always, we should remember that the primary job of code is to communicate our intentions to other programmers (sometimes the "other programmer" is the original programmer two months in the future, when he's forgotten his original intentions). So we can often make ordering decisions by thinking about the story we're trying to tell. Compare this ...

"Once upon a time there lived a beautiful princess, an evil dragon, and a brave knight. The princes was 16 years old; the dragon was 200 years old; the night was 28 years old. The princess had blonde hair; the dragon was bald; the knight had red hair. One day, the princess wandered down to the lake. The dragon liked to eat peasants. The knight fought in many tournaments."

... with ...

"Once upon a time there lived a beautiful princess. She was 16 years old and had blond hair. One day she wandered down to the lake. There was also an evil dragon. He was 200 years old, bald, and he liked to eat peasants. Also, there was a brave knight who was 28 years old. He had red hair, and he fought in many tournaments."

There's no right answer. What's important is to think each case through and decide which approach best communicates your intentions.

(Thanks Tim for sparking this topic.)

don't pass variables through classes

2009-08-26T08:57:00.001-07:00

Sometimes I find myself writing dangerous code like this:


public class UFO
{
 public function UFO( alienColor : uint )
 {
  var alien = new Alien( alienColor );
  
  ...
 }
}

It's dangerous because I'm passing UFO a parameter that it doesn't use. All it does with that parameter is pass it through to Alien's constructor.

Why is this dangerous? Well, first of all, it makes the code difficult to understand. You're probably not confused my example, above, because I made it purposefully simple. In real-life examples, when I give myself license to pass-through parameters, I tend to pass them through multiple levels:


public class UFO
{
 public function UFO( alienColor : uint )
 {
  var bridge : Bridge = new Bridge( alienColor );
  
  ...
 }
}

public class Bridge
{
 public function Bridge( alienColor : uint )
 {
  var alien = new Alien( alienColor );
  
  ...
 }
}

This is also dangerous because it's ugly. You should pass a constructor only the info necessary to construct its class. The construction crew building the UFO and its bridge don't need to know the alien's color.

Finally, it's ugly because it makes testing difficult. alienColor has multiple chances to get messed up (e.g. set to some illegal value) before it reaches its intended target, Alien.

So how should I write this code? Well, UFO doesn't need to know anything about an alien's color. It just needs a completed alien so that it has a pilot (to help it destroy the Earth!). So I should first construct an alien and then pass it to UFO.


var alienColor : uint = 0xFF00FF;
var alien : Alien = new Alien( alienColor );
var ufo : UFO = new UFO( alien );

or, if there's a bridge in the UFO, I should code like this:


var alienColor : uint = 0xFF0000;
var alien : Alien = new Alien( alienColor );
var bridge : Bridge = new Bridge( alien );
var ufo : UFO = new UFO( bridge );

how do you integrate library assets into your code?

2009-08-24T08:47:00.000-07:00

I'm curious as to how folks reference library assets in their code. (I'm talking about Flash projects, not Flex projects).

I don't know if I'm doing it the wisest way, but I create a package called flaBridge. In that package, I make a class for each library item. Often the class is empty...


package com.grumblebee.project.flaBridge
{
  import flash.display.Sprite;

  class CompanyLogo extends Sprite
  {
     public function CompanyLogo()
     {

     }
  }
}

I then link to this class in the fla Library.

This gives me a placeholder for adding specific functionality. It also stops my IDE (FDT) from complaining that I'm referencing classes that don't exist.

If I'm referencing an instance that's on the fla Stage, I do it this way:

var logo : CompanyLogo = this[ "logo" ]; //on stage

NaN != NaN

2009-08-20T13:03:00.000-07:00

Let's talk about dividing by zero.

As you probably know, in Math the result of dividing a (real) number by zero is undefined. What is the result of division by zero in AS 3.0?

It depends. If you divide a number other than zero by zero, you get Infinity:

trace( 10 / 0 ); //Infinity

trace( 876 / 0 ); //Infinity

If you divide zero by zero, you get NaN (which stand for "not a number").

trace( 0 / 0 ); //NaN

(By the way, to test if the value is NaN, you can't ask "if ( myVar == NaN )." Instead, you have to ask "if ( isNaN( myVar ) )." )

I learned this nuance recently while trying to fix a weird bug. I was setting the scaleX property of a Sprite. The Sprite was a loader bar, and I was setting its scaleX equal to the percent loaded:

bar.scaleX = loaded / total;

When I tested it in Firefox, the bar was totally invisible. I actually expected that, because I hadn't coded the loading process yet. I thought I was correctly calculating the total. In other words, I expected loaded / total to be equivalent to something like 0 / 87.

What I didn't know is that total was also zero. So I was actually doing this...

bar.scaleX = 0 / 0;

Which is the same as...

bar.scaleX = NaN;

But, like I said, I didn't notice a problem, because the bar was doing what I expected -- showing me that zero percent had loaded by being invisible.

I noticed the problem when I checked out my SWF in Internet Explorer. (I had Flash Player 10 installed in both IE and Firefox.) In IE, the bar was not invisible. It was big. It was so big that it filled up the entire screen!

Eventually, I figured out that I was dividing zero by zero. That still didn't tell me why I was seeing a giant bar in IE and no bar in Firefox. But when I set the numbers to, say, 10 / 1 or 6 / 0, the bar looked the same in both browsers. Which is when I learned that, in AS 3.0, zero divided by zero is NaN. And it's when I learned that the IE and Firefox plugins treat NaN differently when it's used to set the scaleX value of a Sprite.

Why would you want to scale a Sprite to NaN? Hopefully, you wouldn't. I did it by accident.

In both browsers, you get fill-the-whole-screen Sprites if you set scaleX to Infinity (which I guess makes sense: the Sprite gets infinitely wide). So my guess is that in Firefox, sprites interpret a scaleX of NaN as zero, whereas in IE they interpret it the same way they interpret Infinity.

when null is not null

2009-08-18T07:46:00.001-07:00

Having just left the debugging Twilight Zone, I am going to post my findings so that others can profit from my woes.

I had a simple if statement like this:

if ( someValue == null ) trace( "null" );
else ( trace( "not null" );

I expected the value to be null, so I was surprised to see "not null" appear in the output window.

To check my sanity, I added a trace above the conditional:

trace( "someValue == ", someValue );
if ( someValue == null ) trace( "null" );
else ( trace( "not null" );

To my horror, I got this:

someValue == null
not null

After half an hour of tripping in Bizarro World, I noticed those extra spaces before the word "null" in the first trace. This prompted me to take a look at someValue's declaration:

var someValue : String = myFlashVars.someValue;

myFlashVars is, as you might guess, an object containing all the flashVars. I expected someValue to be null, because, while testing, I wasn't passing any vars into the swf.

Okay, I lied. The declaration wasn't this...

var someValue : String = myFlashVars.someValue;

... it was this:

var someValue : String = unescape( myFlashVars.someValue );

Since myFlashVars got set with URL variables (e.g. http://myapp.swf?someValue=foo), I wanted to make sure that any escaped characters in someValue got converted to unescaped ones.

But this causes a problem when there is no myFlashVars.someValue. If there is no myFlashVars.someValue, then myFlashVars.someValue = null.

And, apparently, if you unescape null, you get the string " null".

So my conditional was testing whether " null" is equal to null. And of course it's not.

keep logic out of constructors

2009-08-12T12:24:00.000-07:00

I'm sometimes tempted to overstuff constructors:


public class AxeMurderer
{
 private var _name : String;
 private var _crazy : Boolean;
 
 public function AxeMurderer( name : String, crazy : Boolean )
 {
  _name = name;
  _crazy = crazy;
  
  if ( _crazy )
  {
   for ( var i : int = 0; i < 10000; i++ )
    trace( "all work and no play makes Jack a dull boy" );
  }
 }
}

The overstuffing is the for loop (and possibly the conditional). I clean things up a bit by refactoring to...


public class AxeMurderer
{
 private var _name : String;
 private var _crazy : Boolean;
 
 public function AxeMurderer( name : String, crazy : Boolean )
 {
  _name = name;
  _crazy = crazy;
  
  if ( _crazy ) writeManifesto();
 }
 
 private function writeManfesto() : void
 {
  for ( var i : int = 0; i < 10000; i++ )
   trace( "all work and no play makes Jack a dull boy" );
 }
}

But this creates a problem when I write an interface for the class.

Let me pause to say that I try to write my interfaces first, before writing the classes that implement them. That way I'm coding TO an interface. However, in real life that doesn't always happen. Sometimes I can't work out an interface without first writing at least a dummy implementation. In such cases, I go back and write an interface later. At least that I way I have the interface for similar classes.

So, having written the AxeMurderer class, I decide to create an IMurderer interface -- one that has a slightly broader scope than just axe murderers:


public interface IMurderer
{
 //Hmmmm....
}

What do I put inside the interface? Looking back at my AxeMurderer class, the only public method is the constructor. That's because I got tempted by a (anti?) pattern: make the constructor build the object by calling a bunch of private methods.

So the interface would be...


public interface IMurderer
{
 function AxeMurderer( name : String, crazy : Boolean )
}

But that would force any class that implemented it to have an AxeMurderer method -- terribly inappropriate for a Poisoner or a Strangler!

So, assuming that all types of murders might write a manifesto, I'm going to change my interface to...


public interface IMurderer
{
 function writeManifesto() : void;
}

(I'm using a short example to illustrate a point. A real-life IMurderer would insist on methods like Kill(), Spare(), Escape(), Surrender() and BlameItOnJunkFood().)

Now I'll rewrite AxeMurderer as follows:


public class AxeMurderer implements IMurderer
{
 private var _name : String;
 private var _crazy : Boolean;
 
 public function AxeMurderer( name : String, crazy : Boolean )
 {
  _name = name;
  _crazy = crazy;
  
  if ( _crazy ) writeManifesto();
 }
 
 //NOTE: Method now public
 public function writeManfesto() : void
 {
  for ( var i : int = 0; i < 10000; i++ )
   trace( "all work and no play makes Jack a dull boy" );
 }
}

Note that I'm still calling writeManifesto() in the constructor. That's fine. Some IMurderer classes may choose to automatically write a manifesto; others may choose to only write one if writeManifesto() is called by an external client.

In general, I try to use constructors just for getting necessary external data into the class. Class logic goes elsewhere.

a super solution

2009-08-10T12:51:00.000-07:00

Like many developers, I favor Composition over Inheritance. Still, subclassing is a powerful tool, and I can't imagine abandoning it altogether. Knowing its pifalls, I try to make my intentions as clear as possible when I choose to use Inheritance.

When I read other-people's code, I tend to get confused by inherited variables. Say I'm skimming over a class with three members: width, height and color. I read method after method that mentions these members. Then all of the sudden, one lone method mentions position.

Huh? What's position? Why haven't I seen it before? I scroll around, looking for its definition, but I don't find it. Finally, I remember that I'm looking at a subclass. "Oh! Maybe position is defined in its parent class." I flip over to that class and, sure enough, there's position's declaration. (This must be a total nightmare in languages that support multiple inheritance.)

But I've now wasted brain cells on something other than the task at hand (whatever that was). I shouldn't have to go searching for vars.

To fix this in my own code, I'm going to start labeling inherited vars as with the prefix "super."


function foo() : void
{
  var someValue : Number = width + super.position.x;
}

If I look at code like that, I know exactly where position comes from.

what a drag

2009-08-10T08:24:00.001-07:00

Like most developers, I make little shortcut utilities to help me bypass repetitive tasks. For some reason, though, I'd never bothered to come up with a solution for the tedious work of drag and drop. Nor have I researched anyone else's solution. But recently, I've had to make a lot of Sprites and MovieClips draggable. After the fifth or sixth time I'd added and removed a bunch of listeners, I thought "There's got to be an easier way."

I thought of two: the first was to extend Sprite, creating DraggableSprite. The second was to make a separate class that only handled dragging and leave Sprite's many other duties to Sprite itself. I settled on the latter, reasoning that Sprite was already bloated enough.

Before sharing my solution, let me outline the steps needed to make a Sprite draggable. First, you need a way to detect when the user has mouse-downed on the Sprite. So you have to add a listener for that.

Inside that listener's callback function, you can go head and call startDrag() on the Sprite. But you also need to remove the MOUSE_DOWN listener, because while the user is dragging the Sprite, listening for mouse downs is just burning computer cycles for nothing.

Meanwhile, you have add a listener for MOUSE_MOVE (in case you need to know when the Sprite moves, as you for the thumb control on a slider or scrollbar). You also need to add two MOUSE_UP listeners, one to the Sprite and one to the stage. The stage listener traps for the the user rolling off the Sprite before releasing his mouse button.

In the MOUSE_UP handler, you call stopDrag(), remove all of the above listeners, and re-add the MOUSE_DOWN listener, so that the process can start all over again.

These steps aren't too bad, unless you wind up having to do them over and over. Compare them with using my DragManager class, which you instantiate this way:

var dragManager : DragManager = new DragManger( mySprite );

That's it. mySprite is now dragabble. If you want control over the optional parameters of startDrag() -- lockCenter and bounds -- just pass them to the Dragmanager constructor as additional parameters:

var dragManager : DragManager = new DragManger( mySprite, true, myRect );

Note: lockCenter defaults to false; bounds defaults to null.

Of course, you usually want to do more than just make a Sprite or MovieClip draggable. You also want to know when it starts being dragged, where it moves, and when it stops being dragged. You can detect these things by adding listeners to the DragManager instance.


var dragManager : DragManager = new DragManger( mySprite );
draggManager.addEventListener( DragManager.START_DRAG, handler );
draggManager.addEventListener( DragManager.DRAG, handler );
draggManager.addEventListener( DragManager.STOP_DRAG, handler );

function handler( event : Event ) : void
{
 trace( event.type, event.currentTarget.dragger.name );
}

If you run this code, you'll see the following output as you drag and drop your Sprite:

startDrag mySprite
drag mySprite
drag mySprite
drag mySprite
drag mySprite
drag mySprite
stopDrag mySprite

Note that, inside the handler, you can get access to the Sprite being dragged by referencing event.CurrentTarget.dragger.

DragManager has a couple of other tricks up its sleeve. You can disable dragging by calling disableDrag() and re-enable it by calling enableDrag(). You can also re-use the same DragManager by changing which object it controls:

var dragManager : DragManager = new DragManger( myMovieClip );

//later

dragManager.sprite = mySprite;

Note: ordinarily, I wouldn't bother being this thrifty. If I want to make both a Sprite and MovieClip draggable, I just do this:

var spriteDragManager : DragManager = new DragManger( mySprite );
var movieClipDragManager : DragManager = new DragManger( myMovieClip );

But the previous approach is useful if you want only one of the objects to be draggable. DragManagers can manage multiple objects, but only one at a time.

Other properties include lockCenter and bounds, which you can use if you want to change aspects of the drag after it's started. Note that if you do this, you need to disable and re-enable the drag to make the changes take effect:

var dragManager : DragManager = new DragManger( mySprite );

//later

dragManager.disableDrag();
dragManager.lockCenter = true;
dragManager.bounds = new Rectangle( 20, 100, 200, 0 );
dragManager.enableDrag();

Note: disableDrag() removes all listeners from the Sprite, so it's a good cleanup method for eliminating CPU-hogging processes.

It's such a joy to write classes like DragManager. Or, rather, it's a joy to HAVE written them. Once they're done and tested, you know you've cut a piece of tedium out of your life.

Here's the code: http://www.grumblebee.com/grumblecode/DragManager.zip

on the use of constructors

2009-08-05T09:32:00.000-07:00

I've tried constructing objects in every way imaginable. After reading many books, blog-posts and essays about best-practices, I was swayed by people who argued that the all data an object needs should be fed to it via its constructor. Before coming to that conclusion, I used to write lots of parameter-initialization methods.


public class Spaceship extends Sprite
{
 private var _hullColor : uint;
 private var _hasLaser : Boolean;
 private var _laserColor : uint;
 
 ... more private properties ...

 public function set hullColor ( value : uint ) : void
 {
  _hullColor = value;
 }
 
 public function set hasLaser( value : uint ) : void
 {
  _hasLaser = value;
 }
 
 public function set laserColor( value : uint ) : void
 {
  _laserColor = value;
 }
 
 ... more setter methods ...
 
 public function render() : void
 {
  ... code that draws the space ship ...
 }
}

Using this method, I'd create a Space-ship instance as follows:


var ussValiant : SpaceShip = new SpaceShip();
ussValiant.hullColor = 0x666666;
ussValiant.hullShape = HullShape.CIGAR;
ussValiant.hasLasers = true;
ussValiant.laserColor = 0x00cc00;
ussValiant.hasBridge = true;
ussValiant.bridgeColor = 0x666666;
ussValiant.bridgeShape = BridgeShapes.SPHERE;
ussValiant.bridgeSize = BridgeSizes.large;

ussValiant.render();

The trouble here is that it's impossible to tell whether or not I need to set all the parameters or if some of them are optional. Do I need to set them in a particular order? What happens if I set one after calling render? To even know about all the parameters, I have to read through the whole class's API. If, instead, I set all necessary parameters via a constructor, a quick glance at its heading will tell me everything I need to know about parameter order and requirements:


public function SpaceShip( hullColor : uint, hullShape : uint, hasLasers : Boolean = false,
       laserColor : uint = 0, hasBridge : Boolean = false,
       bridgeColor : uint = 0, bridgeShape : String = "sphere",
       bridgeSize = "small" )

The obvious downside to this approach is the unwieldy number of parameters that are stuffed inside the constructor's parentheses. It was this very problem that originally convinced me to write all those setters. I hate overstuffing a constructor, because constructors should take, at most, three parameters.

Why three? Well, it's not a hard and fast rule. It's just an aesthetic. Three, because it's relatively easy to remember three things. After that, it gets harder, at least for my poor, addled brain. Constructors that take four or more parameters are hard to use and hard to read without confusion. Compare the following:

THE BEST KIND OF CONSTRUCTOR:
var puppy : Puppy = new Puppy();

A VERY GOOD CONSTRUCTOR:
var name : String = "Fred";
var monster : Monster = new Monster( name );

A PERTTY GOOD CONSTRUCTOR:
var bread : String = BreadTypes.RYE;
var meat : String = MeatTypes.TURKEY;
var hasMayo : Boolean = true;
var sandwich : Sandwich = new Sandwhich( bread, meat, hasMayo );

A DUBIUS CONSTRUCTOR:
var hasMilk : Boolean = false;
var hasSugar : Boolean = true;
var isIced : Boolean = false;
var size : String = CoffeeSizes.GRANDE;
var coffee : Coffee = new Coffee( hasMilk, hasSugar, isIced, size );

A TERRIBLE CONSTRUCTOR:
var title : String = "Lonesome Parrot";
var genre : GenreTypes.WESTERN;
var stars : Array = [ "Ian McShane", "Michelle Pfeiffer" ];
var director : String = "Stephen Spielberg";
var writer : String = "Thomas Kenneally";
var budget : Number = 50000000;
var hasSequel : Boolean = true;
var movie : Movie = new Movie( title, genre, stars, director, writer, budget, hasSequel );

When faced with the prospect of a terrible constructor, it's tempting to just pass it a value object:


public class MovieData
{
 public var title : String;
 public var genre : String;
 public var stars : Array;
 public var director : String;
 public var writer : String;
 public var budget : Number;
 public var hasSequel : Boolean = true;
}

The benefit here is that the constructor now only needs to take in one parameter:

var movie : Movie = new Movie( movieData : MovieData );

The problem with this approach is that the constructor has lost its power to communicate. From looking at its signature, all I know is that it takes in some vague sort of data. I have to look at the value-object class to learn more. And looking at that still doesn't tell me whether or not I need to give every parameter a value or if some are optional.

Sometimes, this is the best I can do. But usually, I can solve this problem by breaking up the class into several smaller classes. In fact, when I feel the need to pass a constructor many parameters -- via raw values or through a value object -- I take it as a sign that my thinking isn't granular enough.

For instance, does it really make sense to have just one monolithic movie class? At the very least, I can break it up into Movie, Metadata and Staff:


public class Staff
{
 ...

 public function Staff( director : String, writer, String, stars : Array )
 {
  ...
 }

 ...
}

public class Metadata
{
 ...
 
 public function Metadata( title : String, genre : String, budget : Number, 
        hasSequel : Boolean = false )
 {
  ...
 }
        
 ...
}

public class Movie
{
 ...
 
 public function Movie( metadata : Metadata, staff : staff )
 {
   ...
 }
}

I'm not crazy about the Metadata class, because it has four parameters, which violates my aesthetic limit. Perhaps I'll leave it as is, though. I'm not dogmatic about the three-parameter rule. However, looking at the parameters, I do have a vague feeling that "budget" is a different sort of beast from "title", "genre" and "hasSequel". I might consider creating a new class called Finances or at least keep that option open in my mind. I know for sure that I don't want to add any more parameters to Metadata! Maybe Metadata itself should take in three parameters, category (title and genre), hasSequels and finances( budget ). Or maybe Metadata should only be about the title, genre and sequels. Maybe Movie should take in metadata, staff and finances.

Regardless of my ultimate decision, my gaol is to keep everything small: small number of parameters, small methods and small classes. Small is good, because small is readable; small is easy to maintain.

This super-modular approach mirrors the way we think. If I ask you to tell me about your best friend, you might say, "His name is Bob. He's a lab technician." Translated to OOP, that's...

var bestFriend : Person = new Person( "Bob", "lab technician" );

But what if I ask you to describe Bob in more detail. You're likely to say something like, "Well, he's been married for ten years and he has a little girl named Sarah. He has brown hair and green eyes. He lives in Seattle." Notice how you broke down your description into categories. You're didn't amorphously describe Bob. You specifically told me about his family, his looks and his location.

You're didn't do this:

var bestFriend : Person = new Person( "Bob", "lab technician", 10, "Sarah", "brown", "green", "Seattle" );

You did this:

var family : Family = new Family( 10, ["Sarah"] );
var looks : Looks = new Looks( "green", "brown" );
var location : Location = new Location( "Seattle" );
var bestFriend : Person = new Person( "Bob", "Lab Technician", family, looks, location );

That's two too-many parameters, but it's more readable and natural than the former version. Maybe name, occupation and looks could be bundled into a class called Description. That would give you...

var bestFriend : Person = new Person( description, family, location );

The goal isn't to come up with the perfect solution. There isn't a perfect solution. The gaol is to continually play around to make your code as simple and communicative as possible.

adobe's mistake: displayObjects need interfaces

2009-08-03T07:59:00.000-07:00

Last week, I wrote a function that drew a randomly-colored circle on a Sprite:


function randomColoredCircle( target : Sprite ) : void
{
 var color : uint = Math.round( Math.random() * 0xFFFFFF );
 var xPosition : Number = 0;
 var yPosition : Number = 0;
 var radius : Number = 30;
 
 target.graphics.beginFill( color );
 target.graphics.drawCircle( xPosition, yPosition, radius );
 target.graphics.endFill();
}

To call this function, all I had to do was hand it a Sprite to draw on:


var sprite : Sprite = new Sprite();

randomColoredCircle( sprite );

addChild( sprite );

This worked fine until I suddenly needed to draw a circle on a MovieClip. I couldn't hand a MovieClip to the function, because it specifically requests Sprites:


function randomColoredCircle( target : Sprite ) : void //won't accept a MovieClip

NOTE: a commenter pointed out that MovieClips do, in fact, inherit from the Sprite class, so the above function will work. However, as you'll see (below), the Shape class does not extend Sprite (or vice versa), so the problem remains.

The worst possible solution to this problem is to make another version of the function that's exactly the same, except it draws on MovieClips:

BAD:


function randomColoredCircleOnSprite( target : Sprite ) : void { ... }
function randomColoredCircleOnMovieClip( target : MovieClip ) : void { ... }

Using this approach, I might have to make a third function that draws circles on Shapes. Ugh! This is begging for trouble. What if I decide to make the circles smaller? I would have to remember to update "var radius : Number = 30" in all three functions.

Here's a better solution -- one I would advocate if Actionscript wasn't an object-oriented langiage:


function randomColoredCircleOnSPRITE( target : Sprite ) : void 
{
 var canvas : Graphics = target.graphics;
 randomColoredCircle( canvas );
}

function randomColoredCircleOnMOVIECLIP( target : MovieClip ) : void 
{  
 var canvas : Graphics = target.graphics;
 randomColoredCircle( canvas );
}

function randomColoredCircle( canvas : Graphics ) : void
{
 var color : uint = Math.round( Math.random() * 0xFFFFFF );
 var xPosition : Number = 0;
 var yPosition : Number = 0;
 var radius : Number = 30;
 
 canvas.beginFill( color );
 canvas.drawCircle( xPosition, yPosition, radius );
 canvas.graphics.endFill();
}

This works by having separate functions for Sprite and MovieClip objects. All those functions do is to extract Graphics objects from their owners and send the Graphics to another function, one that actually does the drawing. This works, because though MovieClips and Sprites are different classes, a Graphic is a Graphic is a Graphic. I can now easily draw on Shapes by making one more graphic-extraction function:


function randomColoredCircleOnSHAPE( target : Shape ) : void 
{
 var canvas : Graphics = target.graphics;
 randomColoredCircle( canvas );
}

Though this approach moves in the right direction, we can do better. In an object-oriented system, if you want to do the same thing to two related classes, you do it to their parent class. In fact, both MovieClip and Sprite descend directly from DisplayObject. So, in theory, I should be able to elegantly solve my problem (and eliminate all the graphics-extractor classes) by drawing on DisplayObjects instead of MovieClips and Sprites:


function randomColoredCircle( target : DisplayObject ) : void 
{
 var color : uint = Math.round( Math.random() * 0xFFFFFF );
 var xPosition : Number = 0;
 var yPosition : Number = 0;
 var radius : Number = 30;
 
 target.graphics.beginFill( color );
 target.graphics.drawCircle( xPosition, yPosition, radius );
 target.graphics.endFill();
}

The variable target can accept any object in the DisplayObject family, so I can call this function as follows:


var sprite : Sprite = new Sprite();
var movieClip : MovieClip = new MovieClip();

randomColoredCircle( sprite );
randomColoredCircle( movieClip );

Unfortunately, this WON'T WORK. I'll get an error telling my that DisplayObjects don't have a property called "graphics." In fact, they don't. This is because though MovieClips, Shapes and Sprites have graphics properties, there are other DisplayObjects that don't. For instance, TextField is a DisplayObject descendant that doesn't have a graphics property. You can't draw on a TextField.

The definition of DisplayObject looks like this:


public class DisplayObject
{
 private var _x : Number;
 private var _y : Number;
 ...
 //Note: no _graphics property! 
}

MovieClip, Sprite and Shape extend DisplayObject like this:


public class MovieClip extends DisplayObject
{
 ...
 private var _graphics : Graphics;
}

TextField extends it like this:


public class TexTField extends DisplayObject
{
 private var _embedFonts : Boolean;
 private var _text : String;
 ...
 //Note: no _graphics property! 
}

So though you can store both a Sprite and a MovieClip in a variable typed to DisplayObject, you can't access the graphics property of that variable, because DisplayObjects don't have graphics.

However, since several of DisplayObject's children DO have graphics properties, you should be able to refer to all those children generically via a common interface. In other words, what Adobe SHOULD have done -- but didn't -- is to define an IDrawable interface like this:


public interface IDrawable
{
 //returns the private _graphics property
 function get graphics () : Graphics;
}

Then, it should have implemented this interface for MovieClip, Sprite and Shape:


public class MovieClip extends DisplayObject implements IDrawable
{
 ...
}

public class Sprite extends DisplayObject implements IDrawable
{
 ...
}

public class Shape extends DisplayObject implements IDrawable
{
 ...
}

Had Adobe just added that little bit of extra code, we could type variables as IDrawable and not have to worry about whether they were Sprites, MovieClips or Shapes:


var sprite : IDrawable = new Sprite();
var moveClip : IDrawable = new MovieClip();
var shape : IDrawable = new Shape();

randomColoredCircle( sprite );
randomColoredCircle( movieClip );
randomColoredCircle( shape );

The last step to making this work is to rewrite the randomColoredCircle function so that it accepts IDrawable objects:


function randomColoredCircle( target : IDrawable ) : void
{
 var color : uint = Math.round( Math.random() * 0xFFFFFF );
 var xPosition : Number = 0;
 var yPosition : Number = 0;
 var radius : Number = 30;
 
 target.graphics.beginFill( color );
 target.graphics.drawCircle( xPosition, yPosition, radius );
 target.graphics.endFill();
}

This works because ALL IDrawable objects have a graphics property:


public interface IDrawable
{
 //returns the private _graphics property
 function get graphics () : Graphics;
}

Like I said, we COULD have used this method IF Adobe had just implemented a common interface for all the classes with graphics properties. They should have done this, as it's a standard and good programming technique, but they didn't. However, all is not lost, because we can do it ourselves by extending the MovieClip, Sprite and Shape classes and making sure our new classes implement IDrawable.

Below, I'll show the complete code to do this. It's a small amount of code, involving some empty classes. The classes are empty because we don't want to add anything to them other than the fact that they implement IDrawable. In other words, MySprite is exactly the same as Sprite, except for the fact that MySprite implements IDrawable and Sprite doesn't:


package
{
 import flash.display.Graphics;
 
 public interface IDrawable
 {
  function get graphics() : Graphics
 }
}

package
{
 import flash.display.Sprite;
 
 public class MySprite extends Sprite implements IDrawable
 {
 
 }
}

package
{
 import flash.display.MovieClip;
 
 public class MyMovieClip extends MovieClip implements IDrawable
 {
 
 }
}

package
{
 import flash.display.Shape;
 
 public class MyShape extends Shape implements IDrawable
 {
 
 }
}

That's it. Now I just need to use MyShape, MySprite and MyMovieClip instead of Shape, Sprite and MovieClip, and I'll be guaranteed that all of my classes will implement a common interface:


var sprite : MySprite = new MySprite();
var movieClip : MyMovieClip = new MyMovieClip();
var shape : MyShape = new MyShape();

randomColoredCircle( sprite );
randomColoredCircle( shape );
randomColoredCircle( movieClip );

MyShape, MySprite and MyMovieClip have all properties and methods of Shape, Sprite and MovieClip (width, rotation, etc.), because they inherit those properties from the classes they extend.

Even if you don't ever need to treat Sprites, Shapes and MovieClips as if they are all the same type of objects, I hope my approach shows off the usefulness of common interfaces. If you have several classes that share similar traits, it's key that you relate those classes via inheritance and/or an interface. Doing so will make your code much more extendible for future projects.

rounding cornders

2009-08-02T13:04:00.000-07:00

Whenever possible, I draw with code instead of with Flash's drawing tools. I do this because (a) it allows me to make dynamic changes to shapes at run-time, and (b) because it keeps all the app-construction info in one place (in the code), not split between the code and the stage or library.

But I keep needing shapes with rounded corners. Actionscript has a built-in rounded-corner rectangle class (graphics.drawRoundedRect), but that's the only rounded-cornder method available. I often need rounded-corner triangles, rounded-corner tooltips and rounded-corner circles (just kidding on that last one). So I decided to create a method that allowed me to round the corners of any shape.

I knew I'd need math, which is not my strong point. So I ignored that problem and focused on how I'd create rounded corners with a Bezier-pen tool. Think of the top of a triangle: imaging making points on both of the lines that meet at the top (the apex). If those points are down a little from the top, they can act as start and end points for a Bezier curve. In the illustration, below, I've drawn the start and end points as red dots.

A point at the apex (blue dot) can act as a control point, giving you all the points you need to draw a curve:

Note: Actionscript's Bezier curves have just one control point. The curve is the widest-possible path that Flash can draw without it crossing outside the triangle formed by the start, end and control points.

With this approach, I could make a rounded-cornered shape by starting with a straight-cornered shape and calculating a Bezier curve for each corner.

The first step would be to figure out how to plot points that are a little ways in from the ends of all the lines, as shown by the red dots, above. Generalizing this, I needed a way to find a point on a line. Which is where math reared its ugly head. Luckily, google exists for moments like this. Before long, I found a formula and turned it into a nifty function:


function pointOnLine(t : Number, point1 : Point, point2 : Point ) : Point
{
 var xResult : Number = point1.x + ( t * ( point2.x - point1.x ) );
 var yResult : Number = point1.y + ( t * ( point2.y - point1.y ) );
 return new Point( xResult, yResult );
}

You can use this function by first creating two points that make up a line...


import flash.geom.Point;

var start : Point = new Point( 100, 100 );
var end : Point = new Point( 100, 500 );

... and then handing the points to the pointOnLine function. You also have to hand it t, which is a number between 0 and 1. A t of zero returns the start-point of the line; a t of .5 returns the mid-point of the line. A t of 1 returns the end-point of the line. And so on. So to get a point close to the end of the line, I could call the function like this:


var nearEnd : Point = pointOnLine( .8, start, end );

That out of the way, I could now calculate all the start and end points I needed by calling pointOnLine() twice for each line in my shape, e.g.


//note that I'm using .2 and .8 for t
var nearStart : Point = pointOnLine( .2, start, end );
var nearEnd : Point = pointOnLine( .8, start, end );

Here's an illustration of nearStart and nearEnd for one lines on a triangle:

Now all I had to do was to loop through all the lines on the triangle to find the rest of the start and end points:

After that, it was easy to find the corner points, since they were used to define the triangle in the first place:

I then drew curves through each group of start-end-corner points with the built in curve-to function:


graphics.moveTo( start.x, start.y );
graphics.curveTo( control.x, control.y, end.x, end.y );

In the illustrations here, I've drawn the triangle so you can understand my thought process. In fact, my code never draws the straight-edge version. If it did, it would have to go back later and erase the non-curvy corners. Instead, it draws actual lines from the two inset points of each virtual line: e.g. lines from the .2 t to the .8 t of each line.

If I go through the same process with the t values adjusted to move the pointOnLines in a little, say .4 and .6, I get something like this:

I packaged up my code in a utility class called RoundedShapes. To use it, you call its draw() method as follows:


RounedShapes.draw( target, roundness, points );

The target parameter is the display object on which you want to draw. It can be any object with a graphics property: e.g. Sprite, MovieClip or Shape.

The roundness parameter is essentially t. Roundness must be a number between 0 and 1, 0 being the same as straight.

The points parameter is an array of Points, defining the straight-corner version of the shape.

To draw a rounded-corner triangle, you could use code like this:


import com.grumblebee.ui.drawing.RoundedShapes;

var sprite : Sprite = new Sprite();
var points : Array = [ new Point( 320, 10 ),
   new Point( 420, 80 ),
   new Point( 320, 160 ),
   new Point( 320, 10 ) ];

var roundness : Number = .2;

sprite.graphics.lineStyle( 2, 0x000000 );
sprite.graphics.beginFill( 0xFF0000 );
RoundedShapes.draw( sprite, roundness, points );
sprite.graphics.endFill();
addChild( sprite );

Here's a swf with some example shapes drawn by RoundedShapes.draw(). Just for fun, I animated the roundness parameter of the star:

Here's a link to the RoundedShapes class and an example fla. Happy rounding!

the beauty of interfaces

2009-08-01T14:03:00.000-07:00

= my humble origins =

For my first few years as a programmer, I had a hard time understanding interfaces.

Before continuing, let me explain what I mean by "interfaces," since people use the word in several ways. I'm not talking about user interfaces (buttons and the like). I always understood those. I'm talking about formal interfaces in Actionscript (and similar structures in other languages), the kind you define like this:

public interface MyInterface {}

I understood how to define an interface. That's easy, as I showed above. And I understood how to use one:

public class MyClass implements MyInterface {}

What I didn't understand was the point of interfaces. So I just never used them, and my programs seemed to work. So I couldn't see what interfaces would add to the mix.

Every once in a while, I heard sayings like, "Program to an interface, not to an implementation," and I'd just shrug and move on. (Actually, that saying really confused me. I couldn't get past "Program to". What did it mean to "program to" something? I understood "program for," as in "program for money" and "program by," as in "program by starting with small methods first," but what on Earth did "program to" mean?)

When I read programming books, they rarely seemed to be written for me. Like most Actionscript developers, I had worked my way up to programming via design and animation. Most of my projects were small and didn't involve a team. But the books I read were constantly talking about large-scale applications and the need to clarify your code so that other team-members could understand it. "Don't name a variable 'a'," those books told me, because 'no one will understand what that means.'" That didn't really resonate with me, because as the lone programmer on small projects, I could easily remember what my variables meant, even if I gave them cryptic names.

What no one told me is that small-time programmers gradually morph into big-time programmers. Before I knew it, my bosses and clients were asking me to add many new features to my programs, and those programs started to grow larger and larger. I found myself writing dozens of lines of code, then hundreds, then thousands... This change happened so gradually that I didn't notice it until I was knee deep in variables named "a," "foo" and "a2".

By the sixth week of a project, I couldn't understand what I had coded on the first week. Worse, sometimes my clients would ask me to add features to a project I'd shelved a year ago. When I dusted it off and looked at the code, it seemed to be written in Swahili.

= I am a team of one =

One day it dawned on me that I DID work on a team! My team was comprised of me last week, me last year, me yesterday, me today and me two months from now. And I'd get really pissed off at the me from last week if he didn't leave the code-base tidy, so that the me from this week could easily navigate through it. Many coders do, in fact, work on teams of multiple people. Most of the time, I still work alone. But I've come to realize this doesn't matter. It's just as important for me to write clean code for myself as it is for someone at Microsoft or Adobe to write clean code for their co-workers.

= what is clean code? =

"Writing clean code" means at least two things:

1. Writing code that rarely has to be examined.
2. Writing code that, if it DOES have to be examined, is easy to understand.

Point one means that coding is a form of organized forgetting. If it takes me five hours to write a complex sort routine, I don't ever want to have to look at its guts again. So I make sure it works and then stuff it in a function called sort(). That name is the only part of the routine that the future me should need to worry about. As far as he's concerned, the function looks like this:


function sort( array : Array ) : Array
{
 blah blah blah (it just works...)
}

But, because it's impossible to predict the future, there's a chance that the me of tomorrow might have to dig into the sort()'s guts. So I owe it to him to make the actual steps of the routine clear, too. That's the second point, above.

Sometimes I morbidly think of programming as if I'm making my will. I don't want my loved ones to be bothered by it while I'm alive. I just want them to know it exists. When I die, I want it to be easy to execute without anyone having to go through a lot of legal hassle. But if, for some reason, someone absolutely needs to examine it under a microscope, I want them to see that my will is well ordered, all i's dotted; all t's crossed.

= what is a programmer's job? =

Even when I first realized the import of clean code, I thought a programmer's job was to first make sure his program worked and only second to make sure it was easy to read. Over time, I realized that the opposite is true. My programs should first and foremost be easy for humans (including me next month) to read. Why? Because I'm inevitably going to spend more time debugging my programs than I spent writing them, and debugging is horrible (and costly in terms of man-hours) if the code is messy. Yes, it's important that a program works. But if the code is clean, it should be relatively easy to get it working if it's broken. But if the code is messy, it's hard to keep it from breaking and nearly impossible to fix it when it does break.

Have you ever had the horrible experience of fixing a bug and then finding that your fix caused another bug? And then fixing THAT bug and discovering that your second fix caused a worse bug? That's the horror of messy code. That doesn't happen with clean code.

= what does clean code look like? =

Clean code looks like anything else that's clean and organized:

"A place for everything and everything in its place."

This means making clear separations between parts: it means that you shouldn't write a class called GameAndHighScoreManager. You should write one class called GameManager and another called HighScoreManager; it means that you shouldn't write a function called moveCowboysAndIndians(); you should write one function called moveCowboys() and another called moveIndians().

And it means that you should separate interfaces from the implementations.

== what is an iterface? ==

An interface is the public parts of a class. It allows other classes to interact with that class. If there's a class called Human and a class called Dog, what parts of Dog does Human need to know about? (What parts of Dog do I have to think about while I'm programming Human? What parts of Dog can I forget about?) Human needs to feedDog(); he needs to walkDog(); he needs to know isDogAsleep(). However, he doesn't need to digestDogsFood() or makeDogsHeartBeat().

Class definitions give us an easy way to make some methods accessible while keeping others private, as I do here:


public class Dog
{
 public function feed( food : Food ) : void { ... }
 
 private function digest() : void { ... }
 
 ...
}

The problem with this is that I haven't separated my interface from its implementation. It's like a car that you have to drive by fiddling directly with the parts under the hood. Making some of those parts private is a good idea. But it's a bad idea to make other parts public by cutting strategic holes in the hood. Rather, a car should have an interface that's completely separate from its implementation. In fact, cars do. In a car, these interfaces are called dashboards. If you open a car's hood, you don't see little labels that say "public" and
private." Everything under the hood is private. Unless you're an expert, you should only be operating a car via its interface: the dashboard.

Alas, in the case of Dog, both interface and implementation are in the guts of the class. This can lead to some very confusing problems. For instance, let's say my Human class winds up feeding his dog:


public class Human
{
 public function feedDog( dog : Dog ) : void
 {
  var kibbles : Food = new Food( "kibbles" );
  dog.feed( kibbles );
 }
}

Everything should work fine unless some idiot -- e.g. the future me -- starts screwing around inside the Dog class.

Well, actually there's a lot I can do inside that class without causing a problem. For instance, I can change...


public function feed( food : Food ) : void
{
 yum yum yum...
}

to...


public function feed( food : Food ) : void
{
 yuck yuck yuck...
}

Because Human doesn't care about the innards of feed(). All Human cares about is calling the method. Once called, it's free to like or dislike it's food, without affecting Human.

But what if I change food's parameters?


public function feed( foodType : String, calories : int ) : void
{
 blah blah blah...
}

I've now broken Human:


public class Human
{
 public function feedDog( dog : Dog ) : void
 {
  var kibbles : Food = new Food( "kibbles" ); //this no longer works
  dog.feed( kibbles );
 }
}

I could also break Human by renaming Dog's feed method to chew() or bite().

If you take your car in to be repaired, you probably won't be upset if the mechanic changes things around under the hood, as long as your car works when you get it back. You won't even know what changes he made. However, if he messes with the interface -- if he removes the steering wheel and sticks the break pedal in the glove compartment -- you'll be confused and angry. Similarly, Human has a right to be angry, because Dog has changed his interface. But I can't really blame Dog. After all, his interface is inside him. It's not really an interface, it's just part of his implementation that's been labeled public.

= making a formal interface =

So how do we give Dog an real, dashboard-like interface? In Actionscript, we do it like this:


package
{
 public interface IDog
 {
  function feed( food : Food ) : void;
  function walk() : void
 }
}

By convention, interface names begin with a capital I. Inside the body of an interface, you list the signature of each public function (e.g. all the items on the dashboard). You don't label them "public," because everything in the interface is public -- that's the whole point of an interface. You don't list the body of the functions, because bodies are filled with implementation details. Implementation details do not belong on interfaces.

Now, I can tie my Dog class to this interface as follows:


public class Dog implements IDog { ... }

Anyone who wants to use my Dog class shouldn't bother looking at it's source code. Instead, they should look at its interface. It's interface contains everything users need to know. Dog itself is just a confusion of details. Users should...

... program to the interface, not the implementation!

By saying that Dog "implements IDog," that class is making a promise. It's promising to conform to the rules of IDog. It's saying, "Regardless of how I digest my food and whether or not I like it, you'll always be able to feed me via my feed method. I reserve the right to change how feed is implemented at any time, but I won't change the method name, the parameters it takes in, or what it returns. And, as a user, that's all you should care about."

= an interface is a promise =

I remember when I first read that an interface is "a kind of promise." I was confused. What happens if I break the promise? If it's just a promise, can't I just promise not to change method names or alter their kind and number of parameters? Sure, I can, but there's nothing to stop me if I break my promise. On the other hand, if I type in my code that Dog "implements IDog," I'll get a compile error if I don't keep my promise. For example, if I change Dog's feed method to this:


public function feed( foodType : String, calories : int ) : void
{
 blah blah blah...
}

My code won't compile, because IDog says it should look like this:


public function feed( foodType : String, calories : int ) : void
{
 function feed( food : Food ) : void;
}

And, in a good IDE (e.g. Flex Builder -- a.k.a. Flash Builder -- or FDT), I won't have to wait until compile time. Most IDEs tell you if you're not following an interface as you type your code.

So a real nuts-and-bolts reason to use interfaces is that they catch errors before the errors happen!

By the way, this doesn't mean that I can't change interfaces. I can. If I want to change the feed() method, I can go into IDog and redefine it. As with all aspects of code, interfaces evolve over time. The good news is that when you make changes to an interface, you get advanced warning about problems you might be causing. You can fix those problems before they rear their heads.

= advanced interface tricks =

Once you get the hang of interfaces, there are some useful advanced features worth using. For instance, interfaces can inherit from other interfaces:


public interface IMachine
{
 function turnOn() : void;
 function turnOff() : void;
}

public interface ITransporter extends IMachine
{
  function beamUp( person : Person ) : void;
 function beamDown( person: Person ) : void;
}

And classes can implement multiple interfaces:


public interface IKillable
{
 function stabMe() : void;
 function shootMe() : void;
}

public interface ITameable
{
 function petMe() : void;
 function feedMe() : void;
}

public class Shark extends Creature implements IKillable { ... }
public class Demon extends SupernaturalBeing implements ITamebale { ... }
public class Wolf extends Creature implents IKillable, ITameable { ... }

Note: it's another convention it name intefances I-something-able.

= interfaces can be used as types =

Coolest of all, you can type variables to interfaces instead of implementations. For instance "var dog : IDog" instead of "var dog : Dog". Here's a more complete example:


public interface IOpenable
{
 function open() : void
}

public class Box implements IOpenable
{
 public function open() : void { trace( "There's money inside!!!" ); }
}

public class Skull implements IOpenable
{
 public function open() : void { trace( "There's a brain inside!!!" ); }
}

public class Door implements IOpenable
{
 public function open() : void { trace( "Nothing to fear. Come on in!" ); }
}

public class DocumentClass
{
 //notice how I typed the variable aThing
 private function openAThing( aThing : IOpenable) : void
 {
  aThing.open();
 }
 
 //constructor
 public function DocumentClass() 
 {
  var box : Box = new Box();
  var skull : Skull = new Skull();
  var door : Door = new Door();
  
  openAThing( box ); //There's money inside!!!
  openAThing( skull ); //There's a brain inside!!!
  openAThing( door ); //Nothing to fear. Come on in!
 }
}

The magic here is that box, skull and door are three totally unrelated classes. They aren't children of the same base class. But they all share the same interface. So as long as you type a variable to IOpenable, that variable can store any of those classes.

= start your projects with interfaces =

Creating interfaces is a great way to start a project (you'll refine those interfaces as you go). If all you have at the beginning is interfaces, what else can you do except "program to interfaces"?

A great way to think about an Object Oriented system is as a bunch of things all talking to each other, pushing each other, pulling each other, etc. As such, each of these things can only interact with another thing through its interface. So you don't need to know anything about implementation details in order to describe the whole system. You just need to know the public face of each thing.

As an example, lets say that I'm making a Pacman game. I know nothing (yet) about how the objects will work, but I know that I'll need a maze, some dots (for the Pacman to eat), a Pacman and some ghosts to chase him and be chased by him. (To keep this example simple, I'll ignore other details, such as scores, lives and levels).

Opening my editor, I'll make a first draft at the interfaces:


public interface IPackman
{
 function move( direction : String ) : void;
 function eatDot() : void;
 function eatGhost() : void;
 function render() : void;
}

public interface IGhost
{
 function move( direction : String ) : void;
 function eatPackman() : void;
 function avoidPackman() : void;
 function returnToBase() : void;
 function render() : void;
}

public interface IMaze
{
 function render() : void;
}

public interface IDot
{
 function render() : void;
}

== draft two ==

Looking over my initial draft, I notice that both Packmen and Ghosts can move and eat. And everything seems to be renderable, which makes sense in a visual system. So I redraft my interfaces to group similar methods together:


public interface IRenderable
{
 function render() : void;
}

public interface IMovable
{
 function move( direction : String ) : void;
}

public interface IEater
{
 function eat( food : IEdibleObject ) : void;
}

When I later define my classes, they will all implement IRenderable. Packman and Ghost will both implement IMovable and IEater.

Notice the reference to IEdibleObject inside IEater's eat method. I need to define that, too:


public interface IEdibleObject
{

}

= empty interfaces =

Sometimes I create empty interfaces. At this point in development, all I know is that a bunch of different kinds of things -- packmen, ghosts and dots -- are all edible. I'm not sure if editable object will need to implement any common methods. And maybe they should all be descended from a base class instead of (or in addition to) implementing a common interface. But at this point, the empty interface serves to remind me that this is a sensible way to group certain objects. If I later decide to add a digestMe() method inside IEdibleObject, my IDE will remind me that I need to implement in this in all classes that are implementing it.

To wrap thing up (for now), I'll add the following definitions to my list of interfaces, though I expect I'll make more drafts when I start working on implementation:


public interface IEnemy
{
 function returnToBase() : void;
 function avoid( target : IGamepiece ) : void
}

//for dots, packmen, ghosts, etc. Do I need this AND IEdible?
public interface IGamepiece
{

}

= interfaces and class inheritance =

Sometimes I wind up using both interfaces and class inheritance. This happens when I want a whole family of classes to implement an interface in the same way:


//this class will never be instantiated as an object, 
//which is why I have named it starting with the prefix "Abstract"
public class AbstractCreature implements IMoveable, IRenderable, IGamepiece
{
 public static var STEP : int = 50;

 //IRenderable forces me to include this method
 public function render() : void
 {
  //override in subclasses
 }
 
 //IMovable forces me to include this method
 public function move( direction : String ) : void
 {
  if ( direction == "up" ) this.y += STEP;
  else if ( direction == "down" ) this.y -= STEP;
  else if ( direction == "left" ) this.x -= STEP;
  else if ( direction == "right" ) this.x += STEP;
  //note: I'm not suggesting that this is how you'd
  //animate a packman or ghost in real life.
 }
}

public class Packman extends AbstractCreature
{
 override public function render() : void
 {
  drawCircle();
  cutPieSliceOutOfCircle();
  animateMouthOpeningAndClosing();
 }
 
 private function drawCircle() { ... };
 private function cutPieSliceOutOfCirce{ ... };
 privare function animateMouthOpeningAndClosing{ ... };
}

public class Ghost extends AbstractCreature
{
 override public function render() : void
 {
  drawBody();
  drawEyes();
 }
 
 private function drawBody() { ... };
 private function drawEyes() { ... };
}

I don't have to explicitly state that Packman and Ghost extend the interfaces IMovable and IRenderable, because they inherit that fact from their parent, AbstractCreature. All these classes also implement my empty (for now) IGamepiece interface -- just in case!

Note that the subclasses are free to implement additional interfaces that aren't implemented by AbstractCreature. For instance, if I have an interface called IPlayerCharacter (for the character played by the actual player of the game, as opposed to the AI ghosts), I could have my Packman subclass extend that.

= interfaces, me and Tim =

My relationship with interfaces has gone through three stages: at first I was baffled by them, then I got into them, and now I'm REALLY into them. For my third and current phase ("REALLY into them"), I have my friend Tim to thank. Tim, a seasoned programmer who has worked for Microsoft and programmed in many languages, makes interfaces for (almost) all his classes. Though I loved interfaces before I started talking to Tim about them, my immediate reaction to Tim's process was that he was taking a good thing too far. But the more I thought about it, the more I was unable to come up with an objection to Tim's way of working. If a class doesn't have a formal interface, then all its public methods are mashing up their interfaces with their implementations. That's messy and dangerous. So now I'm born again into the church of Tim.

Tim's idea is a bit revolutionary in Actionscript circles, but it's the norm in some other programming communities and languages. For instance, in Objective-C (a suddenly popular language, since one must use for iPhone development), all classes must have separate interface files. Unfortunately, since Actionscript doesn't force you to use interfaces, many of developers don't bother.

Not every one of my classes (or Tim's) implements an interface unique to itself. In many cases, large groups of classes all implement a single interface. Interfaces are, among other things, a great way of finding and expressing commonality. "I didn't think these classes had anything in common, but now I can see that they all render graphics. I'm going to make an interface called IRenderable and make them all implement it. Later, I can make a grand render-function that takes an array of IRenderable objects, loops through them and calls each of their render() methods!"

= when not to use interfaces =

Like Tim, I don't bother making interfaces for Value-Object classes (a.k.a Data Transfer Objects). If a class is just a collection of public properties...


public class ContactVO
{
 public firstName : String;
 public lastName : String;
 public email : String;
 pubic phone : String;
}

... then there's not much of point to making an interface for it. I also don't make interfaces for utility classes, which are generally collections of static methods. I don't really think of such classes as classes. In their cases, "class" is just a cheap and easy way to group together a library of helper functions.

But if something is an object that relates to other objects, it needs an interface. And since virtually everything in an OOP world is an object that relates to other objects, virtually everything in that world should have an interface.

a little lesson in refactoring

2009-07-24T13:54:00.000-07:00

Here's a secret you already know: great writers revise. I learned more about writing by looking at an early draft of George Orwell's "1984" than I did in any writing class. Orwell's prose seems so effortless. Yet its simplicity belies all the sweat he poured into it. Every page of his draft is riddled with multiple edits, cross-outs and revisions.

Here's a secret you may not know: good programmers revise. When they get their program working, they know they've only begun their labor. The program is finished when it's easy for humans to read.

Since I learned so much from looking over Orwell's shoulder, I wish I could do the same with lots of programmers, watching them refactor their work to make it clear.

Unfortunately, most programming books omit this step. They either show you rough code that cries out for refactoring. Or they show you clean code that looks like it sprung into existence that way.

When I first started programming, I wondered why my code never looked as good as examples in books. What I didn't realize is that the book examples were the end result of a hidden process, one that involved many drafts and revisions.

So that you don't suffer the same confusion I did, I'm going to show you my revision process, starting with some very rough code I actually wrote. If you enjoy this process and want to learn more, I recommend the following books:

- "Clean Code" by Robert C. Martin.

- "Refactoring" by Martin Fowler and others.

- "Code Complete" by Steve McConnell.

I'm not going to demo a complex piece of code. I'm going to show you the sort of thing you've probably written a hundred times: code to draw a rectangle.

Going into my project, I knew I'd have to draw a bunch of rectangles for various background elements and buttons. I knew that some of them would have both fills and strokes, others would have just fills, and still others would have just strokes. The ones with strokes would have various stroke widths.

I decided to make a CustomRectangle class that allowed for all of these variations. Here's my first attempt at the class header and its constructor:


import flash.display.Sprite;
import com.grumblebee.enums.Colors;

public class CustomRectangle extends Sprite
{
 private var _displayWidth : Number;
 private var _displayHeight : Number;
 private var _fillColor : uint;
 private var _strokeColor : uint;
 private var _strokeWidth : Number;

 public function CustomRectangle( displayWidth : Number = 0,
          displayHeight : Number = 0,
          fillColor : uint = Colors.NO_COLOR,
          strokeColor : uint = Colors.NO_COLOR
          strokeWidth : Number = 1 )
 {
  _displayWidth = displayWidth;
  _displayHeight = displayHeight;
  _fillColor = fillColor;
  _strokeColor = strokeColor;
  _strokeWidth = strokeWidth;
 
  render();
 }
 
 private function render() { ... }
}

You may be wondering about Colors.NO_COLOR. Since I'm using uints to store colors, I need a way to un-set a color value. ints and uints default to zero, and in the hex-color system, zero is black (0x000000). ints and uints can't be set to undefined or null, so where does that leave me? How can I say "there's no fill color?"

It leaves me with uint.MAX_VALUE. uint.MAX_VALUE is a built-in constant that holds the largest number your system can store in a unit (int has both MAX_VALUE and MIN_VALUE constants).

MAX_VALUE might resolve to a different number on different OSes. Out of curiosity, I decided to trace( uint.MAX_VALUE ) on my Mac. As it happens, my Mac's MAX_VALUE for uints is 4,294,967,295. That's way larger than the largest color-value, which is 0xFFFFFF or 16,777,215. (Though it's NOT larger than 0xFFFFFFFF, so if you're using alpha+color hex numbers, you need a different solution!)

So I decided that a "color value" of uint.MAX_VALUE equals no color. To make my code a bit more readable, I created an enum class for colors:


public class Colors
{
 public static const NO_COLOR : uint = uint.MAX_VALUE;
}

Getting back to my CustomRectangle class, I now needed to define the render method:


private function render() : void
{
 if ( _strokeColor != Colors.NO_COLOR && _fillColor != Colors.NO_COLOR )
 {
  if ( _strokeColor != Colors.NO_COLOR ) 
   graphics.lineStyle( _strokeWidth, _strokeColor );
   
  if ( _fillColor != Colors.NO_COLOR )
   graphics.beginFill( _fillColor );
   
  graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
  graphics.endFill();
 }
}

That's not terrible code by any means, but it doesn't pass the Headache Test (HT). To give your code the HT, unfocus your eyes slightly and look at it. If you see a mess of stuff in parenthesis and multiple levels of nesting, your code fails the HT. Don't feel bad. Most first-draft code fails.

My code is not all that hard to figure out. But a future reader (e.g. me next week) doesn't want to waste his time trying to figure it out. He wants to just look at it and GET it! So let's help him out.

First, let's rector the outer-most conditional. Any time you see && or ||, a refactoring bell should go off in your head. Why? Because multiple conditions are headache inducing. They are even that way in English. Compare...

"I'll take you to the zoo if it's not raining tomorrow and if the temperature is above 50 degrees."

... with ...

"I'll take you to the zoo tomorrow if it's a nice day."

Along these lines, we'll refactor the code as follows:


private function render() : void
{
 if ( isRenderable() )
 {
  ...
 }
}

And we'll move the ugly conditional into it's own helper method:


private function isRenderable() : Boolean
{
 if ( _strokeColor != Colors.NO_COLOR && _fillColor != Colors.NO_COLOR )
     return true;
 return false;
}

In case you didn't know, you don't have to wrap the second return statement in an else clause. Return statements always cause their methods to end immediately, so if the "return true" executes, the "return false" will never run.

You might argue that we didn't really simplify the compound-if statement. We just moved it. I agree, and sometimes that's the best you can do. At least we've burried the ugly code. Readers who don't want a headache can just read as far as the call to isRenderable().

But we can do better: let's refactor the two clauses of the compound if into two separate methods:


private function isRenderable() : Boolean
{
 if ( hasStroke() || hasFill() ) return true;
 return false;
}

private function hasStroke() : Boolean
{
 if ( _strokeColor != Colors.NO_COLOR ) return true;
 return false;
}

private function hasFill() : Boolean
{
 if ( _fillColor != Colors.NO_COLOR ) return true;
 return false;
}

Though we just wrote hasFill() and hasStroke() to simplify the isRenderable() method, it now looks like they can do double-duty and also help us simplify render(). Let's change this...


private function render() : void
{
 if ( isRenderable() )
 {
  if ( _strokeColor != Colors.NO_COLOR ) 
   graphics.lineStyle( _strokeWidth, _strokeColor );
   
  if ( _fillColor != Colors.NO_COLOR )
   graphics.beginFill( _fillColor );
   
  graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
  graphics.endFill();
 }
}

... to this ...


private function render() : void
{
 if ( isRenderable() )
 {
  if ( hasStroke() ) 
   graphics.lineStyle( _strokeWidth, _strokeColor );
   
  if ( hasFill() )
   graphics.beginFill( _fillColor );
   
  graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
  graphics.endFill();
 }
}

... which I hope you'll agree is less of a headache to read. But I still think we can do better. Let's define two more helper methods:


private function setFill() : void
{
 graphics.beginFill( _fillColor );
}

private function setStroke() : void
{
 graphics.lineStyle( _strokeWidth, _strokeColor );
}

With these puppies available, we can refactor is render to this:


private function render() : void
{
 if ( isRenderable() )
 {
  if ( hasStroke() ) setStroke();
   
  if ( hasFill() ) setFill();
   
  graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
  graphics.endFill();
 }
}

One last migrane: the nested ifs. Is there any way we can make this method have only one level of nesting? Sure there is!


private function render() : void
{
 if ( ! isRenderable() ) return;

 if ( hasStroke() ) setStroke();
  
 if ( hasFill() ) setFill();
  
 graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
 graphics.endFill();
}

Now THAT passes the Headache Test!

Remember, a return instantly cause the method to end. So if the rectangle is not renderable, the code after the first if won't even run.

Which leaves us with one last headache: the constructor.


public function CustomRectangle( displayWidth : Number = 0,
         displayHeight : Number = 0,
         fillColor : uint = Colors.NO_COLOR,
         strokeColor : uint = Colors.NO_COLOR
         strokeWidth : Number = 1 )
{
 _displayWidth = displayWidth;
 _displayHeight = displayHeight;
 _fillColor = fillColor;
 _strokeColor = strokeColor;
 _strokeWidth = strokeWidth;

 render();
}

My problem with this is that it has a big parameter list. Looking at that list makes my head spin a little. I'd like the reader to know that that method expects render data and leave it at that. If the reader wants to know more, he can drill down farther. If he doesn't care, he can ignore the details.

One way to deal with classes that need a lot of set-up data is to make a bunch of little setter methods:


public function CustomRectangle() { }
public function set displayWidth ( value : Number ) { _displayWidth = value; }
public function set displayHeight ( value : Number ) { _displayHeight = value; }

...

public function render() : void { ... }

My problem with this is that it's really hard to tell what you need to do to set up the class and what you is optional. Is it okay to do this?


var rect : CustomRectangle = new CustomRectangle();
rect.displayWidth = 100;
render();

Will this class blow up because I didn't set displayHeight or any of the other properties? Do I have to set them all? Does it matter what order I set them in? The nice thing about variables that get set via constructor calls is that there's no ambiguity. If you forget one, the compiler will yell at you. But this can lead to parameter bloat, as we saw above.

The solution is to create a new object, a Value Object (a.k.a Data Transfer Object) and pass that to the constructor:


public class RenderData
{
 public var displayWidth = 0;
 public var displayHeight = 0;
 public var fillColor : uint = Colors.NO_COLOR;
 public var strokeColor : uint = Colors.NO_COLOR;
 public var strokeWidth : Number = 1;
}

We can now refactor our constructor to this:


public function CustomRectangle( renderData : RenderData )
{
 _displayWidth = renderData.displayWidth;
 _displayHeight = renderData.displayHeight;
 _fillColor = renderData.fillColor;
 _strokeColor = renderData.strokeColor;
 _strokeWidth = renderData.strokeWidth;

 render();
}

Or, if we want, we can organize this way:


public function CustomRectangle( renderData : RenderData )
{
 initWith( renderData );
 
 render();
}

private function initWith( renderData : RenderData ) : void
{
 _displayWidth = renderData.displayWidth;
 _displayHeight = renderData.displayHeight;
 _fillColor = renderData.fillColor;
 _strokeColor = renderData.strokeColor;
 _strokeWidth = renderData.strokeWidth;
}

Ah, better than Rolaids and Bufferin combined!

Here's our final draft. Take a look at this in a month. I bet it will still be instantly clear to you how it works.


class Custom Rectangle extends Sprite
{
 public function CustomRectangle( renderData : RenderData )
 {
  initWith( renderData );

  render();
 }
 
 private function initWith( renderData : RenderData ) : void
 {
  _displayWidth = renderData.displayWidth;
  _displayHeight = renderData.displayHeight;
  _fillColor = renderData.fillColor;
  _strokeColor = renderData.strokeColor;
  _strokeWidth = renderData.strokeWidth;
 }
 
 private function render() : void
 {
  if ( ! isRenderable() ) return;
  
  if ( hasStroke() ) setStroke();

  if ( hasFill() ) setFill();

  graphics.drawRect( 0, 0, _displayWidth, _displayHeight );
  graphics.endFill();
 }
 
 private function setFill() : void
 {
  graphics.beginFill( _fillColor );
 }

 private function setStroke() : void
 {
  graphics.lineStyle( _strokeWidth, _strokeColor );
 }
 
 private function isRenderable() : Boolean
 {
  if ( hasStroke() || hasFill() ) return true;
  return false;
 }

 private function hasStroke() : Boolean
 {
  if ( _strokeColor != Colors.NO_COLOR ) return true;
  return false;
 }

 private function hasFill() : Boolean
 {
  if ( _fillColor != Colors.NO_COLOR ) return true;
  return false;
 }
}

the dictionary is mightier than the associative array

2009-07-21T11:11:00.000-07:00

Developers tend to overlook (or not know about) Dictionaries. In AS 3.0, a Dictionary is similar to an associative array, except it takes objects as keys instead of Strings. Compare this use of an associative array ...


var pointsForHittingEnemies : Array = new Array();
pointsForHittingEnemies[ "dracula" ] = 100; 
pointsForHittingEnemies[ "mummy" ] = 50; 
pointsForHittingEnemies[ "frankenstein" ] = 25;

... with this use of a Dictionary ...


import flash.utils.Dictionary;

var dracula : Monster = new Monster();
var mummy : Monster = new Monster();
var frankenstein : Monster = new Monster();

var pointsForHittingEnemies : Dictionary = new Dictionary();
pointsForHittingEnemies[ dracula ] = 100; 
pointsForHittingEnemies[ mummy ] = 50; 
pointsForHittingEnemies[ frankenstein ] = 25;

In the second example, note the lack of quotation marks around dracula, mummy and frankenstein. The indices to the Dictionary version of pointForHittingEnemies are objects, not Strings as in the Array version.

Dictionaries are really useful when you need to associate random bits of data with objects. The way this often rears its head for me is when I want to associate random data with a Sprite.

Let's say I am making a playlist of videos. I want a button for each video on the list. The buttons will be Sprites, but how do I associate a Sprite with a particular video, so when the user clicks that Sprite, the associated video will play?

Here's one solution:


import flash.utils.Dictionary;
import flash.display.Sprite;
import flash.events.MouseEvent;

var videos : Array = ["TheGodfather.flv", "2001.flv","GoneWithTheWind.flv"];
var buttonList : Dictionary;

init();

function init() : void
{ 
 var buttonList = new Dictionary();
 var totalVideos : int = videos.length;
 for ( var i : int = 0; i < totalVideos; i++ ) makeButton( i );
}

function makeButtons( index : int ) : void
{
 var button : Sprite = new Sprite();
 button.buttonMode = true;
 button.x = index * 100; //to space buttons out across stage
 
 //add the button to the Dictionary
 //as a key to the video's index
 buttonList[ button ] = index;
 
 //draws stuff on the button (function definition not shown)
 renderButton( button );
 
 addChild( button );
 
 //take a look at the callback function
 //to see how I use the Dictionary
 button.addEventListener( MouseEvent.CLICK, buttonClickCallback );
}

function buttonClickCallback( event : MouseEvent ) : void
{
 var button : Sprite = event.currentTarget as Sprite;
 
 //look up button in the Dictionary and get the
 //appropriate video index
 var index : int = buttonList[ button ];
 
 var videoUrl : String = videos[ index ];
 
 //call to a function that plays a video based on its URL.
 //function definition not shown
 playVideo( videoUrl ); 
}

Notes: instead of storing indices in my Dictionary, I could have stored the actual URLs of the videos:


buttonList[ button ] = videos[ index ];

In this case, I would have written the callback function as follows:


function buttonClickCallback( event : MouseEvent ) : void
{
 var button : Sprite = event.currentTarget as Sprite;
 
 //look up button in the Dictionary and get the
 //appropriate video url
 var videoUrl : String = buttonList[ videoUrl ];
 
 //call to a function that plays a video based on its URL.
 //function definition not shown
 playVideo( videoUrl ); 
}

I like Dictionaries, because they're simple and powerful. However, I only use them for really quick-fix chores, usually when I'm prototyping something on the Timeline. A more robust solution for associating data with objects is the Class structure:


class VideoButton extends Sprite
{
 private var _videoUrl : String;
 
 public function get videoUrl() : String { return _videoUrl }
 public function set videoUrl( value : String ) : void
 {
  _videoUrl = value;
 }
}

Now, in my main document, import the VideoButton class and rewrite the makeButtons function as follows:


function makeButtons( index : int ) : void
{
 var button : VideoButton = new VideoButton();
 button.buttonMode = true;
 button.x = index * 100; //to space buttons out across stage
 
 //store the video's url right in the object itself
 button.videoUrl = videos[ index ];
 
 //draws stuff on the button (function definition not shown)
 renderButton( button );
 
 addChild( button );
 
 //take a look at the callback function
 //to see how I use the Dictionary
 button.addEventListener( MouseEvent.CLICK, buttonClickCallback );
}

And the callback will now look like this:


function buttonClickCallback( event : MouseEvent ) : void
{
 var button : VideoButton = event.currentTarget as VideoButton;
 
 //call to a function that plays a video based on its URL.
 //function definition not shown
 playVideo( button.videoUrl ); 
}

parameters suck

2009-07-17T08:41:00.000-07:00

I'm learning Objective-C, and I've come to love the way you make method calls in that language. If you'd type this in Actionscript...


shapes.arrow( 0xFF0000, 0x00FF00 )

... you'd type something like this in Objective-C:


[shapes arrowWithStrokeColor: 0xFF0000 andFillColor: 0x00FF00 ]

Though they are more verbose, Objective-C method calls make the purpose of their arguments clear.

With code, it's more important to cater to the reader than to the writer (who may wish to save himself some keystrokes.) Code gets read many more times than it gets written. If verbosity is the price we have to pay for readable code, it's time to start digging into our wallets.

I don't want to read shapes.arrow( 0xFF0000, 0x00FF00 ). I can guess that the two hex values are colors, but I don't know which is the fill color and which is the stroke color. To find out, I have to search for the method definition, which is probably in a different file from the one I'm looking at. That slows me down and makes me think about file-navigation in my IDE, rather than about the meaning of the code.

Unfortunately, Actionscript doesn't give you an elegant solution to this problem, so most developers don't bother trying to solve it. But it's a serious problem, and there are ways to deal with it:

1) via comments:


// parameters: strokeColor, fillColor
shapes.arrow( 0xFF0000, 0x00FF00 )

This is a bad solution, because comments and the code they refer to can easily get out of sync. Say that you (or someone else) changes the definition of shapes.arrow() to...


public function arrow( fillColor : uint, strokeColor: uint ) : void { ... }

... but forgets to update the comment. It will now be an incorrect and misleading comment. This is an easy mistake to make, because the comment and the method definition are in different locations. You might make the update in one place and forget to make it in the other.

In general, I'm not a fan of comments. It's too easy to use them to explain messy code. It's much better to clean the code.

2) via descriptive-method names:


shapes.arrowWithStrokAndFillColor( 0xFF0000, 0x00FF00 )

This tends to stretch method names to the point that they get hard to read, and it get absurd if there are more than a couple of parameters:


shapes.arrowWithStrokeWidthAndStrokeColorAndFillColor( 1, 0xFF0000, 0x00FF00 );

However, in certain cases, when you refer to parameters in method names, it makes the code much easier to read. Compare...


find( name, names )

... with ...


findItemInList( name, names )

Of course, if you're using someone else's API, you don't have the luxury of naming their methods. In that case, I recommend...

3) via variables:

compare ...


shapes.arrow( 0xFF0000, 0x00FF00 )

... with ...


var strokeColor : uint = 0xFF0000;
var fillColor : uint = 0x00FF00;

shapes.arrow( fillCollor, strokeColor );

This is my favorite solution, because it uses code as commentary. Self-commenting code is always better than obscure code with comments.

Bottom line: when you find yourself typing something like move( object, 1, 5, false, [10,10] ), think about what you can do to make your code readable. You may not have written the move() function, but you did write the call to it. It's your responsibility to use whatever structures exist in your language to make that call clear.

to block or not to block

2009-07-17T07:37:00.001-07:00

"Best practices" documents tell me to always follow an if, while or for statements with a block of code. They suggest I should type this...


if ( missileHitAlienShip() )
{
 score += 100;
}

...and never this...


if ( missileHitAlienShip() ) score += 100;

I disagree. I find the latter version much easier to read. If you translate the two versions into English, you get "if a missile hits the alien ship, do the following: raise the player's score by 100" and "if a missile hits the alien ship, raise the player's score by 100." I prefer the second version.

When I present them by themselves, the two versions don't look that different, and the block version isn't all that difficult to read. But when a bunch of blocks are nested inside one another, The code quickly gets difficult to read. Conditional logic gets all mixed up with nitty-gritty implementation details. Compare...


function addToScores() : void
{
 if ( levelNumber > 10 )
 {
  bonus += 500; 
 }
 
 for ( var i : int = 0; i < numPlayers; i++ )
 {
  player[ i ].score += bonus;
 }
}

... with ...


function addToScores() : void
{
 if ( levelNumber > 10 ) bonus += 500;
 
 for ( var i : int = 0; i < numPlayers; i++ )
   player[ i ].score += bonus;
}

The "best practices" docs say that you should use blocks because they allow you to easily switch from a single statement to multiple statements. For instance, if I start with something like this...


function addNewAlienShip() : void
{
 var ship : AlienShip = new AllienShip();
 
 if ( shipsHaveWarpDrive ) ship.x = Math.random() * universe.width;
 else ship.x = alienBase.x; 
}

... and later realize I need to also set y-coordinates, I'll need to change my code to something like this:


function addNewAlienShip() : void
{
 var ship : AlienShip = new AllienShip();
 
 if ( shipsHaveWarpDrive ) 
 {
  ship.x = Math.random() * universe.width;
  ship.y = Math.random() * universe.height;
 }
 else 
 {
  ship.x = alienBase.x;
  ship.y = alienBase.y;
 }
}

Since I never know how many statements I'll have to add after an if, I might as well start with a block -- as a sort of template -- even if I initially only intend to follow the if with one statement. Or so the "best practices" logic goes.

I disagree. I'm not a fan of blocks, because they encourage multiple levels of nesting and make methods overly long and hard to read. Given the example above, which may be my initial draft, I'd refactor it as...


function addNewAlienShip() : void
{
 var ship : AlienShip = new AllienShip();
 
 if ( shipsHaveWarpDrive ) putInRandomLocation( ship );
 else putInBase( ship );
} 

function putInRandomLocation( ship : AlienShip ) : void
{
 ship.x = Math.random() * universe.width;
 ship.y = Math.random() * universe.height;
}

function putInBase( ship: AlienShip ) : void
{
 ship.x = alienBase.x;
 ship.y = alienBase.y;
}

This is easier to read and modular. If I ever want to change the way warp drives place ships, I'll have an easy time doing so without searching through levels of nesting.

I am not dogmatic about forbidding blocks. If a block seems like a simple and clean solution, I use it. But I initially follow my ifs, whiles and fors with a single statement. If I later realize that I need to add more statements, I make a decision. I sometimes replace the single statement with a block. More often, I turn the single statement into a function call, as I did in the example above.

A couple of years ago, I turned a major corner in my life as a coder: I started taking three maxims seriously:

1) each function should do one thing.
2) functions should be as short as possible.
3) nested block are evil.

Previously, I'd given lip-service to these ideas, but when I started following them religiously, my code got way easier to read and maintain.

I have found simplicity on the method level to be more important than simplicity on the class level. Since OOP texts mostly focus on classes, many programmers pay more attention to them than to methods. That's like paying more attention to chapters than to sentences. Good writers know that the sentence is where the real work happens. A well organized table of contents is worthless if each chapter is full of non-sensical sentences.

Again, I am not dogmatic about my three rules, and I often can't follow them when making an initial draft. But when I refactor, I take a close look at any method that is longer than five or six statements. And I take an even closer look at blocks. My goal is to write a group of simple, short functions that each works as one little cog in my big machine.

the zen of curly braces

2009-07-13T08:58:00.001-07:00

As one of the unwashed millions who hopes to make his fame and fortune as an iPhone developer, I've been learning Objective-C. My main teacher has been "Programming in Objective-C 2.0" by Stephen Kochan, a book which deserves its accolades.

At some point, Kochan says something like, "In general, you can substitute a block of code for a single statement." I thought about that for a second and realized that, simple as that sounds, I'd never really thought about it before.

Of course, I know that you can -- in all the c-family languages -- write...


if ( condition ) statement;


if ( condition )
{
 block;
 of;
 statements;
}

... but I hadn't considered statement/block substitution as a general rule.

To test things out, I tried this timeline code in an AS3.0 fla:


{
 var a : int = 3;
 trace( a );
}

{
 for ( var i : int = 0; i < 10; i++ ) trace( i );
}

{}

And it worked!

Now, it's not that I think this is useful. I don't. But I love it when I can generalize some specific behaviors into a principle. When this code worked, I felt some contents drifting together. I suddenly understood a bit of Actionscript grammar that I'd never really considered before.

Actually, I can think of a use for this: refactoring. Say that as a first draft, you write a method like this:


public function init() : void
{
 drawBackground();
 drawPlayer();
 drawEnemies();
 setPlayerLives();
 setPlayerStartingPosition();
 drawPlayerShip();
 setEnemyStaringPositions();
 setEnemyStrength();
 setPlayerStrength();
 startGame();
}

Your first step in refactoring could be to group statements into blocks:


public function init() : void
{
 {
  drawBackground();
  drawPlayer();
  drawEnemies();
 }
 
 {
  setPlayerLives();
  setPlayerStartingPosition();
 }
 
 {
  drawPlayerShip();
 }
 
 {
  setEnemyStaringPositions();
 }
 
 {
  setEnemyStrength();
  setPlayerStrength();
 }
 
 startGame();
}

I like this, because it suggests groupings without affecting functionality. init should run exactly the way it did before you added the blocks.

Having added them, you can see some better ways of organizing the statements:


public function init() : void
{
 {
  drawBackground();
  drawPlayer();
  drawEnemies();
  drawPlayerShip();
 }
 
 {
  setPlayerLives();
  setPlayerStartingPosition();
  setPlayerStrength();
 }
 
 {
  setEnemyStaringPositions();
  setEnemyStrength();
 }
 
 startGame();
}

This, with a little cutting and pasting, leads naturally to...


public function init() : void
{
 renderGamePieces();
 initPlayer();
 initEnemies();
 startGame();
}

private function renderGamePieces() : void 
{
 drawBackground();
 drawPlayer();
 drawEnemies();
 drawPlayerShip();
}

private function initPlayer() : void
{
 setPlayerLives();
 setPlayerStartingPosition();
 setPlayerStrength();
}

private function initEnemies() : void
{
 setEnemyStaringPositions();
 setEnemyStrength();
}

incidentally, going back to my original example...


{
 var a : int = 3;
 trace( a );
}

{
 for ( var i : int = 0; i < 10; i++ ) trace( i );
}

{}

... I found that double nesting works, too:


{
 {
  var a : int = 3;
  trace( a );
 }

 {
  for ( var i : int = 0; i < 10; i++ ) trace( i );
 }

 {}
}

As does triple nesting:


{
 {
  {
   var a : int = 3;
   trace( a );
  }

  {
   for ( var i : int = 0; i < 10; i++ ) trace( i );
  }

  {}
 }
}

And so on.

Strangely, this doesn't work:


{
 var a : int = 3;
 trace( a );
}

{
 for ( var i : int = 0; i < 10; i++ ) trace( i );
}

{};

The problem here is the semi-colon after the final close-brace. It throws this error:

Syntax error: extra characters found after end of program.

I got the same error when I added an empty block to the start of the frame code:


{}

{
 var a : int = 3;
 trace( a );
}

{
 for ( var i : int = 0; i < 10; i++ ) trace( i );
}

And I also got it when I added an empty block in the middle of the code:


{
 var a : int = 3;
 trace( a );
}

{}

{
 for ( var i : int = 0; i < 10; i++ ) trace( i );
}

For some reason (that I don't understand), the AS interpreter assumes it's reached the end of your code when it finds an empty set of braces. The empty set doesn't cause an error on its own, but you will get an error if there are any characters following the the close-brace. This isn't a problem, since I can't think of a reason to ever include an empty block. But I am curious about what's going on.

Dumb mistakes.

2009-07-08T14:14:00.001-07:00

Here are a couple of mistakes I make after a long day of coding. Can you spot the errors?

1. Stack Overflow


public class Person
{
 private var _name : String;
 
 public function get name() : String
 {
  if ( name == null ) name = "anonymous";
  return _name;
 }
 
 public function set name( value : String ) { _name = value };
}

The problem: run this code and you'll get an output panel full of "stack overflow" errors. Why? Well, take a closer look at the getter method. It's supposed to return the value of private member "_name". But the first statement in the method refers to "name," not "_name" (note the underscore). _name is the private member; name is the getter method.

When the first statement executes, it tests to see if THE OUTPUT OF THE GETTER METHOD ITSELF is equal to null. Remember, when you type the name of a getter method by itself, you're really just using a syntactic sugar. "name" is really "name()." So what I'm doing in the first statement is similar to this:


 function foo() : Number
 {
  if ( foo() == null ) trace( "x is equal to null" );
 }

The call foo() in the first statement calls the function foo, which has a call to foo in the first statement, which calls foo... and so on. An infinite recursive loop.

In the previous example, I can remove the loop by simply adding underscores to "name":

bad: if ( name == null ) name = "anonymous";
good: if ( _name == null ) _name = "anonymous";

Now name is not calling itself; it's referring to a private member called _name.

2. Null Envy


var herName : String;
var flower : Sprite;
var sheLovesMe : Boolean;
var herAge : Number;
var kisses : int;

if ( herName == null ) herName = "Lisa"; //works like a charm

if ( flower == null ) flower = new Sprite(); //works like a charm

if ( sheLovesMe == null ) sheLovesMe = false; //error

if ( herAge == null ) herAge = 18; //error

if ( kisses == null ) kisses = 0; //error

The problem here is that Booleans and numbers types can NEVER be set to null. They don't accept null as a value; nor can they be compared to null.

Once you define a Boolean, it is automatically set to false. (You can later change its value to true.) There's no such thing as a Boolean with no value, though you can set a Boolean to undefined.


var iLikeCheese : Boolean; //note: not explicitly set to a value
trace( iLikeCheese ); //false

You also can't set or compare a Number to null. Unset numbers are set by default to NaN, which is short for "not a number." However, you can't do this:

if ( herAge == NaN ) herAge = 18; //error

Instead, you have to do this:

if ( isNaN( herAge) ) herAge = 18; //works like a charm

ints and uints default to zero. If I'm using an int as a uint -- in other words, if my int should never be set to a negative number -- I sometimes set it to negative one by default. For instance, you can't give a girl a negative kiss, so...


public static const NOT_SET : int = -1;

var kisses : int = NOT_SET;

if ( kisses == NOT_SET ) kisses = 10;

For this reason, I often use ints to store hex-color values. How else should I indicated no color? After all, zero is black. I suppose I could use a uint and define something like this:


public const NO_COLOR : uint = uint.MAX_VALUE; //MAX_VALUE is a built-in constant

var favoriteColor : uint = NO_COLOR; 

if ( favoriteColor == NO_COLOR ) favoriteColor = 0xFF0000;

This solution is probably good enough for most simple circumstances, but if I need something more robust and scalable, I create a class:


public class Color
{
 public static const NO_COLOR : uint = uint.MAX_VALUE;
 private var _color : uint = Color.NO_COLOR;
 
 public function get color() : uint { return _color; }
 public function set color( value : uint ) { _color = value; }
 public function isSet() : Boolean { return _color == Color.NO_COLOR; }
}

looping through a class's static members

2009-07-08T09:48:00.000-07:00

How do you loop through all static members of a class?

First of all, why would you want to do that? Well, let's say you're writing a game in which the player can move in the four classic compass directions:


public class Directions
{
 public static const NORTH : String = "north";
 public static const SOUTH : String = "south";
 public static const EAST : String = "east";
 public static const WEST : String = "west";
}

Somewhere in your game, you have a moveInDirection() method that accepts a direction. But you want to make sure it doesn't try to move the player in illegal directions, e.g. moveInDirection("up"); The IDE should prevent this, because if you type moveInDirection(Directions.UP) you'll get an error (because there's no UP constant).

However, I'd like to make moveInDirection a bit more idiot proof than having it rely on the IDE. Also, it's possible that directions may be chosen at run time. For instance, a player might type a direction in a textfield, as in a text-adventure game. What if the player types "up"?

So I'd like moveInDirection() to check if the player is trying to make a legal move...


function movieInDirection( direction : String ) : void
{
 if ( isLegal( direction ) )
 {
  ...
 }
}

The question is, how should isLegal() work? The last thing I want to do is to use a bunch of conditionals or an Array...


function isLegal( direction : String ) : Boolean
{
 var legal : Array = [ "north", "south", "east", "west" ];
 
 for each ( var legalDirection : String in legal )
 {
   if ( direction == legalDirection ) return true;
 }
 
 return false;
}

That's a terrible solution, because it couples the class Directions to the Array in my isLegal function. Scaling will be dangerous. For instance, what if I add a new constant to Directions...

public static const INSIDE : String = "inside";

... but forget to add it to the Array?

var legal : Array = [ "north", "south", "east", "west" ]; //Oops! Forgot to add "inside"

A better solution is to loop through all the constants in Directions and check if the player's attempted direction exists. But how do you loop through all the static members of a class? After playing around with arcane solutions involving prototype chains, I settled on using the little-known describeType() function. It's in the flash.utils class, and you import it like this:

import flash.utils.describeType;

If you feed describleType() the Directions class -- trace( describeType( Directions) ) -- it outputs an XML description of the class:


<type name="Directions" base="Class" isDynamic="true" isFinal="true" isStatic="true">
  <extendsClass type="Class"/>
  <extendsClass type="Object"/>
  <constant name="WEST" type="String"/>
  <constant name="NORTH" type="String"/>
  <constant name="EAST" type="String"/>
  <constant name="SOUTH" type="String"/>
  <accessor name="prototype" access="readonly" type="*" declaredBy="Class"/>
  <factory type="Directions">
    <extendsClass type="Enum"/>
    <extendsClass type="Object"/>
  </factory>
</type>

It's then a fairly easy matter to parse the xml, extract all the constants, and test them against the player's choice. I packaged the solution in a utility class:


package com.grumblebee.constants 
{

import flash.utils.describeType;    

  public class Utilities 
  {
     public static function isLegal( enumClass : Class, value : String ) : Boolean
     {
        var xml : XML = describeType( enumClass );
        var xmlList : XMLList = xml.child( "constant" );
        var enumName : String;
      
        for each ( var child : XML in xmlList )
        {
          enumName = child.attribute( "name" ).toString();
          if ( enumClass[ enumName ] == value ) return true;
        }
   
        return false;
     }
     
  }
}

I can't shake the feeling that there's a better way to do this. I'd love to lose the XML parsing. But this is the best I can come up with for the moment. One thing I could do is transform the player's string to upper-case and test it directly to see if there's such a constant in Directions:

if ( Directions[ playerString.toUpperCase() ] != undefined ) ...

But that only works if I stick to the convention of NORTH = "north". It fails if Directions looks like this:


public class Directions
{
 public static const NORTH : String = "n";
 public static const SOUTH : String = "s";
 public static const EAST : String = "e";
 public static const WEST : String = "w";
}

it would also fail in the case of...

public static const UNDER_THE_BRIDGE : String = "under the bridge";

At one point, I thought about adding the isLegal() function to Directions. You can get a class to refer to its own static constants this way:

trace( prototype.constructor[ "NORTH" ] ); //north

Sadly, though prototype.constructor allows you to access individual class variables and constants, for some reason, you can't loop through its members:

for each ( var s: String in prototype.constant ) trace( prototype.constant[ s ] ); //no output

It also doesn't work if you explicitly name the class:

trace( Directions[ "NORTH"] ); //north
for each ( var s : String in Directions ) trace( Directions[ s ] ); //no output.

So until something better comes along, I'm stuck with XML parsing.

ditch conditionals; use factories

2009-06-06T21:36:00.000-07:00

When I first started coding, I used a lot of switch/case statements and complex ifs. But over the years, I become suspicious of them. Now, when I feel the urge to reach for a switch/case, I slap my wrist and try to come up with a better construct.

To demonstrate the problem, I've come up with a toy example: an app that fills the stage with little Fisher-Price-type people.

There are two types of people, bald people and hairy people. Just before placing a person on the stage, my app randomly chooses if he's going to have hair or not. Bald people are all members of the Person class; Hairy folks are members of the HairyPerson class. To create such classes, I do this:

var person1 : Person = Person( new bald() );
var person2 : Person = HairyPerson( new hairy() );

Note that I type both sorts of people to Person. I can do that because HairyPerson is a subclass of Person (and subclasses can be typed to their parent's type). By giving the vars the same type, I can pass them both into functions that expect a Person type, and those functions will work regardless of whether the person is a Person or a HairyPerson.

What are those new bald() and new hairy() calls doing for me? bald and hairy are MovieClips in my FLA's Library. Person classes must be passed a reference to a MovieClip. They use the clip as base artwork, which they then customize via random colors. If you want to know more about Person construction, you can check out my FLA and AS files, but the details aren't important to this post, so I won't elaborate here.

The question is this: in my Document class, where I randomly choose types of people, how do I instantiate type chosen at random? In the past, I would have done it this way:

for ( var i : int = 0; i < 100; i++ )
{
        rand = Math.floor( Math.random() * 2 );

        switch ( rand )
        {
                case 0 :
                        person = new Person( new bald() );
                        break;

                case 1 :
                        person = new HairyPerson( new hairy() );
                        break;


        }

        person.render();
        person.x = Math.random() * Stage.stageWidth;
        person.y = Math.random() * Stage.stageHeight;
        addChild( person );
}

The problem with this is that it doesn't scale well. If I add another type of person, say a HatWearingPerson, I need to add another case -- and I need to change my Math.random() statement so that it is range includes my new case:

for ( var i : int = 0; i < 100; i++ )
{
        rand = Math.floor( Math.random() * 3 ); //2 changed to 3

        switch ( rand )
        {
                case 0 :
                        person = new Person( new bald() );
                        break;

                case 1 :
                        person = new HairyPerson( new hairy() );
                        break;

                case 2 : //added
                        person = new HatWearingPerson( new hatWearer() );
                        break;

        }

        person.render();
        person.x = Math.random() * Stage.stageWidth;
        person.y = Math.random() * Stage.stageHeight;
        addChild( person );
}

This isn't such a big deal in my toy example, but imagine a more complex system in which you were constantly adding and removing types of people. Not only would I have to create the new classes; I'd also have to remember to add (or remove) new cases to the switch/case statement and to update the Math.random() statement. Eventually -- probably sooner rather than later -- I'm going to screw up and forget to add a case or forget to update Math.random().

But the bigger problem is that my Document class and the people classes are tightly coupled. Good OOP practice tells me that those person-instantiation statements shouldn't be hard coded into the Document class. Classes should be as independent from each other as possible, so that you wind up with a modular system in which you can change one class without having to change another.

What's the alternative? Factory classes! Factories are classes that make instances of other classes: Here are mine:

package
{
        public class PersonFactory implements IPersonFactory
        {
                public function getPerson() : Person
                {
                        var person : Person = new Person( new bald() );
                        return person;
                }
        }
}

package
{
        public class HairyPersonFactory implements IPersonFactory
        {
                public function getPerson() : Person
                {
                        var person : Person = new HairyPerson( new hairy() );
                        return person;
                }
        }
}

package
{
        public class HatWearingPersonFactory implements IPersonFactory
        {
                public function getPerson() : Person
                {
                        var person : Person = new HatWearingPerson( new hatwearer() );
                        return person;
                }
        }
}

As you can see, these classes all implement an interface called IPersonFactory. You'll see how this helps me out in a second. In the meantime, here's the interface:

package
{
        public interface IPersonFactory
        {
                function getPerson() : Person;
        }
}

My new and improved Document class looks like this:

var person : Person;
var rand : int;
var factories : Array;

addFactory( new PersonFactory ); //see addFactory(), below
addFactory( new HairyPersonFactory );
addFactory( new FancyPersonFactory );

for ( var i : int = 0; i < 100; i++ )
{
        rand = Math.floor( Math.random() * factories.length );
        person = factories[ rand ].getPerson();

        person.render();
        person.x = Math.random() * stage.stageWidth;
        person.y = Math.random() * stage.stageHeight;
        addChild( person );
}


function addFactory( factory : IPersonFactory ) : void
{
        factories.push( factory );
}

Note that the addFactory function accepts any class that implements the IFactory interface, so my Document class doesn't know -- or need to know -- how many types of people (or people factories) exists.

From now on, if I add a new Person subclass, I just need to make a factory for it and pass that factory to my the Document class.

visual test toolkit

2009-06-05T13:48:00.000-07:00

I'm a big fan of the Flash player, the SWF format and the Actionscript language, but I'm not crazy about the Flash IDE. It belongs on the B-list of many categories.

Want an animation tool? Check out After Effects (or Toon Boom Studio). Flash is a light-weight by comparison. Want a vector-drawing app? Use Illustrator (especially now that it has the Blob Brush!). Want a coding IDE? Use Flex or FDT. Flash dips its toes into many pools but refuses to dive into any of them.

However, I do find Flash useful for one thing -- so useful that I start it up at least once a day: Flash is a faux command-line interpreter for Actionscript! It's not really an interpreter, of course. It's more of a compiler. But it beats everything else for quickly trying out a bit of Actionscript. You don't need to create a project, a class or even a function. Just throw some code on the timeline, press Command+Enter and Bob's your uncle. That's a terrible way to code anything real, but it's a great way to quickly test out a bit of functionality.

Sometimes, when I'm doing these tests, I need visual elements. And I waste time creating little circles, square and text fields. So I quit doing that. Instead, I created a little testing file that I use over and over. It's got a stage full of doodads and whatnots, and everything is labeled with its instance name. Also, items in the library have Export for Actionscript turned on, so I can create new instances with code if need be.

I leave this file open all day, with frame 1 of the timeline exposed in the AS editor. If I need to run a quick test, I'm all set to go.

Here's the file.

generating getters and setters

2009-06-02T09:35:00.000-07:00

I'm down with OOP and using getters and setting instead of exposing class member variables, but making getters and setters is a pain. Flex and FTD have tools to help automate the process, but they don't automate it enough. I wanted to be able to type in a list of vars like this...

private var _newWidth : Number;
private var _newHeight : Number;
private var _scaleList : Array;
private var _moveList : Array;
private var _oldWidth : Number;
private var _oldHeight : Number;
private var _widthPercentChange : Number;
private var _heightPercentChange : Number;

... and, via a single click, get this...

public function get newWidth() : Number
{
return _newWidth;
}

public function set newWidth( value : Number ) : void
{
_newWidth = value;
}

public function get newHeight() : Number
{
return _newHeight;
}

public function set newHeight( value : Number ) : void
{
_newHeight = value;
}

public function get scaleList() : Array
{
return _scaleList;
}

public function set scaleList( value : Array ) : void
{
_scaleList = value;
}

public function get moveList() : Array
{
return _moveList;
}

public function set moveList( value : Array ) : void
{
_moveList = value;
}

public function get oldWidth() : Number
{
return _oldWidth;
}

public function set oldWidth( value : Number ) : void
{
_oldWidth = value;
}

public function get oldHeight() : Number
{
return _oldHeight;
}

public function set oldHeight( value : Number ) : void
{
_oldHeight = value;
}

public function get widthPercentChange() : Number
{
return _widthPercentChange;
}

public function set widthPercentChange( value : Number ) : void
{
_widthPercentChange = value;
}

public function get heightPercentChange() : Number
{
return _heightPercentChange;
}

public function set heightPercentChange( value : Number ) : void
{
_heightPercentChange = value;
}

And now I can, because I built a little AIR app to do it for me. I can copy in the private vars, press the GENERATE button, and -- BINGO! -- out pops my getters and setters. Then I can click the COPY button, which copies the getters and setters to the clipboard. Finally, I can paste them into Flex or FDT.

Here's a link to the app.

Notes: it is template-based, so if you don't like the code it generates, it's easy to make it do what you want. Click HELP for more info.

Also, please note that though this is a useful tool, it can be abused. For instance, some properties should be read only. They shouldn't have a setter. So use with caution and good OOP practices!

keeping up with the actionscript joneses

2009-06-02T07:17:00.000-07:00

I use an RSS reader called Vienna to keep up with Actionscript news. Over time, I've compiled a big list of AS-related blogs, which I've now published as in opml file. Feel free to download it an import it into Vienna (File > Import). I'll update the opml when I find new feeds.

mac apps

2009-06-01T14:03:00.000-07:00

I work on a mac. Here are the apps I use in my work. I'll update this list when I start using new apps or quit using old ones.

MEDIA
Vlc. This is a one-stop-shop video player that plays virtually any format.

WRITING
Textmate. The best text editor I've ever found for the Mac.

MacVim (free). The old Unix editor wrapped with a Mac GUI. Edit code without touching the mouse.

Open Office (free). Open-source MS Office replacement.

TextExpander. Allows you to make system-wide keyboard shortcuts that expand into blocks of text. For instance, on my system, typing aaaa expands to my complete mailing address. You can set up shortcuts that work only in specific apps.

Slidepad. Neat little text-editor that slides on and off the screen via a keyboard shortcut. I used it for on-the-fly, temporary notes.

INFO MANAGEMENT
Evernote (free). A fantastic app that lets you keep track of any sort of information. It can sync to multiple computers, the web, and many mobile devices (including the iPhone).

APP LAUNCHING
Namely (free). Allows you to launch any Mac app via the keyboard. It's a lightweight alternative to Quicksilver, which always bogs down my system.

LauncherConfig (free). Launches multiple files at once. I use it every morning to launch iChat, my mail client, my svn client, my ftp client and my Twitter client with one click.

WEB BROWSING
Firefox Browser (free). I await a Mac version of Google Chrome.

Firebug (free). THE must-have Firefox plugin for web developers.

Fluid (free). Allows you turn web pages into stand-alone apps. I use it so that I can easily launch gmail into its own window.

DEVELOPMENT
Flash Builder 4 (formerly Flex Builder). This is my main coding tool. I used to use FDT, which is terrific, but Flash Builder has now outgunned it. Flash Builder is the best AS (and MXML) editor out there.

Aptana Studio (FREE). A one-stop show IDE for HTML, CSS, Javascript, Python, Ruby and PHP. It's Eclipse-based.

MAMP (free). An Apache server for the Mac.

RegExp Tool (free). This is the best app I've every found for testing out Regular Expressions.

DESIGN
Adobe CS4 Suite. Of course.

REMOTE FILE MANAGEMENT
Transmit. My FTP client of choice. It allows you to edit files while they're online.

Syncro SVN Client. Full-featured GUI client for the Mac.

Zumodrive (free for 1GB, $ for more). A virtual harddrive that you can access from anywhere.

Transmission. Solid bittorrent client.

SOCIALIZING
Colloquay (free). All-you-need IRC client.

Tweetie (free if you use add-supported version). Solid Twitter client for the Mac (and iPhone).

EMULATING
Virtual Box (free). Run Windows on the Mac. Like Parallels, but free.

READING
Vienna (free). RSS reader with a build-in Browser.

Tofu (free). Paste text into this cool tool, and it formats the text into narrow columns, which makes online reading much easier. It's the closest you'll get to a Kindle on your computer screen.

MISC
Eigenclock (free). Replacement for the system clock. Includes a dropdown calendar.

Caffeine (free). Lets you temporarily disable sleep, so that your monitor doesn't power down. Useful if you're watching a long video.

Default Folder X. I seriously don't know how I lived without this. It wraps open, save and save-as dialogs inside a feature-packed window containing shortcuts to folders you need to access quickly. You can define any shortcuts you want.

colorizing text as you type

2009-05-31T10:37:00.000-07:00

For a project I worked on, I needed an input TextTield that would colorize specific kinds of words as the user is typing them. For instance, if the user types "To @be or not to be, @that is the @question," I need the words starting with at-signs to turn red. And, as I said, I needed this to happen "live," as the user types. In other words, "@be" needs to turn red before the user types "or."

Here's the Regular Expression I used: /\B@[A-Za-z0-9]+/g

It starts by looking for a word boundary (\B). This is so it will match @be but not the @be in bumble@bee. More important, I don't want it to match email addresses, which have at-signs in the middle. My RegExp will only match words starting with at-signs.

Next in the RegExp, I added the literal @ and then [A-Za-z0-9]+, which will match any number of characters, as long they are letters or digits. Finally, I added the global switch (g), so that the RegExp would match all @words, not just the first one it finds.

Here's the code, followed by some notes:

var input : TextField;

input.addEventListener( Event.CHANGE, onTextChange);

function onTextChange( event : Event ) : void
{
        var tfSpecial : TextFormat = new TextFormat();
        var tfDefault : TextFormat = new TextFormat();
        var allText : String = input.text;
        var caretIndex : int = input.caretIndex;
        var startIndex : int = ( caretIndex - 100 < 0 ) ? 0 : caretIndex - 100;
        var localText : String = allText.substr( startIndex, caretIndex );
        var regExp     : RegExp = new RegExp( /\B@[^ ]+/g );
        var obj : Object = regExp.exec( localText );
        tfSpecial.color = 0xFF0000;
        tfSpecial.bold = true;
        tfDefault.color = 0x000000;
        tfDefault.bold = false;

        input.setTextFormat( tfDefault, allText.length-1, allText.length  );


        while( obj != null )
        {
                input.setTextFormat( tfSpecial, obj[ "index" ],  obj[ "index" ] + String( obj ).length );
                obj = regExp.exec( allText );
        }
}

NOTES:

All those statements that reference "carretIndex" grab a chunk of the text, starting 100 characters before the cursor position and running to the cursor position. (Unless there's less than 100 characters of text, in which case the chunk is from the beginning to the cursor.) I do this because if the text gets long, I don't want -- or need -- to check all of it. 100 characters is probably overkill, but it allows the user to type @supercalifragilisticexpialidocious if he so chooses.

In this statement...

input.setTextFormat( tfDefault, allText.length-1, allText.length );

...I make sure the text after the cursor changes back to its default black, so that non @words won't be red.

Finally, I loop through all the RegExp matches and colorizes them.

my replacement for trace()

2009-05-29T13:58:00.000-07:00

When debugging a Flash app online, it always sucks that you can't use trace(). There are all sorts of tricks to get around this, including the great DeMonster Debugger.

As much as I like such tools, I've always wished for something simpler. Something like trace() -- but a trace() that works in the browser. Recently, my wish was granted. I learned that Firebug's console accepts logs from Flash. (Firebug is a must-have Firefox plugin for web developers.)

Firebug has a Javascript API which contains a function called console.log. That's great, because Flash can call JS functions, via ExternalInterface.call(functionName,param[s]).

So, all you have to do to send a message from Flash to Firebug is...

1. make sure that the allowScriptAccess parameter is set to "always" in the html page's object and embed tags (it's often set to "sameDomain" by default).

2. In the Actionscript, import Flash.external.ExternalInterface (works in AS2 and AS3).

3. When you want to "trace" to the console, type something like this: ExternalInterface.call( "console.log", "hello, world" );

That's great, but I don't want have to type something that long every time I want to run a quick trace-like action. So I made this little utility function (below). Feel free to use it. Just...

1. Copy it into the folder that contains the fla.

2. Make sure allowScriptAccess is set to "always" in the HTML's object and embed tags.

3. When you want to "trace," just call log(param1, param2, ... paramN);

The cool thing is that log() calls trace() internally, so you can use it for both local development and in-browser testing.

NOTE: with one angry client of mine, the ExternalInterface.call() method cased JavaScript errors on their site. So before going live, I recommend you comment out the final line in the log() function and recompile.

package
{
    import flash.external.ExternalInterface;

    public function log( message : *, ... rest ) : void
    {
        var s : String = "";
                var a : Array;

                a = rest as Array;

                a.unshift( message );

        trace.apply( this, a );

        for ( var i : int = 0; i < a.length; i++ )
        {
                s += a[ i ].toString() + " ";
        }

        ExternalInterface.call( "console.log" , s );
    }
}

There are a few of things worth noting about this function: first of all, it's in a package by itself -- it's not part of a class. Normally, I think of that as a no-no, but in this one case, I let myself do it. I want to be able to type just log(), not Debug.log() or something like that. But if the stand-alone function offends you, just pop it into a class.

log() accepts an arbitrary number of parameters, via the relatively obscure structure ...rest. So you can call it like this log("hello"); like this: log("hello", true); like this: log("hello", true, 45.6, [1,2,3], mySprite.x); etc.

In the above examples, "hello" would be stored in the message parameter and the rest of the parameters would be stored in rest. rest is an Array-like object, but it's not actually an Array. That's a problem, because the Function.apply() method, which I use to call trace(), needs an Array. That why I create the a Array and set it to rest as Array(). Then I push message onto the beginning of it, so that all the parameters are in one big Array.

That allows me to call trace.apply( this, a ). The Function.apply method isn't very well known. It allows you to call a function and use an Array as that function's list of parameters. For instance, the following two snippets have the same effect:

SNIPPET 1:
trace(1, 2, 3);

SNIPPET 2:
var a : Array = [1, 2, 3];
trace.apply( this, a );

(The first parameter to apply allows you to apply the function to a specific object. It's not important here, so I just used "this.")

Finally, for Firebug's console, I concatenate all the a values into a space-separated string and output them using the Console.log JS function. If you comment out the last line, log() will still work for local traces but it will no longer try to call a JS function on the web page housing the swf.

grab just the filename without the extension

2009-05-29T12:57:00.001-07:00

var filename1: String = "monster.jpg";
var filename2: String = "big.fat.hippo.flv";

filename1 = filename1.replace( new RegExp( "(.*)\.(.*)", "g" ), "$1" );
filename2 = filename2.replace( new RegExp( "(.*)\.(.*)", "g" ), "$1" );

trace(filename1); //monster
trace(filename2); //big.fat.hippo

Constrain Proportions

2009-05-29T12:23:00.001-07:00

Here's a really simple solution that I couldn't figure out for a long time: say you need to downsize an image so that the width changes to 80 pixels. You want to change the height, too, so that the image stays in proportion, but by how much should you change it?

I actually figured out a complex way to calculate the height, but then it hit me that there's a really simple way to do it:

myImage.width = 80;
myImage.scaleY = myImage.scaleX;

Dumb Bugs

2009-05-29T11:54:00.000-07:00

Hi. Welcome to Grumbleblog.

I'm a programmer, and I currently code mostly in Actionscript 3.0, Flash's language (a sister tongue to JavaScript). In this blog, I will post info about Actionscript, other languages, and various technical topics that are too arcane for my regular blog.

To start the ball rolling, here's a list of dumb mistakes I frequently make when I'm coding. Though I'll come back here and update the list (as I catch more mistakes), the list will probably only useful to me.

However, I recommend that you make a similar list for yourself. It's useful when you're stuck. Before you start pounding your head against the wall, take a deep breath and check your list.

MY COMMON BUGS

- typing function when I mean var and vice versa.
EXAMPLE: public var killMyself() : void...

- omitting the underscore prefix on private variables (my convention).
EXAMPLE: private var highscore instead of private var _highscore

- forgetting to make classes public (when they should be).
EXAMPLE: class ISuck... instead of public class ISuck...

- messing up close curly braces.
EXAMPLE: if (true) { while(true) { trace(true) } //missing a close }

- omitting the word "function."
EXAMPLE: private addTwo()... instead of private function addTwo()...

- omitting a var's type.
EXAMPLE: private var name = "Bob" instead of private var name : String = "Bob";

- leaving off var in for loops.
Example: for ( i : int = ... instead of for ( var i : int =...
NOTE: I'm especially prone to this with for-in loops.
NOTE: I also sometimes leave off the type:
for (var i = 0... instead of (var i : int = 0...

- forgetting to call new on classes that are sub objects:
EXAMPLE: o.point = {x:10,y:20}; instead of...
o.point = new Point();
o.point = {x:10,y:20};

- adding an event listener to a Loader to test for load completion. I should be attaching it to loaderInstance.contentLoaderInfo instead.