When to set Stage properties

Speaking of setting AIR for TV Stage properties (which I was speaking of in my last blog entry) ….

I was looking at some sample AIR for TV applications written by a member of the AIR for TV engineering team, and was reminded of something interesting. He sets the stage properties in an event handler that handles the ADDED_TO_STAGE event.

Specifically, in the constructor for his main document class, he writes:

addEventListener(Event.ADDED_TO_STAGE, onStage);

Then in his onStage() event handler, he writes:

private function onStage(evt:Event):void
stage.align = StageAlign.TOP_LEFT;
stage.scaleMode = StageScaleMode.NO_SCALE;
//remove event listener
removeEventListener(Event.ADDED_TO_STAGE, onStage);
// And more initializations follow

It’s tempting, and seemingly logical, to put the Stage property initializations in the constructor of the main document class. But you should wait until you receive the ADDED_TO_STAGE event.  It is possible in some circumstances for the constructor of the main document class  to execute before the object has been added to the stage.  If that occurs, accessing the object’s stage property results in an exception.

For a display object that is not the main document class, this behavior is more obvious. You create a display object, and then you add it to the stage. Therefore, the object’s constructor always executes before you add the object to the stage.  So setting Stage properties in the constructor is certain to fail in these cases.  So that’s another good reason to always wait to access the stage property of any display object until after you’ve received the ADDED_TO_STAGE event.

This programming tip is not specific, by the way, to AIR for TV applications, but applies to any Flash Player or AIR app.