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.

4 Responses to When to set Stage properties

  1. Pingback: Tweets that mention When to set Stage properties « Flash Platform Doc Team -- Topsy.com

  2. David says:

    Hi! That’s very interesting. Maybe it’s because I’ve never developed an AIR app but under exactly what circumstances would the stage property be null in the main-class instance of the first .swf file opened by the Flash runtime? I’d really like to know the details on this. And is it just for AIR… or also applicable to the Flash Player?

  3. Jackie Levy says:

    Hi David,

    This behavior can occur in AIR or Flash Player apps, and is not platform-specific.

    I went back to the AIR for TV engineer to get some examples of circumstances that cause the stage property of the main document class to be null. Here’s one he knows about it. There could be others.

    On the Stage, I placed a TLF TextField. (I used Flash Professional CS5, and in the properties tab, set the drop down values to TLF Text and Read Only).

    Then, in my main document class, I put this line in the constructor:
    stage.scaleMode = StageScaleMode.NO_SCALE;

    And sure enough, I get this error when I try run the app (using Control > Test Movie > Test):

    TypeError: Error #1009: Cannot access a property or method of a null object reference.

    Then I changed the constructor to listen for the ADDED_TO_STAGE event, and put the stage property initialization in the event handler. All was well – no nasty exception.

    I did this first with my publish settings set to Adobe AIR 2 and then repeated it for Flash Player 10.

    I’m a little fuzzy on exactly what is happening internally. The TLF field obviously requires the TLF framework, and somehow that changes the order of execution such that the document class’s stage property has not yet been set.

    I hope that helps.