flash display_list_root_property

ActionScript 1 and 2 developers will surely remember the _root property. In ActionScript 3 its function has been entirely reviewed rendering its usage totally secure.

You will remember that the root property was accessible in a global manner and allowed us to quickly reference the main timeline of an animation. Its use was strongly advised against for reasons of portability of the application developed.

Let’s take a typical case: we would develop an animation in ActionScript 1 or 2 which was then loaded in another SWF. If we targeted our main timeline with the _root, once the animation was loaded by the SWF, the _root would point to the timeline of the SWF loader and no longer to the timeline of our loaded SWF.

It is for this reason that it was advised to always work by relative targeting using the _parent property and not by absolute targeting using the _root property.

As with the stage property, the root property returns null although the DisplayObject has not been added to the display list.

var myClip:MovieClip = new MovieClip();
// displays : null
trace( myClip.root );

So that the root property points to the timeline where the DisplayObject is attached you must add it to the display list.

If the graphic object is a child of the main timeline, that’s to say contained by the MainTimeline object, its root property points to it.

The following code is defined by the main timeline:

var myClip:MovieClip = new MovieClip();
// the myClip clip is added to the main timeline
addChild ( myClip );
// displays : [object MainTimeline]
trace( myClip.root );

If the graphic object is not a child of the main timeline, but a child of the Stage object, its root property returns a reference to it:

var myClip:MovieClip = new MovieClip();
// the myClip clip is added to the Stage object
stage.addChild ( myClip );
// displays : [object Stage]
trace( myClip.root );

Once the graphic object is not a child of the main timeline, its root and stage properties are equivalent as they both point towards the Stage object.

The use of the root property in ActionScript 3 is totally justified and doesn’t pose any targeting problem as was the case in ActionScript 1 and 2.

In ActionScript 3, the root property references the main timeline of the current SWF. Even in the case of external loading, when the SWF is loaded in another we can easily target the root property, we always make reference to the timeline of the current SWF.

This illustrates the idea of scenarios:

We investigate this further in the article entitled loading external content.

Worth remembering

• The root property of a DisplayObject returns null as long as it is not placed in the display list.
• When the graphic object is not a child of the main timeline the root and stage properties both return a reference to the stage object.
• The root property references the timeline of the current SWF.
• In ActionScript 3 the use of the root property doesn’t suffer from its previous weaknesses in ActionScript 1 and 2.