An MXML event handler uses an XML attribute where the attribute's name matches the name of the event being handled. For example, the Button class's click event uses an XML attribute that's also named click. The value of the XML attribute is an ActionScript statement that causes some action to take place.

Executing a single ActionScript statement in an event handler

If you need to execute a single ActionScript statement for any particular event, you can place the ActionScript code directly in the MXML-based event handler. In the following code, when the user clicks the Button component, the click event is handled and the ActionScript statement in the click XML attribute is executed:

<mx:Button label="Click Me"
    click="messageLabel.text='You clicked the button'"/>
<mx:Label id="messageLabel"/>

<input type="button" onClick="doSomething()"/>

The result is the same as in MXML: The event handler consists of a markup-based attribute that calls scripting code to be executed upon the event being dispatched. Only the event naming pattern is different.

A simple event handling application

Follow these steps to create a simple application that uses an MXML-based event handler:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="vertical">
    <mx:Label id="myLabel"/>
    <mx:Button label="Click Me" click="myLabel.
</mx:Application>

Handling events with ActionScript functions

When you need to execute more than a single ActionScript statement in response to an event, you should create a custom function. The function allows you to add as much code as you need. The event handler function can be very simple:

private function clickHandler():void
{
    ... add ActionScript code here ...
}

Now all the code you want to call is wrapped inside clickHandler(), so to execute the code, call the function from the object's event handler:

<mx:Button label="Click Me" click="clickHandler()"/>

<mx:Button label="Save" click="saveClickHandler()"/>
<mx:Button label="Cancel" click="cancelClickHandler()"/>

Using an event handler function

Follow these steps to create an application that uses an event handler function:

<?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():void
    {
    myLabel.text="You clicked the button";
    }
    ]]>
    </mx:Script>
    <mx:Label id="myLabel"/>
    <mx:Button label="Click Me" click="clickHandler()"/>
</mx:Application>

Every event that's dispatched in the Flex framework creates a variable known as an event object. The purpose of an event object is to share information about the nature of the event, including the event's name, the object that dispatched the event, the context of the event, and detailed information that might be useful in understanding what happened.

The event object's variable name

To handle an event and get information from the event object, you typically create an event handler function that's designed to receive the event object as an argument. When the event occurs, you then call the event handler function and pass the event object as its argument. For the duration of an MXML-based event handler, the name of the event object is always the same: event (always spelled in lowercase). So, assuming you've created a clickHandler() function that's designed to receive an event argument, the syntax of the MXML object declaration becomes this:

<mx:Button label="Click Me" click="clickHandler(event)"/>

Using event object arguments

The event object is always an instance of an ActionScript class named flash.events.Event or a subclass of this Event class. When you create an event handler function to receive an event object, you can always data type the argument as the Event class:

private function clickHandler(event:Event):void
{
    myLabel.text="You clicked the button";
}

Tip

All event objects can be handled as the Event class as they're passed into an event handler function, even if their true type is a subclass of the Event class. This convenient shortcut is made possible by ActionScript's support for polymorphism, where objects can be cast as and handled as their superclass types. As long as you don't need to refer to event object properties that are only implemented in the subclass, such as MouseEvent, typing the event object as Event doesn't have any negative effect on the application's performance or functionality.

Using event object properties

As shown in the UML diagram in Figure 7.4, the Event class supports properties and methods that let you get information about the event and in some cases control its behavior. (The diagram shows only certain key properties and methods of the Event class. See the class's API documentation for a complete list.)

Figure 7.4. UML diagram of the Event class

These are the key properties of the Event class:

When you pass an event object to an event handler function as an argument, you have access to all the event object's properties for the duration of the function. To capture information about the event, use the properties that are of interest:

private function clickHandler(event:Event):void
{
    myLabel.text="You clicked the button labeled " +
    event.target.label;
}

Using event object properties in an application

Follow these steps to create an application that uses event object properties:

<?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:Event):void
    {
    myLabel.text="The " + event.type +
    " event was dispatched by " + event.target.id;
    }
    ]]>
    </mx:Script>

    <mx:Label id="myLabel"/>
      <mx:Button label="Click Me" click="clickHandler(event)"/>

</mx:Application>

Event class inheritance

Event objects are created as specific class types depending on the nature of the event that's dispatched. For example, events having to do with mouse actions are typically instances of a class name flash.events.MouseEvent. As shown in the UML diagram in Figure 7.5, MouseEvent, ResultEvent, TextEvent, and dozens of other classes in the Flash and Flex class libraries are directly extended from the standard Event class.

Figure 7.5. All event classes are directly extended from the Event superclass

When an event class such as MouseEvent extends Event, it inherits that superclass's basic properties such as type and target. The subclass typically defines additional properties that are useful for that particular event. The MouseEvent class adds properties to track button state, mouse cursor position, and other useful information. Some of these properties include:

Which event class will I get?

To find out what specific class will be dispatched for a particular event, you can use one of these strategies:

Debugging the event object

Follow these steps to debug the application and inspect the event object:

As shown in Figure 7.6, the Variables view displays the event object's type and all its current property values.

Reading the documentation

Documentation for every event in the Flex Framework includes the type of the event object that will be dispatched when the event occurs. For example, the documentation for the Button class's click event shows that the event object is an instance of flash.events.MouseEvent. To find this information:

As shown in Figure 7.7, you should see the specific type of the class that will be dispatched for that event.

Figure 7.6. The event object's type displayed in the Variables view

Figure 7.7. Documentation for the click event

Handling specific event objects

To capture information that's available only in one of the extended event classes, set an event handler function's event argument to that class. For example, this event handler function expects an instance of MouseEvent:

private function clickHandler(event:MouseEvent):void
{
    myLabel.text="You clicked; was the alt key pressed? " +
    event.altKey;
}

The altKey property is available only because the event argument is declared as the subclass that supports that property. If the event argument instead is declared as the Event superclass, the altKey property isn't recognized by the compiler and a compiler error results.

The complete application shown in Listing 7.4 is an application that captures a MouseEvent and displays the status of the keys on the keyboard at the moment the event is dispatched.

<?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
    {
    myLabel.text="The " + event.type +
    " event was dispatched by " + event.target.id;
    altLabel.text="Alt key pressed: " + event.altKey;
    ctrlLabel.text="Ctrl key pressed: " + event.ctrlKey;
    shiftLabel.text="Shift key pressed: " + event.shiftKey;
    }
    ]]>
    </mx:Script>

    <mx:Label id="myLabel"/>
    <mx:Label id="altLabel"/>
    <mx:Label id="ctrlLabel"/>
    <mx:Label id="shiftLabel"/>

    <mx:Button label="Click Me" click="clickHandler(event)"/>

</mx:Application>

The following MXML code declares a Button component with a click event handler:

<mx:Button id="myButton" label="Click Me"
    click="clickHandler(event)"/>

The following code calls addEventListener() instead of the MXML-based event handler:

myButton.addEventListener("click", clickHandler);

The first argument you pass to addEventListener() is the name of the event you're listening for. The second argument is the name of the function you want to call when the event is dispatched.

The object from which you call addEventListener() always calls the listener function with the same signature, passing a single argument data typed as the appropriate event class for that event. Event listener functions designed to be used with addEventListener() always have the same signature:

[access modifier] function [functionName](
    event:[event class data type]):void
{}

So a function designed to receive an instance of MouseEvent always looks like this:

private function clickHandler(event:MouseEvent):void
{
    ... execute event handling code ...
}

You typically call addEventListener() during application startup, where it can replace an MXML-based event handler definition. For example, you might set up your event listeners in a function named initApp() that's called upon the Application component's creationComplete event. The application in Listing 7.5 uses this strategy. Notice the following:

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
      layout="vertical"
    creationComplete="initApp()">
    <mx:Script>
    <![CDATA[
    private function initApp():void
    {
    myButton.addEventListener("click", clickHandler);
    }
    private function clickHandler(event:MouseEvent):void

{
    myLabel.text="The " + event.type +
    " event was dispatched by " + event.target.id;
    }
    ]]>
    </mx:Script>
    <mx:Button id="myButton" label="Click Me"/>
</mx:Application>

Each event class in the Flex framework implements constants that have values equal to the names of events for which the event class is used. For example, the MouseEvent class has many constants that reflect the names of events for which this event class is dispatched (shown with their equivalent values):

There are more, but you get the picture. You use these constants in calls to addEventListener() instead of phrasing the event name as a literal string. For example, instead of this code:

myButton.addEventListener("click", clickHandler);

you can use this:

myButton.addEventListener(MouseEvent.CLICK, clickHandler);

When you use event name constants, you reduce the risk of typing errors in your code. When you use literal strings to indicate which event you want to listen for, it's easy to misspell the name. For example, this code would result in an event listener that will never be triggered, because no event name is clik:

myButton.addEventListener("clik", clickHandler);

Because the event name is phrased as a literal string, the compiler has no way of knowing that it's misspelled. Of course, you can make the same mistake with an event name constant:

myButton.addEventListener(MouseEvent.CLIK, clickHandler);

But in this case, the compiler would complain, as shown in Figure 7.8, telling you that there is no such property or constant as CLIK in the MouseEvent class, and you'd be able to find and fix the error at a much earlier stage of development.

Figure 7.8. A compiler error resulting from a misspelled event name constant

Another advantage of using event name constants comes from Flex Builder's code completion tool. As shown in Figure 7.9, when you type the name of the MouseEvent class and add a period, you see a list of available constants that are members of the class. You can then select the appropriate event name and ensure that it's typed correctly from the beginning.

Figure 7.9. Flex Builder's code completion tool with event name constants

You can remove an event listener that was set up with addEventListener() with the removeEventListener() method. This method also is defined in the EventDispatcher class and can be called from any object that dispatches events.

The basic syntax for removeEventListener() is the same as addEventListener():

myButton.removeEventListener(MouseEvent.CLICK, clickHandler);

The addEventListener() and removeEventListener() methods allow you to add and remove event listeners as needed whenever an application's requirements change logically at runtime.

You declare custom events in a component with the <mx:Metadata> tag and a metadata tag named [Event]. Start by adding the <mx:Metadata> tag set as a child of the component root:

<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Metadata>
    </mx:Metadata>
    ... remainder of component code ...
</mx:VBox>

Within the <mx:Metadata> tag set, add one [Event] metadata tag for each custom event you want to declare. The syntax of the [Event] metadata tag is:

[Event(name="[custom event name]", type="[event object type]")]

The [Event] metadata tag has these two attributes:

If you only need to dispatch an event that informs the event listener that the event occurred, and don't need to share specific data, you can use a shorthand form of the [Event] tag that omits the type attribute:

[Event(name="sizeSelected")]

If you need to share specific data with the event listener and use a special event class that is designed to contain that data, include the type property and refer to the fully qualified event class name:

[Event(name="sizeSelected", type="flash.events.TextEvent")]

Adding an event declaration to a custom component and testing it

Follow these steps to add an event declaration to a custom MXML component:

Figure 7.11. A custom event shown in Flex Builder's code completion tool

As shown in Figure 7.12, the application displays the component but isn't yet handling the custom event.

Figure 7.12. The application with the custom component

To dispatch a custom event, follow these steps:

The complete code to dispatch a TextEvent class for an event named sizeChanged looks like this:

var e:TextEvent = new TextEvent("sizeChanged");
e.text = "some value I want to share";
dispatchEvent(e);

Follow these steps to dispatch an event from the custom component:

The completed component code is shown in Listing 7.7.

<?xml version="1.0" encoding="utf-8"?>
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Metadata>
    [Event(name="sizeSelected", type="flash.events.Event")]
    </mx:Metadata>
    <mx:Script>
    <![CDATA[
    private function clickHandler(event:Event):void
    {
    var e:TextEvent = new TextEvent("sizeSelected");
    e.text = sizeGroup.selection.value as String;
    dispatchEvent(e);
    }

]]>
    </mx:Script>
    <mx:RadioButtonGroup id="sizeGroup" itemClick="clickHandler(event)"/>
    <mx:RadioButton value="Small" label="Small" groupName="sizeGroup"/>
    <mx:RadioButton value="Medium" label="Medium" groupName="sizeGroup"/>
    <mx:RadioButton value="Large" label="Large" groupName="sizeGroup"/>
</mx:VBox>

Event handling with custom events looks just like handling events that are predefined by classes in the Flex framework. You can handle a custom event in these two ways:

Handling a custom event with MXML

To handle an event with an MXML declaration, add an XML attribute named for the event to the MXML declaration of the object that will dispatch the event. When the event is dispatched, call a custom event handler function and pass the event object as an argument:

<components:SizeSelectorComplete
    sizeSelected="sizeSelectedHandler(event)"/>

Create a custom event handler function that expects the appropriate event class as its event argument:

private function sizeSelectedHandler(event:TextEvent):void
{
    ... process event data here ...
}

When the event occurs, the event handler function is executed and the data can then be appropriately handled.

Follow these steps to handle a custom event with an MXML event handler:

As shown in Figure 7.13, you should see that the selected radio button's value is displayed in the application.

Figure 7.13. The completed application handling a custom event

Custom event classes are designed as ActionScript classes that extend the Event class. You can place the custom event class in any folder within a project source root; typically they're created in a folder simply named events.

Using the New ActionScript Class wizard

Follow these steps to create a custom event class that holds data for a Login form:

The generated class code should now look like this:

package events
{
    import flash.events.Event;
    public class LoginEvent extends Event
    {
    public function LoginEvent(type:String,
    bubbles:Boolean=false, cancelable:Boolean=false)
    {
    super(type, bubbles, cancelable);
    }
    }
}

var myEvent:LoginEvent = new LoginEvent("myEventName");

Declaring public properties

Each data value you want to wrap into the custom event class should be declared as a public property. For example, a data value for the user's password in a login data entry form would be declared as:

public var password:String;

Follow these steps to add user and password data elements to the custom event class:

Declaring event name constants

If you know the name of certain custom events for which the custom event class is designed, you can declare static event name constants that serve the same purpose of such constants as MouseEvent.CLICK; they help you accurately code the rest of the application.

For example, if the LoginEvent class will be used for a custom event named login, you would declare the event name constant with:

public static const LOGIN:String="login";

When you listen for the event using addEventListener(), you can use the constant with this code:

myComponent.addEventListener(LoginEvent.LOGIN, loginHandler);

The ActionScript class in Listing 7.8 declares custom properties and event name constants.

package events
{
    import flash.events.Event;
    public class LoginEvent extends Event
    {
    public var username:String;
    public var password:String;
    public static const LOGIN:String="login";
    public function LoginEvent(type:String,
    bubbles:Boolean=false, cancelable:Boolean=false)
    {
    super(type, bubbles, cancelable);
    }
    }
}

The Event class has a method named clone() that's used during the bubbling process to create new copies of the event object for each level of bubbling. As described previously, the event object's currentTarget property changes its value each time the event is dispatched to point to the container or control that's currently dispatching the event. By creating a new copy on each dispatch, the currentTarget for previous versions of the event object doesn't change.

override public function superMethod():void
{}

If you don't include the override keyword and the method name matches one that's already declared in the current class's inheritance hierarchy, the compiler generates an error.

Keep in mind these rules for overriding the clone() method:

The clone() method for the LoginEvent class would look like this:

override public function clone():Event
{
    var newEvent:LoginEvent = new LoginEvent(type);
    newEvent.username = username;
    newEvent.password = password;
    return newEvent;
}

Notice that the current object's type property (the name of the current event) is passed to the new copy of the event object in the constructor method call.

super(type, true, cancelable);

When you dispatch a custom event class, follow these steps, which are the same as for pre-built event classes in the Flex framework:

To declare a custom event named login that dispatches an instance of the LoginEvent class described above, the code within the custom Form component would look like this:

<mx:Metadata>
    [Event(name="login", type="events.LoginEvent")]
</mx:Metadata>

At runtime, you would create an instance of the event class, passing the event name into the constructor method:

var e:LoginEvent = new LoginEvent("login");

The next step is to populate the event object with data. Assuming you have TextInput controls with their id properties of userNameInput and passwordInput, the code would be:

e.username = userNameInput.text;
e.password = passwordInput.text;

Finally, dispatch the event just as you would with one of the pre-built event classes:

dispatchEvent(e);

Listing 7.9 shows a Form component that declares and dispatches the custom event using the custom event class.

<?xml version="1.0" encoding="utf-8"?>
<mx:Form xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Metadata>
    [Event(name="login", type="events.LoginEvent")]
    </mx:Metadata>
    <mx:Script>
    <![CDATA[
    import events.LoginEvent;
    private function doLogin():void
    {
    var e:LoginEvent = new LoginEvent("login");
    e.username = userNameInput.text;
    e.password = passwordInput.text;
    dispatchEvent(e);
    }
    ]]>
    </mx:Script>
    <mx:FormItem label="User Name:">
    <mx:TextInput id="userNameInput"/>
    </mx:FormItem>
    <mx:FormItem label="Password:">
    <mx:TextInput id="passwordInput"/>
    </mx:FormItem>
    <mx:FormItem>
    <mx:Button label="Log In" click="doLogin()"/>
    </mx:FormItem>
</mx:Form>

You handle an event that uses a custom event class in two ways-the same as with the Flex framework's pre-built event classes:

In either case, you create a custom event handler function that expects an event argument typed as your custom event class:

private function loginHandler(event:LoginEvent):void
{}

import events.LoginEvent;

Within the event handler function, extract data as needed. The complete event handler function might look like this:

private function loginHandler(event:LoginEvent):void
{
    messageLabel.text = "You logged as " + event.username +
    " with a password of " + event.password;
}

Then, to call the event handler function, use an MXML-based event handler, as in:

<components:LoginForm login="loginHandler(event)"/>

Or, if you prefer to use addEventListener(), call this code as the application starts up:

myForm.addEventListener(LoginEvent.LOGIN, loginHandler);

Either way, the loginHandler() function is called and the data is delivered to the application.