How stage, root, and MainTimeline Fit Together

this article is form a flash forum. i think the article is worth to keep it. so i post it here.

When you create a new ActionScript 3 application/movie, you're working with a main timeline as the "root" of your application. This root that *you* as a developer are working with then gets added to the stage when your main timeline instance is instantiated. This instance represents the root that is a property of DisplayObject. It is your main timeline.

In the property inspector in Flash CS3 you can associate a custom class with your root (aka main timeline) by filling out the document class field (available when nothing on the screen is selected). Whatever class you specify there has to be at least a Sprite, however, since a) it needs to exist as a child of stage and b) because other instances exist within this instance (unless code is used to explicitly move them to stage). If you do not specify a class for the document class Flash will create one for you called MainTimeline. This instance represents the root that is a property of DisplayObject. It is your main timeline.

If you write code in a timeline, you are defining code that will become part of the class definition of that movie clip symbol, or in the case of the main timeline, since it isnt a symbol, definitions specific to the MainTimeline or document class definition. If you both specify a class for the document class AND write code in the main timeline, then you will have to be sure that your document class extends at least MovieClip (instead of Sprite) since you are using frames in that movie clip (to write code) and it will not work for Sprite instances.

In all respects to the developer, the main timeline is the root of the application. Fittingly so, it is also the instance referenced by the root property of DisplayObject instances within that SWF. The root instance, however, is not the absolute root of the display list hierarchy. That title belongs to the stage instance.

The stage instance is an instance of the Stage class which is instantiated when the Flash player starts. It represents the stage or top-most level of the Flash player. SWFs are then loaded into this stage container with their root instances and played as a child of stage. DisplayObject instances have a stage property that reference this Stage instance.

The stage, however, unlike root, cannot be modified by Flash developers. It is always an instance of the Stage class and always the top level of the display hierarchy within the Flash player.

When a SWF is played, it will always start with 2 display objects in the display hierarchy, the stage instance with a single child of the root instance (MainTimeline instance or an instance of your document class if specified). Other instances would be generated by contents of the SWF and are typically children of root (though it is possible to add additional children to stage through ActionScript). Any symbols or graphics in the main timeline in Flash are children of root (as, again, root is the main timeline)

ALL DisplayObject instances have root and stage properties. Each of these properties (when valid) for any display object within a single SWF reference same root and stage instances, there are only one of each (the only exception is the root property of the stage which references the stage). These properties are null if you have an instance who is not a child of a display list within the stage display hierarchy.

For loaded SWFs, the stage properties of its DisplayObject instances will reference the same stage as that referenced in the SWF that loaded it; there can be only one stage. For loaded SWFs, however, the root property will reference that loaded SWF's root, or its main timleine instance, not the root of the SWF that did the loading.

To summarize: one stage, one root per SWF (which is the main timeline) and that root is an instance of a document class or the MainTimeline class if a document class isn't provided