actionscript 3.0 for journalists

Using Event Listeners to call Functions

In the previous lesson, the Anatomy of a Function, we covered how to call a function using the function name and a set of parenthesis. However there is another way to call a function, and that is to use something called an event listener.

An event listener is like a trigger. This command waits or "listens" for a specific event, and when that event occurs, it will call a function.

In order to use an event listener, we must first setup an environment whereby an event occurs. Generally, the most common event in flash is the mouse click event. This event occurs whenever a person clicks on an object in flash, like a movieclip or a button. In this tutorial, we will first setup a basic button symbol in Flash that we will use as a trigger to display a message in our output window.

First, open Flash CS3 or CS4 and choose ActionScript 3.0 from the new document window.

New document window in Flash

Once in the new document we will create a simple text button to use for our example. Choose the text tool on your tool menu bar.

The text tool icon

You can adjust the font and color of your text as you wish in the properties window. Next, click on your stage and type in some dummy text to use for your button. Be sure your text is set for static text. This option will be displayed in your properties window. Dynamic text will not work inside a button.

text box on stage

Once you have your button set, make sure your text box is selected, then click on the modify menu at the top of the screen and select convert to symbol. For the symbol type we will choose button and give our symbol a unique name. This is not an identifier name used in ActionScript, but just a name for your own reference.

Convert to symbol dialogue box

Next is one of the more important steps. We need to give our button an instance name. An instance name is what identifies your button in ActionScript. It is case sensitive and must adhere to all of the same rules for variables names. (In fact, instance names are actually variable names themselves). Click on the button to select it, and in the properties box, we will name our button my_btn.

giving an instance name to our button

Now that we have our button instance name set, we can open our Actions window from the Window menu at the top of the screen and begin using the event listener features.

Event listener ActionScript code

Before we can type in the code for an event listener, we need to first have a function for our event listener to call. We will use the function from the previous lesson we made, but with one small change. In the parameter field, we must specify a variable with the datatype Event. We can call it anything we want. Most developers just use something short like "evt" or many times just the letter "e." The Event datatype might be a little confusing. Don't worry about it right now since we aren't really using this. It is more of a placeholder that Flash requires, even if you do not use the event.

function showMessage(e:Event):void {
       trace("You just clicked a button on the stage");
 }

Why do we need this Event variable as an argument? The reasons can be a little technical. In ActionScript 3.0 event listeners work by calling a function after an event occurs. But when they call that function, they automatically pass some data to that function in the form of something called an event object. In more advanced programming, we can use that event data within the function to reference the button or movieclip that was clicked on, as well as other properties.

Even if you don't use this event argument, you still must include it. Usually it is just a matter of including e:Event in the argument field each time you write a function that might be called by an event listener.

Next, we need to write out the event listener itself. Event listeners are always attached to some type of object that they are listening to. In this case, we are going to attach an event listener to the button we created. We do this through a process called dot syntax. We will learn more about dot syntax in the Object Oriented Programing lesson.

function showMessage(e:Event):void {
       trace("You just clicked a button on the stage");
 }

my_btn.addEventListener(MouseEvent.CLICK, showMessage);

Event listener with a function in ActionScript 3

The event listener consists of a pair of parenthesis and two arguments, separated by a comma. The first argument is the event that will trigger this event listener. The second argument lists the function that will be called once the event occurs. Note: there are other optional arguments that are beyond the scope of this tutorial.

Here are a list of some of the different mouse events you can listen for:

  1. MouseEvent.CLICK Triggers when the object is clicked and the mouse button is released.
  2. MouseEvent.DOUBLE_CLICK Triggers when the object is clicked twice rapidly.
  3. MouseEvent.MOUSE_DOWN Triggers as soon as the mouse button is pressed down on an object (release is not necessary)
  4. MouseEvent.MOUSE_UP Triggers any time the mouse is release over the object, even if it is pressed down outside the object.
  5. MouseEvent.MOUSE_OVER Triggers as soon as the mouse moves over the object, regardless if the button is pressed.
  6. MouseEvent.MOUSE_OUT Triggers when the mouse leaves the object, regardless if the button is pressed.

Test your movie and click on the button you created. Every time you click on the button, the function will run and you will see your text appear. You can put any code in this function that will execute once the button is clicked. Spend some time swapping out the different event types and see how they react to the mouse.

Listening for other type of events, like videos

Event listeners are not only for listening to mouse events like clicks. There are lots of objects in Flash that can trigger events, and thus execute a function. In this next example, we will setup a basic video player in Flash and add an event listener to listen when the video completes. In a more advanced program, this might be used to switch out the video or close the video after it is done playing.

First, start a new ActionScript 3.0 Flash document. In the Window menu at the top of the screen, select components.

Component pane in Flash CS4

Select the FLVPlayback listed under the video section, and drag it to your stage.

Video player in Flash CS4

The next step will require that you have saved your Flash document. Take note of the exact location you save your document. In order to load a video using the FLVPlayback component, the video must reside in the same location as your .fla file. You can download a sample video for this lesson here, or you can use your own video file as long as it was encoded in H.264. Make sure the sample video, countdown.flv is in the same location as your Flash document (.fla) file.

Next, select the Window menu at the top of the screen and choose component inspector. The component inspector will show you options related to your component when it selected. If you do not see the option in this image, select the video component on your stage.

component inspector in Flash CS4

Click on the source option in the component inspector, and click on the magnifying glass icon. In the next dialogue window, select the folder icon to browse to the location of your video file.

select source component dialogue box

In this example we will choose the countdown.flv sample file. Flash will read the meta data and set the correct video dimensions automatically. At this point, the video would play if we were to test our Flash project. Embedding video in Flash is that easy! But, since this is an ActionScript tutorial, we are not quite done yet. The next step is to select the video component on your stage and then give it the instance name of myVideo. The instance name box is located in your properties pane.

component instance name

With an instance name, we can now reference this component in ActionScript. Remember, all instance names must conform to the conventions outlined in the rules of variable naming.

Next, open your ActionScript dialogue box by selecting Actions under the Window menu at the top of the screen.

This time we are going to use an event that is not automatically included as a part of the core Flash package. We must use a line of code at the top of our ActionScript to include it. This is a common task in ActionScript 3.0, as it lets users include only code they need in each program.

Click on the layer named actions and open your Actions window. In the top of your action window, write out the line:

import fl.video.VideoEvent;

Next, we will type in our function from before, but this time we'll trace the output "Finished!" inside our function. For the event listener, we will listen to the video event COMPLETE.

function showMessage(e:Event):void {
 	trace("Finished");
 }

myVideo.addEventListener(VideoEvent.COMPLETE, showMessage);

ActionScript for detecting the end of a video

Test your movie, and click the play button if your video does not start automatically (the option to autoplay a video is located in the component inspector window). Once the video is completed, a message in your output window should let you know that the video is finished playing.

Now, you might be asking yourself how one is suppose to memorize all of these many event types. The truth is, no one does. It is all located in the Flash online documentation. We will cover how to sort through the documentation to find the commands and events you might need to run your programs. For now, try playing with some of the other video event types and see how they react when you use them. Simply replace the word "COMPLETE" with a different event type listed on Adobe's Online Documentation page on video events.