You can think of events as occurrences of any kind in your SWF file that are of interest to you as a programmer. For example, most SWF files support user interaction of some kind—whether it's something as simple as responding to a mouse click or something more complex, such as accepting and processing data entered into a form. Any such user interaction with your SWF file is considered an event. Events can also occur without any direct user interaction, such as when data has finished loading from a server or when an attached camera has become active.

In ActionScript 3.0, each event is represented by an event object, which is an instance of the Event class or one of its subclasses. An event object stores information about a specific event and contains methods that facilitate manipulation of the event object. For example, when Flash Player detects a mouse click, it creates an event object (an instance of the MouseEvent class) to represent that particular mouse click event.

After creating an event object, Flash Player dispatches it, which means that the event object is passed to the object that is the target of the event. An object that serves as the destination for a dispatched event object is called an event target. For example, when an attached camera becomes active, Flash Player dispatches an event object directly to the event target, which in this case is the object that represents the camera. If the event target is a display object on the screen, however, the event object is passed from the Stage up through the display object containers that contain the event target (the display list), until it reaches the event target. In some cases, the event object then "bubbles" back up the display list hierarchy along the same route. This traversal of the display list hierarchy is called the event flow. The event flow is not described in this QuickStart article; for more information see the list of resources at the end of the article.

Your code can listen for events using event listeners. Event listeners are the functions or methods that you write to respond to specific events. To ensure that your program responds to events, you must add event listeners either to the event target or to any display list object that is part of an event object's event flow.

Any time you write event listener code, it follows this basic structure (the elements in bold are placeholders you'd fill in for your specific case; more concrete examples follow):

        function eventHandlerFunction(eventObject:EventType):void
{
   // Actions performed in response to the event go here.
}
eventTarget.addEventListener(EventType.EVENT_NAME, eventHandlerFunction);


    

This code does two things:

It defines a function, which is the way to specify the actions that will be performed in response to the event.
It calls the addEventListener() method of the source object, in essence "subscribing" the function to the specified event so that when the event happens, the function's actions are carried out.

When the event actually happens, the event target checks its list of all the functions and methods that are registered as event listeners. It then calls each one in turn, passing the event object as a parameter.

You need to alter four elements in the preceding code to create your own event listener.

Change the name of the function to the name you want to use (this must be changed in two places, where the code says eventHandlerFunction)
Substitute the appropriate class name of the event object that is dispatched by the event you want to listen for (EventType in the code)
Substitute the appropriate constant for the specific event (EVENT_NAME in the listing)
Change the addEventListener() method call so that it's called on the object that will dispatch the event (replacing eventTarget in the preceding code)
Optionally, you can also change the name of the variable used as the function's parameter (eventObject in the code listing)

The following sections show examples of event handling code to give you an idea of some of the common event elements and possible variations available when you write event-handling code.

Clicking a button to play the current movie clip

The following example demonstrates creating a clickable button that is used to play a movie clip (for example, the main timeline in Flash). In the code listing, playButton is the instance name of the button, and this is a special name meaning "the current object" (which in this case is assumed to be a movie clip).

Example

        import flash.events.MouseEvent;

this.stop();

function playMovie(event:MouseEvent):void
{
   this.play();
}

playButton.addEventListener(MouseEvent.CLICK, playMovie);
    

Result

This content requires Flash To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player. To view this content, JavaScript must be enabled, and you need the latest version of the Adobe Flash Player.

To get the source files for this example, download click_to_play_source.zip from the top of the page, or right-click the SWF above and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as click_to_play_CS5.fla.

Detecting typing in a text field

The following example demonstrates using the textInput event of a text field to detect when the user enters text in the text field. In this example it simply writes the user's keystroke back to the screen. However, the same event could be used for more complex tasks. For example, the code could be expanded to automatically format text such as a phone number, or to check that the text matches certain allowable characters or formatting. In the following code listing, entryText is an input text field, and outputText is a dynamic text field.

Example

        import flash.events.TextEvent;

function updateOutput(event:TextEvent):void
{
   var pressedKey:String = event.text;
   outputText.text = "You typed: " + pressedKey;
}

entryText.addEventListener(TextEvent.TEXT_INPUT, updateOutput);
    

Result

To get the source files for this example, download detecting_typing_source.zip from the top of the page, or right-click the SWF above and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as detecting_typing_CS5.fla.

Clicking a button to navigate to a URL

This example shows how to create a button that, when clicked, navigates the browser to the specified URL. The button essentially behaves like a hyperlink in a web page. In this code listing, linkButton is the instance name of the button.

Example

        import flash.events.MouseEvent;

function gotoAdobeSite(event:MouseEvent):void
{
   var adobeURL:URLRequest = new URLRequest("http://www.adobe.com/");
   navigateToURL(adobeURL);
}

linkButton.addEventListener(MouseEvent.CLICK, gotoAdobeSite);
    

Result

To get the source files for this example, download click_to_navigate_source.zip from the top of the page, or right-click the SWF above and select Download Source from the context menu. The Flash Professional CS5 version of the FLA file is in the ZIP file as click_to_navigate_CS5.fla.

For more information

This article was adapted from the sections "Introduction to handling events" and "Event-handling examples" in Programming ActionScript 3.0. For more information about handling events in ActionScript 3.0, see the following resources:

Getting Started with ActionScript > Events in Learning ActionScript 3.0
Handling events in the ActionScript 3.0 Developer's Guide
Flex Quick Start: Handling events" in the Flex Developer Center

Event handling in ActionScript 3

by H. Paul Robertson

Content

Modified

Page tools

Requirements

User level

Required products

Sample files

Clicking a button to play the current movie clip

Detecting typing in a text field

Example

Clicking a button to navigate to a URL

Example

For more information

Related Flash Quick Starts

More Like This

Products

Solutions

Industries

Help

Learning

Ways to buy

Downloads

Company