Flex components dispatch their own events and listen to other events. An object that wants to know about another object's events registers as a listener with that object. When an event occurs, the object dispatches the event to all registered listeners.

The core class of the Flex architecture, mx.core.UIComponent, defines core events, such as updateComplete, resize, move, creationComplete, and others that are fundamental to all components. Subclasses of these classes inherit and dispatch these events.

Custom components that extend existing Flex classes inherit all the events of the superclass. If you extend the Button class to create the MyButton class, you can use the events inherited from the Button class, such as mouseOver or creationComplete, as the following example shows:

<?xml version="1.0"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:MyComp="myComponents.*"> 

    <mx:Script>
        <![CDATA[

            import flash.events.Event;

            private function handleClick(eventObj:Event):void {
                // Define event listener.
            }

            private function handleCreationComplete(eventObj:Event):void {
                // Define event listener.
            }

        ]]>
    </mx:Script>

    <MyComp:MyButton 
        click="handleClick(event);"
        creationComplete="handleCreationComplete(event);"/>

</mx:Application>

Your custom components can also define new events based on the requirements of your components. For example, the section Using data binding with custom properties showed how to define a custom event so that properties of your component can work with the Flex data binding mechanism.

Handling predefined events within the custom component

The previous example showed a custom component, MyButton, dispatching two events. In that example, you defined the event listeners in the main application file.

Your custom component can also define event listeners within the component itself to handle the events internally. For example, Defining public properties as variables defined event listeners for the keyDown and creationComplete events within the body of the component. This allows the component to handle those events internally.

The example used the creationComplete event to access the default fontSize property of the component. You could not access this property in the constructor itself because Flex does not define it until after the component is created. For more information on the initialization order of a component, see Advanced Visual Components in ActionScript.

Dispatching custom events

Your ActionScript component can define custom events and use the predefined events. You use custom events to support data binding, to respond to user interactions, or to trigger actions by your component. For an example that uses events to support data binding, see Using data binding with custom properties.

For each custom event dispatched by your component, you must do the following:

1. Create an Event object describing the event.
2. (Optional) Use the [Event] metadata tag to make the event public so that other components can listen for it.
3. Dispatch the event by using the dispatchEvent() method.

To add information to the event object, you define a subclass of the flash.events.Event class to represent the event object. For more information on creating custom event classes, see Custom Events.

You might define some custom events that are used internally by your component, and are not intended to be recognized by the other components. For example, the following component defines a custom event, dispatches it, and handles it all within the component:

package myComponents
{
    import mx.controls.TextArea;
    import flash.events.Event;

    public class ModalText extends TextArea {

        public function ModalText() {
            super();
        
            // Register event listener. 
            addEventListener("enableChanged", enableChangedListener);
        }

        public function enableInput(value:Boolean):void {
            // Method body.
    
            // Dispatch event.
            dispatchEvent(new Event("enableChanged"));
        }

        private function enableChangedListener(eventObj:Event):void {
            // Handle event.
        }
    }
}

In this example, the public method enableInput() lets the user enable or disable input to the control. When you call the enableInput() method, the component uses the dispatchEvent() method to dispatch the enableChanged event. The dispatchEvent() method has the following signature:

dispatchEvent(eventObj)

The eventObj argument is the event object that describes the event.

If you want an MXML component to be able to register a listener for the event, you must make the event known to the Flex compiler by using the [Event] metadata tag. For each public event that your custom component dispatches, you add an [Event] metadata keyword before the class definition that defines that event, as the following example shows:

[Event(name="enableChanged", type="flash.events.Event")]
public class ModalText extends TextArea {
    ...
}

If you do not identify an event in the class file with the [Event] metadata tag, the compiler generates an error when an MXML component attempts to register a listener for that event. Any component can register an event listener for the event in ActionScript using the addEventListener() method, even if you omit the [Event] metadata tag.

You can then handle the event in MXML, as the following example shows:

<?xml version="1.0"?>
<!-- as/ASMainModalTextEvent.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    xmlns:MyComps="myComponents.*">

    <mx:Script>
        <![CDATA[

            import flash.events.Event;

            private function handleEnableChanged(event:Event):void {
                myTA.text="Got Event";
            }
        ]]>
    </mx:Script>

    <MyComps:ModalTextEvent id="myMT"
        enableChanged="handleEnableChanged(event);"/> 
    
    <mx:Button click="myMT.enableInput(true);"/>
    <mx:TextArea id="myTA"/>
</mx:Application>
The executing SWF file for the previous example is shown below: