The concept of event listeners is pretty simple. Essentially, you tell an object to listen for an event and react if that event occurs. Imagine that you’re sitting in a busy airport. Lots of things are going on around you, all of which can be thought of as events. If you had no particular reason to be at the airport, you might ignore all of these events. They would still occur, but you would not listen for them.

However, if you’re scheduled to depart on an upcoming flight, you might establish a few listeners. For example, you might listen for a loudspeaker announcement about your flight number but ignore everything else. Or, you might also listen for a loudspeaker announcement about your destination city. You might even plan to listen for a third event: the inclusion of your airline in an announcement.

In all cases, the reaction to these events would be to pay attention to the announcement hoping to learn more about your flight. Other events might still occur in the airport, including other announcements, but without listening for those events, they would wash over you without reaction.

ActionScript 3.0 event listeners work much the same way. Creating an event listener, in its most basic form, is fairly straightforward. The first item needed is the object that will listen for the event. A button is a good example to start with. The addEventListener() method is then used to assign a listener to that object. This method requires two arguments. The first argument is an event to listen for—one that is appropriate for your goal. For example, it makes sense for a button to listen for a mouse event, but less so to listen for the end of a video or a resizing of the stage. The second argument is a function to execute when the event is heard.

Here’s an example of code that uses a button with the instance name rotate_right_btn and a function called onRotateRight(). This can be found in the simple_event_listener.fla source file.

1    rotate_right_btn.addEventListener(MouseEvent.MOUSE_UP, onRotateRight);
2    function onRotateRight(evt:MouseEvent):void {
3        box.rotation += 20;
4    }

The event this code is listening for is a mouse up event—that is, when the mouse button is released while over the button. In ActionScript 3.0 syntax, events are typically grouped together in classes, and the event itself is usually defined as a constant—a variable that cannot be changed after it’s defined. Using constants, when you know a value will never change, reduces errors because the compiler will warn you if you try to change them. Constants are usually typed in all uppercase letters, with multiple words separated by underscores.

The MouseEvent class contains constants that refer to mouse events like MOUSE_UP and MOUSE_DOWN. Other examples of events are ENTER_FRAME, found in the Event class and used to react to playhead updates, and KEY_UP, found in the KeyboardEvent class, for reacting to user keyboard input. We’ll look at both of these events later on in this chapter.

The second argument in the addEventListener() method, the function that is called when the event is received, is listed by name only, without the trailing parentheses. This is because you are referring to the function, not actually calling it. The listener will do that for you when the event is received. In this example, onRotateRight refers to the onRotateRight() function, defined in lines 2 through 4.

You will probably be familiar with the structure of this function from the discussion about functions in Chapter 2. To review the syntax, the braces define the function’s contents. In this case, line 3 adds 20 degrees to the current rotation value of the movie clip box. Also explained in Chapter 2, the void that follows the function name and parentheses indicates that no value is returned by the function.

However, new to our discussion of functions (see Chapter 2 if needed) is the fact that when functions are used in event listeners, the function requires a single parameter. This parameter receives information not from any ActionScript you write, but rather from the event. In this case, we arbitrarily named the parameter evt. (You may also see e or event used in other resources, but any valid parameter name will work.)

Without a parameter in place to receive that incoming data, you will get an error that says something like, “Argument count mismatch. Expected 0, got 1.” It will also tell you which function has the problem to make it easier to find. The error means that the function expected no arguments coming in, because no parameters were defined. Instead, one argument was received, resulting in a mismatch.

You’ll get used to this quickly, and reap the benefits. The data received usually contains useful information about the event and element that triggered the event. You can parse this information for use in the function. In keeping with good error reporting, the parameter should have a data type that matches the type of data being sent into the function. In this case, the event that triggered the listener was of type MouseEvent. Using this as the parameter data type will make sure that the listener receives only a MouseEvent, or the compiler will warn you to the contrary.

To illustrate the use of this argument data, let’s look at another mouse event example, found in the start_stop_drag.fla source file. This time, however, we’ll use two events, and use the incoming information to identify the target of the event—speaking generically, the object at which the event occurred. Specific to this case, the target is the object that was clicked.

1    myMovieClip.addEventListener(MouseEvent.MOUSE_DOWN, onStartDrag);
2    myMovieClip.addEventListener(MouseEvent.MOUSE_UP, onStopDrag);
3    function onStartDrag(evt:MouseEvent):void {
4        evt.target.startDrag();
5    }
6    function onStopDrag(evt:MouseEvent):void {
7    stopDrag();
8    }

In this example, two event listeners are assigned to a movie clip in lines 1 and 2. One listens for a mouse down event, another listens for a mouse up event. They each invoke different functions. In the first function, the target property of the event, which is parsed from the function argument, is used to identify which object received the mouse event. This allows the onStartDrag() function in lines 3 through 5 to start dragging the movie clip that was clicked. The onStopDrag() function in lines 6 through 8 then stops all dragging when the movie clip receives a mouse up event.

The best thing about this example is that the target property identifies the movie clip without an instance name. This generic approach is very useful because it makes the function much more flexible. The function can act upon any appropriate object that is clicked and passed into its parameter. In other words, the same function could start and stop dragging any movie clip to which the same listener was added. The following additional lines, adding the same functionality to a second movie clip called myMovieClip2, demonstrate this:

9    myMovieClip2.addEventListener(MouseEvent.MOUSE_DOWN, onStartDrag);
10    myMovieClip2.addEventListener(MouseEvent.MOUSE_UP, onStopDrag);

Finally, this example’s last modification demonstrates that more than one object can also call the same listener function. It is possible, while dragging an object, to move your mouse so quickly that the mouse up event occurs outside the bounds of the object you’re dragging. If that occurs, the object would not receive the mouse up event, and the drag would not be stopped.

One way to get around this is to attach another listener to the stage, and set that listener to also call the onStopDrag() function. This way, whether your mouse up occurs over the movie clip or over the stage, the dragging will cease.

11    stage.addEventListener(MouseEvent.MOUSE_UP, onStopDrag);

Now we can combine the syntax we’ve covered in the Properties and Events sections to set up interactive control over properties. In the chapter03 directory of the accompanying source code for this book, you’ll find a file called props_events_methods_ui.fla. It contains nothing more than the example movie clip box and two buttons in the library that will be used repeatedly to change the five properties discussed earlier. The movie clip contains numbers to show which of its frames is visible, and the instance name of each copy of the button on the stage reflects its purpose. Included are move_up_btn, scale_down_btn, rotate_right_btn, fade_in_btn, and toggle_visibile_btn, among others. Figure 3-3 shows the layout of the file.

Figure 3-3. Layout of the props_events_ui.fla file

Starting with movement, we need to define one or more functions to update the location of the movie clip. There are two common approaches to this task. The first is to create one function in the keyframe in frame 1 for all movement that uses a conditional to decide how to react to each event. We’ll demonstrate that when we discuss keyboard events. For now, we’ll use the simpler direct approach of defining a separate basic function for each type of movement, as shown in the following script:

1    function onMoveLeft(evt:MouseEvent):void {
2        box.x -= 20;
3    }
4    function onMoveRight(evt:MouseEvent):void {
5        box.x += 20;
6    }
7    function onMoveUp(evt:MouseEvent):void {
8        box.y -= 20;
9    }
10    function onMoveDown(evt:MouseEvent):void {
11        box.y += 20;
12    }

Once the functions are defined, all you have to do is add the listeners to the appropriate buttons.

13    move_left_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveLeft);
14    move_right_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveRight);
15    move_up_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveUp);
16    move_down_btn.addEventListener(MouseEvent.MOUSE_UP, onMoveDown);

This simple process is then repeated for each of the buttons on stage. The remaining script collects the aforementioned properties and event listeners to complete the demo pictured in Figure 3-3. The resulting file wires up one or more buttons for each property, all of which manipulate the movie clip in the center of the stage. The finished script can be found in the prop_events.fla source file.

17    scale_up_btn.addEventListener(MouseEvent.MOUSE_UP, onScaleUp);
18    scale_down_btn.addEventListener(MouseEvent.MOUSE_UP, onScaleDown);
19
20    rotate_left_btn.addEventListener(MouseEvent.MOUSE_UP, onRotateLeft);
21    rotate_right_btn.addEventListener(MouseEvent.MOUSE_UP,
22                                      onRotateRight);
23
24    fade_in_btn.addEventListener(MouseEvent.MOUSE_UP, onFadeIn);
25    fade_out_btn.addEventListener(MouseEvent.MOUSE_UP, onFadeOut);
26
27    toggle_visible_btn.addEventListener(MouseEvent.MOUSE_UP,
28                                        onToggleVisible);
29
30    function onScaleUp(evt:MouseEvent):void {
31        box.scaleX += 0.2;
32        box.scaleY += 0.2;
33    }
34    function onScaleDown(evt:MouseEvent):void {
35        box.scaleX -= 0.2;
36        box.scaleY -= 0.2;
37    }
38
39    function onRotateLeft(evt:MouseEvent):void {
40        box.rotation -= 20;
41    }
42    function onRotateRight(evt:MouseEvent):void {
43        box.rotation += 20;
44    }
45
46    function onFadeIn(evt:MouseEvent):void {
47        box.alpha += 0.2;
48    }
49    function onFadeOut(evt:MouseEvent):void {
50        box.alpha -= 0.2;
51    }
52
53    function onToggleVisible(evt:MouseEvent):void {
54        box.visible = !box.visible;
55    }

Listening for keyboard events is very similar to listening for mouse events, with one significant exception: The target of the event listener is not always the object you wish to manipulate. When working with text, the text field may indeed serve well as the target of the keyboard events. When controlling movie clips, however, the stage itself is often a useful, centralized recipient of keyboard events.

Adding an event listener to the stage means that you can process all key events with a single listener, and then isolate only the desired key events with a conditional, issuing instructions accordingly. To simplify the syntax of this demonstration, we’ll use the switch form of conditional statements. The switch statement, discussed in Chapter 2, is simply a more easily readable if/else-if conditional structure.

This script in the following example can be seen in the methods_events.fla file in the accompanying source code. We’ll start by adding the listener to the stage. In this case, we’ll be looking for the key down event, which is specified using a constant like all predefined events, KEY_DOWN. This time, however, it’s part of the KeyboardEvent class. When the event is heard, our listener will call the onKeyPressed() function.

1    stage.addEventListener(KeyboardEvent.KEY_DOWN, onKeyPressed);

Next, we define the onKeyPressed() function, being sure to type the incoming argument value as KeyboardEvent. Finally, we parse the incoming event information for the keyCode property. The keyCode is a unique number assigned to each key and allows you to determine which key was pressed.

To specify each key in our script, we’ll use constants defined in the Keyboard class that each contain key codes. Using these constants, when they suit your purpose, is easier than having to know the keyCode value for each key. For example, you can reference the Enter/Return key as Keyboard.ENTER, the left arrow key as Keyboard.LEFT, and so on.

We’ll use five keys to execute five methods. When each desired key is pressed, it will execute the appropriate method, and then break out of the switch statement. We’ll also add a default state that will trace the keyCode of any other key pressed. The final script segment looks like this:

2    function onKeyPressed(evt:KeyboardEvent):void {
3        switch (evt.keyCode) {
4            case Keyboard.ENTER:
5                box.play();
6                break;
7            case Keyboard.BACKSPACE:
8                box.stop();
9                break;
10            case Keyboard.LEFT:
11                box.prevFrame();
12                break;
13            case Keyboard.RIGHT:
14                box.nextFrame();
15                break;
16            case Keyboard.SPACE:
17                box.gotoAndStop(3);
18                break;
19            default:
20                trace("keyCode:", evt.keyCode);
21        }
22    }

The first four methods are basic movie clip navigation options: playing, stopping, or sending the movie clip to the previous or next frame in its timeline. The last method sends the movie clip to a specific frame and then stops its playback. The methods are probably self-explanatory, with only the last method even using an argument—in this case, the frame number. If you do want additional information, however, we’ll put these and other navigation options to use in Chapter 5 when we discuss timeline control.

The combined source file, props_methods_events.fla, includes both the properties and methods examples in this chapter.

Frame events are not triggered by user input the way mouse and keyboard events are. Instead, they occur naturally as the SWF plays. Each time the playhead enters a frame, a frame script is executed. This means that frame scripts execute only once for the life of the frame, making them an excellent location for seldom executed tasks, such as initializations. In other words, for a frame script to execute more than once, the playhead must leave the frame and return—either because of an ActionScript navigation instruction, or a playback loop that returns the playhead to frame 1 when it reaches the end of the timeline. Single-frame FLA files, therefore, execute their single frame scripts only once.

However, using an event listener, you can listen for a recurring enter frame event that some display objects have, including the main timeline, movie clips, and even the stage. An enter frame event is fired at the same pace as the document frame rate. For example, the default frame rate of an FLA created by Flash Professional CS4 and later is 24 frames per second, so the default enter frame frequency is 24 times per second. Using the enter frame event allows your file to update frequently—a handy thing for updating visual assets.

The frame_events.fla file in the accompanying source code demonstrates this event by updating the position of a unicycle every time an enter frame event is detected. It places the unicycle at the location of the mouse and, as a further review of properties, it rotates the child movie clip in which the wheel resides. Figure 3-7 demonstrates the effect. As you move your mouse to the right on the stage, the unicycle will move to the right, and the wheel will rotate clockwise.

Figure 3-7. Visual depiction of the unicycle movements

The code for this example follows. The first line adds an enter frame event listener to the main timeline, specifying the event using the ENTER_FRAME constant of the Event class. The function sets the unicycle’s x coordinate and rotation to the x coordinate of the mouse.

1    stage.addEventListener(Event.ENTER_FRAME, onFrameLoop);
2
3    function onFrameLoop(evt:Event):void {
4        cycle.x = mouseX;
5        cycle.wheel.rotation = mouseX;
6    }

An alternative to using enter frame events to trigger actions on a recurring basis is to use time-based events. Although it’s among the most straightforward options, using the enter frame event exclusively for this purpose has disadvantages. For example, Flash Player can reliably achieve only moderate frame rates—somewhere between the default 24 frames per second (fps) and perhaps 60 or so fps on the high end. Your mileage may vary, but that’s fairly accurate when averaging the CPU population at large. More importantly, the rate at which the enter frame fires is not always consistent.

On the other hand, time-based events are measured in milliseconds and can therefore sometimes fire more quickly. Further, time-based events don’t vary as much from scenario to scenario, so they are more reliable and consistent.

Previous versions of ActionScript used the setInterval() method for ongoing recurring events and the setTimeout() method for finitely recurring events. ActionScript 3.0 wraps up these approaches neatly behind the scenes of the new Timer class, simplifying the process of using timers.

The first step in using the Timer class is to create an instance of the class. Fortunately, creating instances in ActionScript 3.0 is very consistent, so this may look familiar. A variable is declared and typed using a data type that matches the class being instantiated. The new keyword creates a new instance of the class and that instance is stored in the variable:

var timer:Timer = new Timer(delay, repeatCount);

In this case, the class constructor can take two arguments. The first is mandatory and specifies the delay, in milliseconds, before the timer event is fired. The second is optional and is the number of times the event fires. Omitting the second argument will cause the event to fire indefinitely, each time after the specified delay. Using a positive value, such as 3, will cause the event to fire that finite number of times (again, after the specified delay).

In the sample timer_events.fla in the accompanying source code, the timer event (consistently specified as the constant TIMER in the TimerEvent class), occurs every second (or, in Timer units, every 1,000 milliseconds) and calls a function that increases the rotation of a hand nested inside a watch movie clip. The rotation increases 6 degrees every second, making one full 360-degree journey in 60 seconds.

1    var timer:Timer = new Timer(1000);
2    timer.addEventListener(TimerEvent.TIMER, onTimer);
3    timer.start();
4
5    function onTimer(evt:TimerEvent):void {
6        watch.hand.rotation += 6;
7    }

One important thing to note is line 3. The timer you instantiate does not start automatically. This gives you greater flexibility and control over your timer events. You can also stop the timer using the stop() method, and reset the timer using the reset() method. The latter stops the timer and also resets the repeat count to zero. For example, if you specified that the timer call a function five times, but reset it after the third call, the timer would begin counting again from zero rather than picking up from three at the point when it was reset. Figure 3-8 shows the watch used in timer_events.fla.

Figure 3-8. Use of the timer event in a stopwatch