flash display_list_stage_property

Let’s come back to the stage property defined by the DisplayObject class. We have previously learned that the Stage object is no longer accessible in the global way that it was in ActionScript 1 and 2.

To access the Stage object we target the stage property on any DisplayObject:

myDisplayObject.stage

The subtlety lies in the fact that the DisplayObject has to be added to the display list in order to return a reference to the stage object.

If we target the stage property on a DisplayObject which is not present in the display list it returns a null:

<code actionscript> var myClip:MovieClip = new MovieClip(); displays : null trace( myClip.stage ); Once the clip is added to the display list, the stage property contains a reference to the Stage object: <code actionscript> var myClip:MovieClip = new MovieClip(); addChild ( myClip ); displays : [object Stage] trace( myClip.stage );

Thanks to the Event.ADDED_TO_STAGE event we can access the Stage object in a secure way as the broadcast of this event guarantees that the graphic object is present in the display list:

Contrary to timelines, that can be multiple (in the case of multiple SWFs), the Stage object is unique.

In order to test if a graphic object is currently displayed we simply have to test whether its property returns null or not.

Worth remembering

• The stage property of a DisplayObject returns null when it isn’t placed in the display list.