2  Dynamically Add and Remove Children

The click event of the s:Button control triggers the addition of a new Button child

element to the targeted container. Depending on the layout applied to a container, the

addition and removal of child elements may or may not affect the position of other

child elements. In this example, as each new child element is added, it is offset vertically

from the last child element. If BasicLayout were assigned to the container, each additional child element would be presented at a higher z-order within the display.

Using the addElementAt() method, you can set the desired position for the new child

within the display list:















In this example, as each new Button is added to the container, the control is placed at

the elemental index 0. Because VerticalLayout is assigned to the container, each new

child added will be placed at the top of the content display, pushing the y-positions of

any other child elements downward.

To remove a child element at a specific index, use the removeElementAt() method:

myContent.removeElementAt(0);



Children can also be removed using the removeElement() method, which takes the reference name of a child element as its argument:

myContent.removeElement(myElement);



If the reference name is not available, you can use the getElementAt() method of the

content API and specify the index of the child element you wish to remove. The following example uses the getElementAt() method to remove the first element from the

container’s display list:

myContent.removeElement( myContent.getElementAt( 0 ) );



The Group and SkinnableContainer layout container classes also support the removal

of all child elements using the removeAllElements() method.

As children are added to and removed from a container, the numChildren property of

the container is updated. This can help in effectively using the methods of the content

API exposed by implementations of IVisualElementContainer.

The following example demonstrates the possible ways to programmatically add child

elements to and remove them from a container:


xmlns:s="library://ns.adobe.com/flex/spark"

xmlns:mx="library://ns.adobe.com/flex/mx">



2.2 Dynamically Add and Remove Children | 31



www.it-ebooks.info






import mx.core.IVisualElement;

import spark.components.Button;

private function getNewElement():IVisualElement

{

var btn:spark.components.Button = new spark.components.Button();

btn.label = "button " + myContent.numElements;

return btn;

}

private function addFirstElement():void

{

myContent.addElementAt( getNewElement(), 0 );

}

private function addLastElement():void

{

myContent.addElement( getNewElement() );

}

private function removeFirstElement():void

{

if( myContent.numElements > 0 )

myContent.removeElement( myContent.getElementAt( 0 ) );

}

private function removeLastElement():void

{

if( myContent.numElements > 0 )

myContent.removeElementAt( myContent.numElements - 1 );

}

]]>
















label="addFirst" click="addFirstElement();" />

label="addLast" click="addLastElement();" />

label="removeFirst" click="removeFirstElement()" />

label="removeLast" click="removeLastElement()" />

label="removeAll" click="myContent.removeAllElements()" />

















32 | Chapter 2: Containers



www.it-ebooks.info



2.3 Reorder Child Elements of a Container

Problem

You want to dynamically reorder the index positions of child elements within a container at runtime.



Solution

Use the setElementIndex() method to change the elemental index of an individual child

element, or use the swapElements() and swapElementsAt() methods to transpose the

index positions of two children in an IVisualElementContainer implementation, such

as a Group or SkinnableContainer. The elemental index corresponds to the order in

which a child element is rendered in a layout.



Discussion

As child elements are added to a container, whether programmatically or declaratively

in MXML, references to those elements are stored within an Array. The container’s

layout delegate uses that Array to display children. A child element can be accessed

from this display list using its elemental index, and the order in which the children are

displayed can be manipulated by changing these indexes.

In the following example, a child element at the lowest index within the display list is

promoted to the highest index using the setElementIndex() method of an IVisual

ElementContainer implementation, consequentially updating the layout of the other

children in the HorizontalLayout:


xmlns:s="library://ns.adobe.com/flex/spark"

xmlns:mx="library://ns.adobe.com/flex/mx">




private function reorder():void

{

myContent.setElementIndex( myContent.getElementAt(0),

myContent.numElements - 1 );

}

]]>



















2.3 Reorder Child Elements of a Container | 33



www.it-ebooks.info

















The reference to the first element within the display list of the s:Group is accessed using

the getElementAt() method of the content API. The child element is moved from the

front of the list to the end, and the order in which all child elements are rendered is

updated on the layout.

The rendering order can also be manipulated at runtime using the swapElements()

method, which takes two references to IVisualElement implementations:

myContent.swapElements( btn1, btn2 );



The swapElementsAt() method swaps the indexes of two elements of a visual container

based on the specified index positions:

myContent.swapElements( 0, 2 );



Although a layout will render children sequentially from the list, do not confuse the

elemental index of a child with its depth property when considering display. The

depth property of an IVisualElement implementation represents the layer position of

the child within the layout. Its value is not tied to the length of the child display list,

and multiple children can share the same depth. Manipulating the depths therefore

differs from manipulating the indexes of children within the display list, in that assigning an index that has already been assigned or is out of the current range (from 0 to the

highest assigned index + 1) will throw a runtime exception.

The elemental index and the depth property of a child element may not visually affect

the layout of children when using sequential layouts, such as HorizontalLayout and

VerticalLayout, but it’s important to understand the concepts of rendering order and

layer depth when using BasicLayout or a custom layout. To help you understand how

the depth property of an element affects the layout, the following example displays the

first declared s:Button control on a layer above the second declared s:Button:











Although the elemental index of the second s:Button control in the display list is greater

than that of the first, the first s:Button is rendered before the second and placed on a



34 | Chapter 2: Containers



www.it-ebooks.info