Understanding root and the Document Class in AS3

Hopefully, we all know the _root object is gone in AS3. While use of _root was generally frowned upon in the Actionscript dev community, it had its uses. It was a quick and easy way to reference your project’s main timeline. Moving into AS3, we let go of _root and embrace the concept of a Document Class.

The purpose of the Document Class in AS3 is to extend your project’s main timeline (just a MovieClip instance) with a custom MovieClip subclass. While a similar effect was achievable in AS2, it required using a work-around. It’s nice to be able to assign your project a ‘main’ class right from the properties panel in Flash CS3.

You may be thinking that comparing the ‘AS2 _root’ to the ‘AS3 Document Class’ is like comparing apples to oranges, and you would be right. The _root object in AS2 was a reference to the project’s main timeline, whereas the Document Class is not a reference at all; it is a subclass of the MovieClip object that serves as the Actionscript’s entry point into your project.

Sooooo, why does it make sense to talk about them together…? In order to understand the concept of root (not _root!!!) in AS3 you need to understand the concept of the Document Class.

In AS3 every DisplayObject (instances and subclasses of TextField, Sprite, MovieClip, etc…) contains a root property that is a reference to the Document Class once the DisplayObject is added to the display list. It is important to realize that the DisplayObject’s root property will be null if it is not on the display list.

I have created a really bare bones example of how to interact with the root property of DisplayObjects in AS3. I have a Main class (the Document Class of my FLA) and a Child class (a subclass of Sprite) to be added to the display list.

My Child class has a single method called traceRoot which will trace out the current value of the Child’s root property and then attempt to call a method on the Main class.

The Child class:

package 
{
    import flash.display.*;
    
    public class Child extends Sprite
    {
        public function Child()
        {
            trace('--- a new Child has been instantiated ---')
        }
        
        public function traceRoot()
        {
            trace('findRoot from ' + this.root)
            trace('attempting to call the getFoo() method on this child\'s root....');
            try
            {
                // root refers to the Document Class (the class assigned to the stage), but it has
                // to be casted as the type of the Document Class if you want to be able to access its members
                trace('Success! getFoo(): ' + Main(root).getFoo());
                trace('root: ' + root)
            }
            catch(err:Error)
            {
                trace('Failed! Could not access the root to call the getFoo function... please add this child instance to the display list')
            }
        }
        
    }
}

I am using a try/catch statement in the traceRoot function, because if the Child is not on the display list and I attempt to access the root property, the FlashPlayer will throw a runtime error… accessing a member of a null property is a no-no.

Another important thing to notice: once my Child is on the stage, meaing the root property is not null, I still need to Cast the root reference to the type of my Document Class before I can access its members. Even though the Flash Player knows that the root property is of the type Document Class, it still needs to be formally casted, since the root property is always expected to be a Sprite.

Hope this helps clear up some confusion regarding the Document Class in AS3 and the new root property. Here are the source files for my simple demo if you want to get a hands on look at these concepts in action

21 Responses to 'Understanding root and the Document Class in AS3'

  1. Johan Nyberg says:

    Once again, thanks a bunch! :-)

  2. Johan Nyberg says:

    So, when would you suggest using the static array in the GlobalVarContainer class (another brilliant article, btw :-), and when should one access public variables/methods in the Document Class through the root property?

  3. Jon says:

    I shy away from making any variable public :). If you need to be able to adjust variables on an object, you should use a public setter method on that object. It is always better to have an object manage its own internal properties.

    To be honest, I don’t use the root too much in AS3, but its good to understand what it is. If I were to find myself using root, it would be to trigger a method on the Document Class.

    An alternative (and preferred) way of calling methods on the Document Class would be to bubble events up the display list and catch them at the top-level (your Document class). I still struggle a bit with executing this properly, but once I get it figured out, it’ll be an new article for sure!

  4. Johan Nyberg says:

    What I’m referring to is not so much public variables – I don’t like them either – but rather references to MovieClips on the stage. The only way to access them is either via the root property or by storing the references in a GlobalVarContainer-type-of-class.

  5. Jon says:

    yeah, as far as I know if you just want to reference any clip directly on your stage, from a somewhere nested down the Display List, root is the quick and dirty way… and really the only way to do it without using events to trigger functions in your Document Class..

    Have you worked at all with Events in AS3?

  6. Johan Nyberg says:

    I’m presently migrating from AS2 to AS3, so yes, I’ve started to come to grips with the new event model. But I’m still a bit foggy about all that bubbling stuff… :-)
    I just find that I sometimes want to be able to reference clips in my movie. For example, I have a clip that holds the frame (yes, an actual frame as in picture frame) of the movie, and it sets the boundaries.

    Referencing it is a convenient way of founding the visible bounds of the movie.

    I shouldn’t have to trigger an event to do that, should I?

  7. no… you shouldn’t have to. I would have to see your project structure to be able to offer more specific advice. if you’d like, i can take a quick look at your project and see if i can help.

  8. Dubi Sharon says:

    Dear Jonathan Greene, great stuff here, Iâm new to as3 as the rest of the world. i can’t get a solution to the stage proprties. do you have an example for that ? I will appreciate if you post one.

  9. Hey Dubi,

    Have a look at the Stage documentation in the AS3 reference manual (http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/) to see the stage related properties and methods you have available to you.

    As far as acessing the stage object and its properties/methods, you can use the inherent ‘stage’ property on any Display Object. Just like the ‘root’ property, the ‘stage’ property will be null unless the the Display Object is added to the display list.

    I updated the source files on this post to trace out some stage properties.

    Cheers,
    -Jon

  10. Johan Nyberg says:

    Hi again Jon. Thanks a bunch for your willingness in taking a look at my project! I am presently working towards a deadline with another project, but can I get back to you at the beginning of next year? I can’t seem to find your email anywhere on the site, could you please mail it to me?

    Thanks again for taking your time.

  11. Jon says:

    I won’t be doing any major QA :), but I would be happy to have a look at the project and see what might be messing you up. I sent ya my email address… good luck with your deadlines!

  12. Thanks for the info. I was trying to reference a method of the document class from a child object using something like you’re explaining, but was missing the cast – DocumentClassName(this.root);

  13. Stag do says:

    Thanks so much for making the simple example available. After going round in circles for a while, you solved my issue within a couple of minutes!
    James

  14. Muddy says:

    Thanks a lot! Was of great help!

  15. jarofed says:

    Thank you for the simple explanation of the document class concept! I work on flash games development and sometimes were stuck with this issue.

  16. Dado says:

    Failed to download – broken link.

    Thank you anyway.

  17. snick says:

    Thanks for the informative illustration of the arcane concept of root in AS3.

    I tend to think of direct linkages from child to parent as being taboo in AS3.
    Child objects should dispatch events up to the parent, and let the parent handle the job of executing instructions within its own domain. This also sidesteps the potential problems with hard-coded links to parent objects.

    “root” seems more or less like a kludge included in AS3 for completeness, with respect to earlier versions of the platform. Instance names, and the plethora of associated methods in AS3, kind of fall into the same category. This is essentially an advocation of previous “less than best” practices in order to promote adoption of the new language.

  18. benjamin says:

    Well explained Tutorial.

  19. Hubert Wilk says:

    Hi

    I have problem with Font from and to external SWF, accessing it is look like I can Register new font but when I use any of the font from Embeded and Registred in External swf just do not work showing my empty textfield, when I use font embeded in time of creation it is workin so it is look like Font is in two levels Root in total SWF and in Roots in individials external loaded SWF. Is stupid as I can registred with this one Super root call it that – mean Master one , but read only from local one individual of external SWF, is any chance to move or replace Font to one place via swfs: (

    PLEASE HELP :)))

    Regards
    Hubert

  20. Hubert Wilk says:

    hw3web.co.uk/extra/dynamicTTF.jpg , so all work happen in External SWF load External Fonts(via swfs) and registre it , look like it gooing to FONT in RED master SWF , but when I set TextField in my external Grey one Font is not existing , I must add when I use SWF external without load to Master(red) one all works finr , so it must be problem/issue with root/Font location !: (

    Regards
    Hubert

Trackbacks/Pingbacks
  1. [...] You know what, I think I got you confused… I am just tired and did not understand the scope of your issue. Perhaps it is better if you read this article about root in AS3: http://greenethumb.com/article/23/understanding-root-and-the-document- class-in-as3 [...]

Leave a Reply

Your email address will not be published. Required fields are marked *

*