Understanding the Listener Event Model for Components

While it's rather simple to drag and drop components on to the Stage of your Flash document and use the Property inspector to set up initial values for them, the result of any component behavior needs to be described by you, in your own ActionScript code. When the user interacts with a component, a specific event — tailored for the component — is sent out to the Flash movie. Just as you can yell when you're alone in a forest, these broadcasted events will just be ignored by the Flash movie unless you create something to listen to the events. Such objects are called listeners because their sole purpose is to intercept broadcasted messages from other objects that generate events — such as components.

What a Typical Listener Looks Like

Just about any object in a Flash movie can be a listener. You can add custom methods to MovieClip objects, for example, or you can create an instance of the Object class that exists only in ActionScript. To create a generic object, use the following syntax:

 var oListener:Object = new Object(); 

or

 var oListener:Object = {}; 

Note 

Since the components that ship with Flash 8 are built in ActionScript 2.0, you should get in the habit of using ActionScript 2.0 syntax for the code you use in movies using the components. If you use Flash 8 components, you must publish your Flash movie with ActionScript 2.0 selected in the Flash tab of the Publish Settings.

Once you have created an object that behaves as a listener, you can create methods for the listener geared toward the behavior of the component it observes. For example, if you wanted to do something when a Button component instance is clicked, you can add a click() method (or handler) to the listener object.

 oListener.click = function(oEvent:Object):Void {    trace("---listener received an event broadcast"); }; 

In this simple example, a trace() message is sent to the Output panel. You could add further actions to the click() method, performing more tasks necessary for your Flash movie.

Letting the Component Know Who its Listeners Are

Once a listener has a method to invoke, you need to assign the listener object (or its method) to the component that will be broadcasting events. For our previous example, you could assign the listener to a Button component instance named cbt by using the following code:

 cbt.addEventListener("click", oListener); 

or

 cbt.addEventListener("click", oListener.click); 

The addEventListener() method takes two parameters: the event being broadcast and the listener object (or method). Each component has its unique event names. The Button component, used in this example, has a click event, which is broadcast to all listeners when the user clicks the Button component instance.

Most components also broadcast additional information to the listeners, passed as parameters to the listener's method. All of the UI components pass an event information object to their listeners. The exact properties of this object vary from one component to the next, but some are consistent. In the following listener method, the oEvent parameter from the Button instance contains several properties, including oEvent.target, which is a reference to the Button instance.

 oListener.click = function(oEvent:Object):Void {    trace(oEvent.target + " was clicked.");    trace("The broadcasted event was  "+ oEvent.type); }; 

Note 

You can change the parameter name to any term you wish. In our example, the parameter is referred to as oEvent, but you can use a term such as eventObj. Just be sure to use the term consistently throughout your listener's method.

The type property, as you can see in the example code, can tell the listener what type of event was broadcast to it. In this way, you can create one method for a listener and have it handle different event types with specific code.

We'll show you how to create a simple example that demonstrates how a listener works:

1. Create a new Flash document, and save it as button_listener.fla.

2. Rename Layer 1 to cbt. This layer will hold an instance of the Button component.

3. Open the Components panel (Ctrl+F7 or z+F7) and drag an instance of the Button component from the User Interface set to the Stage.

4. Select the new instance, and in the Property inspector, name the instance cbt. Click the Parameters tab and assign a new label to the button, such as My Button.

5. Create a new layer named actions, and place it at the top of the layer stack.

6. Select frame 1 of the actions layer, and open the Actions panel (F9, or Option+F9 on Mac). Add the following code to the Script pane:

    var cbt:mx.controls.Button; var oListener:Object = new Object(); oListener.click = function(oEvent:Object):Void {    for(var i in oEvent){       trace(i + "= "+ oEvent[i]);    } }; cbt.addEventListener("click", oListener); 

7. Save your document, and test it (Ctrl+Enter or z+Enter). When you click the cbt instance, you should see the following text in the Output panel:

    target = _level0.cbt type = click 

   This output illustrates the two properties of the oEvent object broadcasted by the Button component. The event's name is "click" and the target property is a reference to the object broadcasting the event, cbt (_level0.cbt).

On the CD-ROM 

You can find the completed example file, button_listener.fla, in the ch33 folder of this book's CD-ROM.