addChild and removeChild

addChild() and removeChild() are methods which add and remove visual elements on the stage.

addChild

addChild is an ActionScript function that adds visual elements in the Flash presentation. It's general syntax is:
addChild(displayObject);
- "displayObject" is the object that must be displayed in the Flash presentation (such as: a text field, a geometric figure, an image, etc.).
You can see in the next example how to apply it. The script in this example displays three text fields, with text that is taken from an Array, and background color for each field, defined in a different Array. Also see the explanations from code.
var texts:Array = ['courses', 'tutorials', 'coursesweb.net'];      // Array with texts to display
var bcolor:Array = [0xe8e9fe, 0xeded01, 0xfedada];        // Array with colors for the background of each text
var lung:int = 110;           // Variable used for the lenght of the text field

// Read through the "texts" Array
for(var i:int=0; i<texts.length; i++)
{
  // creates a field "TextField" for each element in texts
  // Sets the fields height, lenght, and distance "x" depending on "i" (for liniar display)
  // Adds background color from "bcolor" Array and text from the current element in "texts"
  var txt:TextField = new TextField();
  txt.height = 25;
  txt.width = lung;
  txt.x = i*(lung + 8);
  txt.backgroundColor = bcolor[i];
  txt.background = true;
  txt.text = texts[i];

  addChild(txt);         // Add the field in the scene.
}
- The code "for(var i:int=0; i<texts.length; i++)" reads the "texts" Array and for each current element it creates a Text Field object, and "addChild(txt);" adds this "txt" object on the stage , with all it's settings (size, background color, text, etc.).
- It will display a row with 3 text areas in the Flash presentation, like this:
courses   tutorials   coursesweb.net
The FLA file with this example can be downloaded from: AS3 addChild.

removeChild

removeChild is an ActionScript function that deletes visual elements from the Flash presentation. It's general syntax is:
removeChild(removeObject);
- "removeObject" is the object that must be deleted from the flash presentation (such as: a text field, a geometric figure, an image).

When the same instance is added multiple times (as in the example above, the "for()" loop creates and adds the same "txt" instance 3 times), the last one is retained in memory as being that objects instance. In this case using the "removeChild(insObj)" method will delete the last element with the instance name "insObj", even if more were added, the others do not exist with that name.
You can see in the following example how to apply the "removeChild()", and the effect obtained.
  1. Open a new Flash document and draw a geometric figure (square, circle) on the stage and turn it into a button (from the Modify -> Convert to Symbol).
  2. Give the button the name "remove_bt" (in the Properties panel, at "<Instance Name>").
  3. Right-click on frame 1 in the Timeline, choose "Actions", and in the Actions panel add the following code:
    var texts:Array = ['courses', 'tutorials', 'www.marplo.net'];      // Array with text to display.
    var bcolor:Array = [0xe8e9fe, 0xeded01, 0xfedada];        // Array with colors for the background of each text
    var lung:int = 100;           //  Variable used for the lenght of the text field
    
    // Reads through the "texts" Array
    for(var i:int=0; i<texts.length; i++)
    {
      // creates a field "TextField" for each element in texts
      // Sets the fields height, lenght, and distance "x" depending on "i" (for liniar display)
      // Adds background color from "bcolor" Array and text from the current element in "texts"
      var txt:TextField = new TextField();
      txt.height = 25;
      txt.width = lung;
      txt.x = i*(lung + 8);
      txt.backgroundColor = bcolor[i];
      txt.background = true;
      txt.text = texts[i];
    
      addChild(txt);         // Adds the field on the stage
    }
    
    // Recording CLICK event for the button on the stage, "remove_bt"
    remove_bt.addEventListener(MouseEvent.CLICK, removeIns);
    
    // The function called by the registered event
    function removeIns(evt:MouseEvent):void
    {
      removeChild(txt);        // Delete's the element with the instance "txt"
    }
    
      - This script adds three text fields (as in the previous example) in the flash presentation, above the button from the stage. When the button is pressed, this activates the "MouseEvent.CLICK" event that calls the "removeIns()" function.
      - The "removeChild(txt);" command deletes the "txt" object instance.
  4. If you press "Ctrl+Enter", the result will be like in the following presentation.
    - As the same instance is added multiple times, the last one rewrites from memory the previous one. The button will delete the last text field added, but it will not recognize the others as being the "txt" instance and if the button is pressed again it will give an error.
To download the FLA file with this example, click: AS3 removeChild.

removeChildAt

When elements are added with "addChild", they are retained in memory, in an Array in the adding order, starting the indexing from the number of those added on the stage. For example, if on the stage there's only a button , it has the index 0 and the following are indexed as numbered after it (1, 2, ...).
The "removeChildAt()" method can delete elements in a Flash presentation, according to their index:

removeChildAt(index)
- When an element is deleted, the index order in the Array from memory is updated, so, the element that is recorded after the deleted one will take it's index, the following one decreases with a unit, and so on. You can understand it better from the following example witch is a new version of the previous one.
Leave the button "remove_bt" on the stage (from the document created for the previous example), delete the code in the Actions panel and add this one:
var texts:Array = ['courses', 'tutorials', 'www.marplo.net'];      // Array with text to display
var bcolor:Array = [0xe8e9fe, 0xeded01, 0xfedada];        // Array with colors for the background of each text
var lung:int = 100;           // Variable used for the lenght of the text field

// Reads through the "texts" Array
for(var i:int=0; i<texts.length; i++)
{
  // creates a field "TextField" for each element in texts
  // Sets the fields height, lenght, and distance "x" depending on "i" (for liniar display)
  // Adds background color from "bcolor" Array and text from the current element in "texts"
  var txt:TextField = new TextField();
  txt.height = 25;
  txt.width = lung;
  txt.x = i*(lung + 8);
  txt.backgroundColor = bcolor[i];
  txt.background = true;
  txt.text = texts[i];

  addChild(txt);         // Adds the field on the stage
}

// Recording CLICK event for the button on the stage, "remove_bt"
remove_bt.addEventListener(MouseEvent.CLICK, removeIns);

// The function called by the registered event
function removeIns(evt:MouseEvent):void
{
  removeChildAt(2);        // Deletes the element with index 2
}
- When the button is pressed, the comand "removeChildAt(2);" deletes the element with index 2. Two text fields remain on the stage (the first and the third, but the memory index gets updated, so, the field that had the index 3 will get index 2, fact demonstrated if the deletion button is pressed again. According to the code, it will always delete the element with the index 2. When on the stage the are no more elements that can take the place of the one deleted, pressing the button will give an error.
The FLA file with this example can be downloaded from: AS3 removeChildAt.

getChildByName

Besides the numerical index of the elements, they are also recorded with an unique name, that will not change when an element is deleted.
Each element added in the flash presentation has a unique name. If the name of the element is not specified, will be automaticaly added by the program with the name "instanceNR" ('NR' is the serial number: "instance12", "instance13", ...).
This name can be defined with the property name, with the following syntax:

insObj.name
- "insObj" is the instance of the element added in the Flash presentation.
- This command sets, but also returns, the name of that instance, for example:
                trace(insObj.name);

If you set a name, you'll have a more efficient control over the objects. To access an object by its name, use the following function:
getChildByName("name")
- "name" is the name defined with "insObj.name".
Here's how you can apply "insObj.name" and "getChildByName()" to the previous example. Use the same flash document (with the "remove_bt" button), and add the following ActionScript code (any existing code must be deleted).
var texts:Array = ['courses', 'tutorials', 'www.marplo.net'];      // Array with text to display
var bcolor:Array = [0xe8e9fe, 0xeded01, 0xfedada];        // Array with colors for the background of each text
var lung:int = 100;           // Variable used for the lenght of the text field

// Reads through the "texts" Array
for(var i:int=0; i<texts.length; i++)
{
  // creates a field "TextField" for each element in texts
  // Sets the fields height, lenght, and distance "x" depending on "i" (for liniar display)
  // Adds background color from "bcolor" Array and text from the current element in "texts"
  var txt:TextField = new TextField();
  txt.height = 25;
  txt.width = lung;
  txt.x = i*(lung + 8);
  txt.backgroundColor = bcolor[i];
  txt.background = true;
  txt.text = texts[i];

  // Atributin a name to the instance, for it to be unique also use 'i's value
  txt.name = 'camp'+i;

  addChild(txt);         // Adds the field on the stage
}

// Recording CLICK event for the button on the stage, "remove_bt"
remove_bt.addEventListener(MouseEvent.CLICK, removeIns);

// The function called by the registered event
function removeIns(evt:MouseEvent):void
{
  removeChild(getChildByName('camp0'));        // Deletes the element with 'camp0' name
  removeChild(getChildByName('camp1'));        // Deletes the element with 'camp1' name
}
- the "txt.name = 'camp'+i;" expression within the "for()" loop gives each "txt" instance a registration name: camp0, camp1, camp2.
- By knowing the added names, the "getChildByName()" method can be used. Observe the command "removeChild(getChildByName('camp0'));", "removeChild()" deletes the element taken by "getChildByName()".
The result of this example will be the one from the following presentation
- Once the text fields with the name: "camp0" and "camp1" are deleted, no other element with those names will exist in the presentation.

To download the FLA file with this example, click: AS3 getChildByName

&bull Other useful functions from this category: