Flex 2 Developer's Guide > Building User Interfaces for
Flex Applications > Using Flex Visual Components > Handling events

Handling events

Flex applications are event-driven. Events let a programmer know when the user has interacted with an interface component, and also when important changes have happened in the appearance or life cycle of a component, such as the creation or destruction of a component or its resizing.

When an instance of a component dispatches an event, objects that have registered as listeners for that event are notified. You define event listeners, also called event handlers, in ActionScript to process events. You register event listeners for events either in the MXML declaration for the component or in ActionScript. For additional examples of the event handling, see Initializing components at run time.

The following example registers an event listener in MXML that is processed when you change views in an Accordion container.

<?xml version="1.0"?>
<!-- components\CompIntroEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    width="300"
    height="280">

    <mx:Script>
        <![CDATA[
            import mx.controls.Alert;
            private function handleAccChange():void {
                Alert.show("You just changed views");
            }
        ]]>
    </mx:Script>

    <!-- The Accordion control dispatches a change event when the 
            selected child container changes. -->
    <mx:Accordion id="myAcc" 
        height="60" 
        width="200" 
        change="handleAccChange();">
        <mx:HBox label="Box 1">
            <mx:Label text="Put Some Stuff Here"/>
        </mx:HBox>

        <mx:HBox label="Box 2">
            <mx:Label text="Put Different Stuff Here"/>
        </mx:HBox>
    </mx:Accordion>
</mx:Application>

This example produces the following image:

Accordion container and event listener

You can pass an event object, which contains information about the event, from the component to the event listener.

For the Accordion container, the event object passed to the event listener for the change event is of class IndexChangedEvent. You can write your event listener to access the event object, as the following example shows:

<?xml version="1.0"?>
<!-- components\CompIntroEventAcc.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    width="300"
    height="280">

    <mx:Script>
        <![CDATA[
            // Import the class that defines the event object.
            import mx.events.IndexChangedEvent;
            import mx.controls.Alert;
            
            private function handleChange(event:IndexChangedEvent):void {
                var currentIndex:int=event.newIndex;
                Alert.show("You just changed views \nThe new index is "
                    + event.newIndex);
            }
        ]]>
    </mx:Script>

    <!-- The Accordion control dispatches a change event when the 
            selected child container changes. -->
    <mx:Accordion id="myAcc" 
        height="60" 
        width="200" 
        change="handleChange(event);">
        <mx:HBox label="Box 1">
            <mx:Label text="Put Some Stuff Here"/>
        </mx:HBox>

        <mx:HBox label="Box 2">
            <mx:Label text="Put Different Stuff Here"/>
        </mx:HBox>
    </mx:Accordion>
</mx:Application>

In this example, you access the newIndex property of the IndexChangedEvent object to determine the index of the new child of the Accordion container. For more information on events, see Using Events.

Subtopics

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:
1. Flex sets the parent property for the component to reference its parent container.
2. Flex computes the style settings for the component.
3. Flex dispatches the add event from the button
4. Flex dispatches the childAdd event from the parent container.
5. 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.
6. Flex creates and initializes the component's children, including the component's internal children.
7. 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.
1. Flex completes all processing required to display the component, including laying out the component.
2. Flex makes the component visible by setting the visible property to true.
3. 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.
4. 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.

Flex 2.01