About the component instantiation life cycle

The component instantiation life cycle describes the sequence of steps that occur when you create a component object from a component class. As part of that life cycle, Flex automatically calls component methods, dispatches events, and makes the component visible.

The following example creates a Button control and adds it to a container:

<?xml version="1.0"?>

<!-- components\AddButtonToContainer.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Box id="box1" width="200">
        <mx:Button id="button1" label="Submit"/>

    </mx:Box>
</mx:Application>

The following ActionScript is equivalent to the portion of the MXML code. Flex executes the same sequence of steps in both examples.

// Create a Box container.
var box1:Box = new Box();
// Configure the Box container.
box1.width=200;

// Create a Button control.
var button1:Button = new Button()
// Configure the Button control.
button1.label = "Submit";

// Add the Button control to the Box container.
box1.addChild(button1);


The following steps show what occurs when you execute the ActionScript code to create the Button control, and add it to the Box container. When you create the component in MXML, Flex 2 SDK generates equivalent code.

You call the component's constructor, as the following code shows: // Create a Button control.
var button1:Button = new Button()


You configure the component by setting its properties, as the following code shows:// Configure the button control.
button1.label = "Submit";


You call the addChild() method to add the component to its parent, as the following code shows:// Add the Button control to the Box container.
box1.addChild(button1);


Flex performs the following actions to process this line:

Flex sets the parent property for the component to reference its parent container.
Flex computes the style settings for the component.
Flex dispatches the add event from the button
Flex dispatches the childAdd event from the parent container.
Flex dispatches the preinitialize event on the component. The component is in a very raw state when this event is dispatched. Many components, such as the Button control, create internal child components to implement functionality; for example, the Button control creates an internal UITextField component to represent its label text. When Flex dispatches the preinitialize event, the children, including the internal children, of a component have not yet been created.
Flex creates and initializes the component's children, including the component's internal children.
Flex dispatches the initialize event on the component. At this time, all of the component's children have been initialized, but the component has not been fully processed. In particular, it has not been sized for layout.
Later, to display the application, a render event gets triggered, and Flex does the following.
Flex completes all processing required to display the component, including laying out the component.
Flex makes the component visible by setting the visible property to true.
Flex dispatches the creationComplete event on the component. The component has been sized and processed for layout and all properties are set. This event is dispatched only once when the component is created.
Flex dispatches the updateComplete event on the component. Flex dispatches additional updateComplete events whenever the position, size, or other visual characteristic of the component changes and the component has been updated for display.
You can later remove a component from a container using the removeChild() method. The removed child's parent property is set to null. If you add the removed child to another container, it retains its last known state. If there are no references to the component, it is eventually deleted from memory by the garbage collection mechanism of Adobe Flash Player.

Given this sequence of actions, you should use the events as follows:

The preinitialize event occurs too early in the component life cycle for most initialization activities. It is useful, however, in the rare situations where you must set the properties on a parent before the children are created.
To configure a component before Flex has determined its visual appearance, use the initialize event. For example, use this for setting properties that affect its appearance, height, or width.
Use the creationComplete event for actions that rely on accurate values for the component's size or position when the component is created. If you use this event to perform an action that changes the visual appearance of the component, Flex must recalculate its layout, which adds unnecessary processing overhead to your application.
Use the updateComplete event for actions that must be performed each time a component's characteristics change, not just when the component is created.