Event handling in ActionScript 3.0

Event properties

Here is the basic rundown of common Event properties:

• type:String
• eventPhase:uint
• bubbles:Boolean
• cancelable:Boolean
• target:Object
• currentTarget:Object

Additional properties will apply to subclasses. MouseEvent instances, for example, also have a relatedObject property which describes a display object related to the current event (such as the display object you rolled off of to get to the current roll over event), among others.

Some of the properties should look familiar. Here is a description of the properties listed above:

• type: The type of event being handled. This is the same as the first parameter used to add the function as a listener in addEventListener. Ex: MouseEvent.CLICK.
• eventPhase: The current phase of the event. This is provided as a number that relates to the constants EventPhase.CAPTURING_PHASE, EventPhase.AT_TARGET, and EventPhase.BUBBLING_PHASE, depending on which phase the listener is being called.
• bubbles: Indicates whether or not the event is an event that bubbles (and captures). This does not mean that the event went through or is going through a capture or bubbles phase, but rather it is a kind of event that can. When clicking just the stage in the previous example, the event did not capture or bubble because stage was the only target. However, bubbles would still be true since the event was a mouse click.
• cancelable: Indicates whether or not an event is cancelable. Cancelable events are events that, by default, can result in additional consequences that can be stopped within an event handler. An example would be typing text in a text field to add characters to that field. By default, a character is added to the field every time a key on the keyboard is pressed or some other action occurs which causes the player to change the contents of a text field. A listener listening for a text input (TextEvent.TEXT_INPUT) event can recognize when this happens and cancel this default behavior. In such a case, the cancelable property would have a value of true.
• target: The object which Flash targeted for the event. This is the object that would receive the event in the at target phase.
• currentTarget: Refers to the object that is currently called by the listener when the event occurs. This is the same object on which addEventListener was called from when the listener was added.

These properties can be useful in determining specific actions that need to be taken for various events.

Example 3: Mouse up outside, ActionScript 3.0 style

One of the shortcomings of ActionScript 3.0 events is the lack of an equivalent to the ActionScript 2.0 onReleaseOutside event. You have mouse down and mouse up events for ActionScript 3.0, but nothing dealing with the release of an event outside of a previously clicked object. Instead, you have to use a little bit of trickery using the unique behavior of the stage to determine when the mouse is clicked on an object and then released outside of it.

There are a couple of approaches to achieve this. Here's the easiest method:

1. Detect a mouse down for the desired target.
2. In a mouse down event handler, add a listener to the stage for a mouse up.
3. In the stage mouse up listener, check to see if the target is the original object being clicked by checking the target property of the event object. If so, the mouse was released over the original target. If not, the mouse was released outside of that object.
4. Remove the stage listener within the mouse up listener.

Because the stage captures all mouse events you can be fairly certain that any mouse up event will be received by the stage. By adding a mouse up listener to the stage within the mouse down listener of the target object, you will know that the next time the mouse released it will be either for a mouse up over the original object clicked or outside of the object (a mouse up outside event).

Using Flash 9 Professional ActionScript 3.0 Preview

1. Open Example 2.

2. Replace the timeline script in Frame 1 with the following:

   function boxDown(event:MouseEvent):void {
     trace("box down");
     stage.addEventListener(MouseEvent.MOUSE_UP, boxUpOutside);
   }
   
   function boxUpOutside(event:MouseEvent):void {
     if (event.target != box) {
        trace("box up outside");
     }
     stage.removeEventListener(MouseEvent.MOUSE_UP, boxUpOutside);
   }
   
   box.addEventListener(MouseEvent.MOUSE_DOWN, boxDown);
   

Using Flex 2

1. Create a new Flex MXML document (or edit Example 2).

2. Use the following MXML:

   
              applicationComplete="initApp()">
     
                public function boxDown(event:MouseEvent):void {
              trace("box down");
              stage.addEventListener(MouseEvent.MOUSE_UP, boxUpOutside);
           }
   
           public function boxUpOutside(event:MouseEvent):void {
              if (event.target != box) {
                 trace("box up outside");
              }
              stage.removeEventListener(MouseEvent.MOUSE_UP, boxUpOutside);
           }
   
           public function initApp():void {
              box.addEventListener(MouseEvent.MOUSE_DOWN, boxDown);
           }
        ]]>
     
    
     
     
    
   
   

Test the movie and click on the box. Try clicking and releasing the mouse while it remains over the box. Then try clicking and dragging the mouse, releasing the mouse button while the cursor is outside the box. You should see an output of just "box down" when clicking on the box and an output of both "box down" and "box up outside" when clicking on the box and releasing off of the box, even if you release the mouse outside of the Flash Player window (this is specific to mouse up events associated with the stage).