When you create a component using MXML, you can add an event handler using an attribute that has the same name as the event you want to handle. For example, buttons dispatch click events when the user clicks on them. Therefore, you can add a click attribute to the Button tag to handle the click event. You also can assign ActionScript to the attribute. For example, the following code lowers the alpha of the button by .1 each time the user clicks on the button:

<mx:Button id="button" label="Alpha Button" click="button.alpha −= .1" />

Although you can assign ActionScript expressions to event handler attributes, as in the preceding example, it is more common (and useful) to assign a function call to the event handler attribute. This allows you to define more complex functionality in response to the event. When you call a function/method from an event handler attribute, you should pass a parameter called event to the function. In MXML, the event parameter will automatically pass along the event object that the component dispatches:

<mx:Button id="button" label="Alpha Button" click="clickHandler(event)" />

You then need to define the method that is intended to handle the event. The method should accept a parameter of type Event (or the appropriate subtype). The following example accomplishes the same thing as the inline expression did previously. However, in addition it resets the alpha to 1 if and when the alpha is less than 0:

private function clickHandler(event:MouseEvent):void {
  var target:Button = event.target as Button;
  target.alpha −= .1;
  if(target.alpha < 0) {
    target.alpha = 1;
  }
}

As you can see in the preceding code, we can retrieve a reference to the object that dispatched the event using the target property of the event object. This allows one event listener to be used with more than one event dispatcher.

You can use ActionScript to add event listeners to a component as an alternative to using MXML event attributes. This is useful for a couple of reasons. First, it is useful to add event listeners using ActionScript when you are creating the component instance using ActionScript as opposed to MXML. Second, when you add event listeners using ActionScript, you can also remove the event listeners later. This is useful if you want to temporarily or permanently stop listening for a specific event for a component.

To register a listener for an event using ActionScript you should use the addEventListener() method. This method requires that you pass it at least two parameters: the name of the event for which you want to listen and the function to use as the listener. Typically, you should use constants for event names rather than quoted strings to avoid typos that would introduce bugs that the compiler would not catch. The event name constants are members of the associated event class. For example, the Event class defines OPEN, CLOSE, SCROLL, SELECT, and many other constants. The MouseEvent class defines CLICK, MOUSE_OVER, and other mouse-related event constants. The FlexEvent class defines constants for many of the Flex-specific events such as ADD, REMOVE, CREATION_COMPLETE, and INITIALIZE. The following code creates a button and then adds a listener for the click event:

var button:Button = new Button();
button.label = "Click This Button";
button.addEventListener(MouseEvent.CLICK, clickHandler);
addChild(button);

The event listener function is automatically passed an Event object as a parameter:

private function clickHandler(event:MouseEvent):void {
  var target:Button = event.target as Button;
  target.alpha −= .1;
  if(target.alpha < 0) {
    target.alpha = 1;
  }
}

The flash.events.Event class is the base class for all events in Flex applications. However, many event objects are instances of event subtypes. For example, events related to mouse behavior (click, mouseOver, etc.) are of type MouseEvent.

Event objects always have a type property indicating the type of event the object represents. For example, a click event will dispatch an object with a type property of click. Event objects also have target properties that reference the actual object that dispatched the event. In some cases, the target may not be the object for which you have registered a listener. This can occur when the object for which you have registered a listener contains a child component that also dispatches the same event (and the event bubbles). If you want to ensure that you are getting a reference to the object for which the listener is registered to listen for the event, use the currentTarget property. The following example illustrates this point:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical">
    <mx:Script>
        <![CDATA[

            private function clickHandler(event:MouseEvent):void {
                textArea.text = event.target + "
" + event.currentTarget;
            }

        ]]>
    </mx:Script>
    <mx:Canvas id="canvas" click="clickHandler(event);">
        <mx:Button id="button" label="Click This Button" />
    </mx:Canvas>
    <mx:TextArea id="textArea" />
</mx:Application>

If you run this example and click the button, you’ll see that the text area tells you that the target of the event is the button while the current target is the canvas. That is because the button is what actually dispatched the event, but the canvas is the object with which you registered the listener.

Each UI component type may have events that are specific to that type. For example, combo boxes dispatch open events when the menu is expanded. However, all UI components have a set of events in common. Table 7-2 lists these common events.

The list of common events in Table 7-2 isn't comprehensive. The UIComponent class (from which all UI components inherit) defines many more events. For a comprehensive list, look at the Flex documentation listing for mx.core.UIComponent. We’ll also discuss many of the events in this book in the sections where they're most appropriate (e.g., we’ll discuss drag-and-drop events in the Drag-and-Dropˮ section of Chapter 10).