Adding Children (Flash AS3)

Introduction

The easiest and most intuitive way to add an objects (like a movie clip instance) to the stage is to drag it out of the library. But it is often desirable to do this with code—to add the instance dynamically while the program is running, rather than have it there from the beginning. For example, you could create a slide show and have the slides load one at a time as they are called called.

Adding Movie Clips to the Stage

Open a new Flash file and save it right away as add_MC.fla.
First you will need a movie clip of some sort; it doesn't have to be anything special, just a shape or something. Call it "myCoolClip."
Select the movie clip in the Library window. Right-click (control-click) on the movie clip and choose Properties.
If you're using CS4, click on the Advanced button to open the properties window to full size (if it's not already open fully). In CS5, choose the ActioScript tab.
Check the "Export for Actionscript" box. Note that the movie clip name will appear in the "Class" box. Let's leave it as is ("myCoolClip") for sake of ease.
Click OK. You will get a warning that Flash will create a new class for you. That's just fine.
Create a new layer and call it "actions." Select the first frame and open the Actions window.
The first thing we need to do is to create a new instance of the myCoolClip class created above. Let's call the instance "myCoolClipInstance":
```
var myCoolClipInstance:myCoolClip = new myCoolClip();  
```

Now we need to place it on stage:

var myCoolClipInstance:myCoolClip = new myCoolClip();
addChild(myCoolClipInstance);

That's it! Pretty simple, eh?

Okay, but what if we don't want our movie clip stuck in the upper-left corner of the stage? What if we want it to appear somewhere else? Simple, simply specify x and y coordinates:
```
var myCoolClipInstance:myCoolClip = new myCoolClip();
addChild(myCoolClipInstance);
myCoolClipInstance.x=300; 
myCoolClipInstance.y=150; 
```
This will position the movie clip 300 pixels from the left edge and 150 rom the top. Of course, you can change the x and y values and position the movie clip wherever you like.

Getting trickier—user adding and removing

The example above grabs the movie clip from the library and places it on stage at run time—that it as soon as the Flash movie starts. Let's alter the code so that the user and add and remove the clip dynamically.

First, add two buttons to the stage. We'll use one to put the movie clip on to the stage and the other to remove it. Call the first button loadMC_btn and the second removeMC_btn.

Now a couple of listeners for the buttons. Put them after the first line in the code:

var myCoolClipInstance:myCoolClip = new myCoolClip();
loadMC_btn.addEventListener(MouseEvent.CLICK, loadMC);    
removeMC_btn.addEventListener(MouseEvent.CLICK, removeMC);  

addChild(myCoolClipInstance);
myCoolClipInstance.x=300; 
myCoolClipInstance.y=150;

Next we need to write the functions. Let's put the addChild() code we already have into the loadMC() function Pay close attention to the new code beloW:

var myCoolClipInstance:myCoolClip = new myCoolClip();
loadMC_btn.addEventListener(MouseEvent.CLICK, loadMC);    
removeMC_btn.addEventListener(MouseEvent.CLICK, removeMC);  

function loadMC(MouseEvent):void {
    addChild(myCoolClipInstance);
    myCoolClipInstance.x=300; 
    myCoolClipInstance.y=150;
}    

function removeMC(MouseEvent):void { 
    removeChild(myCoolClipInstance);    
}

Try it out; it should work. But there is one issue—if you hit the remove button before the object has been added to the stage you get an error. To fix this, let's add a variable and a conditional to check to see if the object is on stage. Below is the entirety of the code we've written so far with some new additions:
```
var myCoolClipInstance:myCoolClip = new myCoolClip();    
var mcOnStage:Boolean=false;    
loadMC_btn.addEventListener(MouseEvent.CLICK, loadMC);    
removeMC_btn.addEventListener(MouseEvent.CLICK, removeMC);    

function loadMC(MouseEvent):void { 
    addChild(myCoolClipInstance);
    myCoolClipInstance.x=300; 
    myCoolClipInstance.y=150;
    mcOnStage=true;    
}    

function removeMC(MouseEvent):void {
    if (mcOnStage ) { 
        removeChild(myCoolClipInstance);
        mcOnStage=false;
    }     
}  
```
First we added a boolean variable called "mcOnStage" which we set to false (since, when the movie starts the movie clip is not on stage). Next we add a statement that changes the value of the variable to true once the object is added to the stage. Finally, we add a conditional to the remove function that checks to see the value of mcOnStage. If it's true, then the function will remove the object. If it is false however, the function does not try to remove the object, preventing the error.

Adding movie clips to other clips

It's also possible to attach a movie clip to another clip already on stage.

Create an empty movie clip (a movie clip that contains no artwork inside its timeline).
Give this movie clip the instance name "holder_mc," and position it somewhere towards the middle of the stage.

Now all you need to do is add the holder's instance name to the addChild and removeChild methods like so:

 
      
        var myCoolClipInstance:myCoolClip = new myCoolClip();    
var mcOnStage:Boolean=false;    
loadMC_btn.addEventListener(MouseEvent.CLICK, loadMC);    
removeMC_btn.addEventListener(MouseEvent.CLICK, removeMC);    

function loadMC(MouseEvent):void { 
    holder_mc.addChild(myCoolClipInstance);
    //myCoolClipInstance.x=300; 
    //myCoolClipInstance.y=150; 
    mcOnStage=true;    
}    

function removeMC(MouseEvent):void {
    if (mcOnStage ) { 
        holder_mc.removeChild(myCoolClipInstance);
        mcOnStage=false;
    }     
}  
        
      

Try it now.

Creating movie clips dynamically

The addChild() method can also be used with the "new" command to create a movie clip (or other class of object) from scratch using Actionscript, and then place it on stage. For example, if I wanted to create an empty movie clip on the stage at the coordinates 100, 50, I could write:

var myClip_mc:MovieClip = new MovieClip();       
addChild(myClip_mc);       
myClip_mc.x=100;       
myClip_mc.y=50;

Let's use this to create a holder movie clip for myCoolClip:

Add the following code to your script:

var holder2_mc:MovieClip = new MovieClip();       
addChild(holder2_mc);       
holder2_mc.x=100;       
holder2_mc.y=50;

var myCoolClipInstance:myCoolClip = new myCoolClip();    
var mcOnStage:Boolean=false;    
loadMC_btn.addEventListener(MouseEvent.CLICK, loadMC);    
removeMC_btn.addEventListener(MouseEvent.CLICK, removeMC);    

function loadMC(MouseEvent):void { 
    holder2_mc.addChild(myCoolClipInstance);
    //myCoolClipInstance.x=300; 
    //myCoolClipInstance.y=150;
    mcOnStage=true;    
}    

function removeMC(MouseEvent):void {
    if (mcOnStage ) { 
        holder2_mc.removeChild(myCoolClipInstance);
        mcOnStage=false;
    }     
}

Here we create a new movie clip instance, call it "holder2," and give it an x and y position.

We can also specify the stacking order. For example, let's say we wanted the new movie clip holder2 to appear at the bottom-most position in the stack; we would add the line in black:
```
var holder2_mc:MovieClip = new MovieClip();  
addChild(holder2_mc);  
holder2_mc.x=100;  
holder2_mc.y=50;
setChildIndex(holder2_mc, 0);
```
The setChildIndex() method works a lot like the z-index property in CSS; the higher the number, the higher in the stacking order (closer to the top) the element appears. The zero denotes the bottom-most position on the stage. If you use 1 instead, the object would be placed in the second-lowest position (one up from the bottom); etc.

Be careful however; unlike CSS, if you specify a number greater than the number of objects on stage, you'll get an error. So what if you don't know how many objects are on stage? Well, if you want to place your object on top, regardless of the number of clips, you can do this:
```
var holder2_mc:MovieClip = new MovieClip();  
addChild(holder2_mc);  
holder2_mc.x=100;  
holder2_mc.y=50;
setChildIndex(holder2_mc, this.numChildren-1);
```
We have to subtract 1 because the lowest item is numbered zero; therefore if there are six items on stage, the top item is actually numbered "5."

Daniel C. Fergus