This section gives you a summary of the properties and methods covered in this chapter. This list isn't exhaustive, but it includes some of the handiest and most frequently used tools. You can find a complete list in the Flash CS5 help files: Help→Flash Help→ActionScript 3.0 and Components→ActionScript 3.0 Language and Components Reference. Look for the DisplayObjectContainer class, and then scroll down to find the properties and methods. If you see a method and want more details about it, click its name.
All display object containers are also descendants of the DisplayObject type. They have all the properties you'd expect in a displayable object, like x/y position coordinates, height, and width. In addition, they have a few properties that are particularly useful in their role as containers. The summary below lists the name of the property in bold, followed by a description, explaining the characteristics of the property and a few details about its use. The formal description is the description found in Adobe's ActionScript 3.0 Reference. It lists the property name, and then on the right side of the colon it shows the data type stored in the property. The formal description is helpful but a little abstract, so this list also provides an example, which is a little more concrete and follows the card table and card theme used throughout this chapter. The examples show how you'd use the property, assuming that the display object container is an instance of a movie clip named greenTable.
name. You can assign a name to a display object container using the name property. You can use just about anything for a name. In the examples in this book, the name property was used with the trace() statement. Be careful not to confuse the name property with variable names or class names. See Using trace() to Report on the Display List for more details about the name property.
Formal Description: name: String
Example: greenTable.name
numChildren. A property that keeps track of the number of children in a display object container. The value is an int data type. This value is helpful when you're writing routines that identify specific child objects in a container. If you use numChildren along with the position index of the children, keep in mind that the index begins its count at 0, while numChildren starts its count at 1. See Adding Display Objects by Index Position for an example that uses the numChildren property.
Formal Description: numChildren: int
Example: greenTable.numChildren
parent. Display object containers can have parents, too. Use the parent property to show the parent of the display object container, which has to also be a DisplayObjectContainer type. When you work with the Display List, the methods used most are those that belong to the display object container. Often the easiest way to identify the display object container is with the parent property. See Placing Objects Inside Display Containers for more details about the parent property.
Formal Description: parent: DisplayObjectContainer
Example: card1.parent. In this example, if card1 is a display object held in the display object container greenTable, the result identifies greenTable as the parent.
When you work with the Display List, you're working with the methods of display object containers. Methods like addChild() and removeChild() are indispensable. The summary list below is made up of three parts. The first part shows the name of the method in bold, and then gives a description, explaining what the method does, and the result or value that comes from the method. There may also be a page reference pointing you to a place in this chapter that provides more details about the method and related issues.
The second part of the summary shows the formal description of the method as provided by Adobe in the help system's ActionScript 3.0 Language and Components Reference. From left to right, the formal description begins with the method name, and then in parentheses shows the parameters required by the method. Parameters include a descriptive word on one side of the colon and the data type on the other side of the colon. Some methods have more than one parameter. On the right side of the parentheses is another colon and a word that describes the data type or class that the method returns. The formal description is somewhat abstract. The examples at the end of each summary are more concrete, showing you how you'd write a statement using the method. The examples continue using the card table and card theme used in this chapter. The assumption is that the display object container in the example is an instance of a movie clip named greenTable. The display object is an instance of a movie clip named "card1." Where a name property is used, card1 has a name property of "Card 1."
addChild(). Adds a display object to the Display List using the variable name of the display object. Adding a display object to the Display List makes it visible in the animation. The display object is added as a child of the display object container and then placed on the top of the visual stack, giving it the highest position index number. See Adding Objects to the Display List for more details about the addChild() method.
Formal description: addChild(child:DisplayObject): DisplayObject
Example: greenTable.addChild(card1);
addChildAt(). Adds a display object to the Display List using the variable name of the child and a specified index position. The child is positioned at the exact index included in the method parameters. Objects already on the Display List at that index level or above are bumped up by one. The position index doesn't permit empty spots. So, for example, if a display object container has only four children and you attempt to add a new child at index position 7, your animation won't run, and you see an error message with the words, "The supplied index is out of bounds." For more examples using the addChildAt() method, see Adding Display Objects by Index Position.
Formal description: addChildAt(child:DisplayObject, index:int):DisplayObject
Example: greenTable.addChildAt(card1,3);
contains(). Determines whether a display object is held in a DisplayContainerObject. The result is true if the display object is in the display object container.
Formal description: contains(child:DisplayObject):Boolean
Example: greenTable.contains(card1);
getChildAt(). Returns the child display object instance at a particular position index. After identifying the instance, you can use the properties and methods of the object. See Getting the Name or Index Position of a Display Object for more details.
Formal description: getChildAt(index:int):DisplayObject
Example: greenTable.getChildAt(3);
getChildByName(). Returns the child display object by identifying the name property. After identifying the instance, you can use the properties and methods of the object.
Formal description: getChildByName(name:String):DisplayObject
Example: greenTable.getChildByName("Card 1");
getChildIndex(). Returns the position index of a display object using the variable name. The result is a value of type int. See Getting the Name or Index Position of a Display Object for more examples using the getChildIndex() method.
Formal description: getChildIndex(child:DisplayObject):int
Example: greenTable.getChildIndex(card1);
removeChild(). Removes a display object from the Display List and from its display object container. A child removed from the Display List is no longer visible in the animation. The object is referenced by its variable name. If the object is itself a display object container, then the display objects it holds are also removed. For more details, see Removing Objects from the Display List.
Formal description: removeChild(child:DisplayObject):DisplayObject
Example: greenTable.removeChild(card1);
removeChildAt(). Removes a display object from the Display List and from its display object container. The object is referenced by its positionIndex; its name or variable name isn't required. If the object is itself a display object container, the display objects it holds are also removed. For another example of the removeChildAt() method, see Removing Display Objects by Index Position.
Formal description: removeChildAt(index:int):DisplayObject
Example: greenTable.removeChildAt(2);
swapChildren(). Swaps the position of two display objects in their display object container. This changes the visual stacking order—the way objects appear to overlap each other as well as other display objects in the container. For more on swapChildren(), see Swapping the Position of Two Children.
Formal description: swapChildren(child1:DisplayObject, child2:DisplayObject):void
Example: greenTable.swapChildren(card1, card2);
swapChildrenAt(). Swaps the position of two display objects in their display object container. This changes the visual stacking order—the way the objects appear to overlap each other as well as other display objects in the container. There are more details on the swapChildrenAt() method on Swapping the Position of Two Children.
Formal description: swapChildrenAt(index1:int, index2:int):void