Recipe 13.10. Performing Actions When the User Clicks a Button

Problem

You want Flash to do something when the user clicks a button.

Solution

Add ActionScript that creates a listener object and registers the listener object with the button instance. Alternatively, if you've used a button symbol instance or a movie clip symbol instance, add an onRelease( ) event handler method.

Discussion

For Flash to be responsive to the user's mouse clicks, you're going to need to write some ActionScript. The ActionScript you'll need to write is not particularly long, however. The details of the ActionScript you'll write depend, in part, on which type of button you've used.

If you've used a Button component:

1. Create a listener object.

2. Assign a click( ) method to the listener object.

3. Register the listener object with the button instance.

A listener object is a code-based construct that basically sits around waiting (listening) for a component to do something. This something for which the listener is waiting is called an event. If the component performs the particular type of event for which the listener is configured, then the corresponding code on the listener object runs. Each type of component can dispatch different types of events. The button component dispatches an event called click when the user clicks it. The way that the listener object knows what code to run at that point is by looking for a method (a group of actions) called click( ).

That may all sound a bit confusing, but a simple example will illustrate that it really does not require too much code. First you need to create the listener object. The following line of code creates an object named oListener:

 var oListener:Object = new Object(); 

Next, define a method that corresponds to the event for which you want the object to listen. In this example, the listener should listen for a click event. Inside the curly braces of the method definition is where you should place the code that should run when the event is dispatched. In this example, Flash will call the trace( ) statement to display a message in the Output panel during testing:

 oListener.click = function(oEvent:Object):Void {   trace("The button was clicked"); }; 

Then, register the listener object with the component instance for the particular type of event. Call the addEventListener( ) method from the component instance and pass it two parameters: the name of the event as a string and a reference to the listener object. For example, to register oListener to listen for click events dispatched by a button named cbtSubmit, use the following code:

 cbtSubmit.addEventListener("click", oListener); 

That covers the basics of listener objects and handling component events. Even though the code may be unfamiliar to you at first, once you have learned it, you'll be able to reapply it to just about all of the components. That's because just about all of the components dispatch events and work with listener objects in the same way. The primary difference in different scenarios has only to do with the name of the event that is being handled.

If you've used a button symbol instance or a movie clip symbol instance, you still need to write some ActionScript code to perform some actions when the user clicks the button. However, the code you will need to write is quite different from the code for a Button component. You don't need to use listener objects at all. Instead, you should define an onRelease( ) event handler method for the instance. Within the onRelease( ) event handler method (between the curly braces) is where you can place all the code that you want to run when the user clicks on the button. The following example defines an onRelease( ) event handler method for a button instance named btSend:

 btSend.onRelease = function():Void {   trace("You have clicked the send button"); }; 

The preceding example displays the message "You have clicked the send button" in the Output panel while testing the movie. You could replace the trace( ) statement with any other ActionScript code that you want to run when the button is clicked, but in any case the rest of the syntax remains the same. You can read more details on working with button event handler methods in Chapter 9.

See Also

Recipe 13.7