Using event subclasses

Depending on the event type, the Event object can have a wide range of properties. These properties are based on those defined in the W3C specification http://www.w3.org/TR/DOM-Level-3-Events/), but Flex does not implement all of these.

When you declare an Event object in a listener function, you can declare it of type Event, or you can specify a subclass of the Event object. In the following example, you specify the event object as type MouseEvent:

public function performAction(e:MouseEvent):void { 
    ... 
}

Most controls generate an object that is of a specific event type; for example, a mouse click generates an object of type MouseEvent. By specifying a more specific event type, you can access specific properties without having to cast the Event object to something else. In addition, some subclasses of the Event object have methods that are unique to them. For example, the LogEvent has a getLevelString() method, which returns the log level as a String. The generic Event object does not have this method.

An event object that you define at run time can be a subclass of the compile-time type. You can access the event-specific properties inside an event listener even if you did not declare the specific event type, as long as you cast the Event object to a specific type. In the following example, the function defines the object type as Event. However, inside the function, in order to access the localX and localY properties, which are specific to the MouseEvent class, you must cast the Event object to be of type MouseEvent.

<?xml version="1.0"?>
<!-- events/AccessEventSpecificProperties.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"
    initialize="addListeners()">

    <s:layout> 
        <s:VerticalLayout/> 
    </s:layout>

    <fx:Script>
        <![CDATA[
            import mx.controls.Alert;

            private function customLogEvent(e:Event):void {
                var a:MouseEvent = MouseEvent(e);
                Alert.show("Y: " + a.localY + "\n" + "X: " + a.localX);
            }

            private function addListeners():void {
                b1.addEventListener(MouseEvent.CLICK, customLogEvent);
            }
        ]]>
    </fx:Script>

    <s:Button id="b1" label="Click Me"/>

</s:Application>

The executing SWF file for the previous example is shown below:

If you declare the Event object as a specific type, you are not required to cast that object in the handler, as the following example shows:

private function customLogEvent(e:MouseEvent):void { ... }

In the previous example, you can also cast the Event object for only the property access, using the syntax shown in the following example:

<?xml version="1.0"?>
<!-- events/SinglePropertyAccess.mxml -->
<s:Application 
    xmlns:fx="http://ns.adobe.com/mxml/2009"    
    xmlns:mx="library://ns.adobe.com/flex/mx"     
    xmlns:s="library://ns.adobe.com/flex/spark"
    initialize="addListeners()">

    <fx:Script>
        <![CDATA[
        import mx.controls.Alert;
        private function customLogEvent(e:Event):void {
            Alert.show("Y: " + MouseEvent(e).localY + "\n" + "X: " + MouseEvent(e).localX);
        }

        private function addListeners():void {
            b1.addEventListener(MouseEvent.CLICK, customLogEvent);
        }
        ]]>
    </fx:Script>
    
    <s:Button id="b1" label="Click Me"/>

</s:Application>

The executing SWF file for the previous example is shown below:

This approach can use less memory and system resources, but it is best to declare the event’s type as specifically as possible.

Each of the Event object’s subclasses provides additional properties and event types that are unique to that category of events. The MouseEvent class defines several event types related to that input device, including the CLICK, DOUBLE_CLICK, MOUSE_DOWN, and MOUSE_UP event types.

For a list of types for each Event subclass, see the subclass’s entry in ActionScript 3.0 Reference for the Adobe Flash Platform.