Event Handling Contributed by David Stiller (www.quip.net)
WHEN SOMETHING OCCURS in a Flash movie, the occurrence is called an event. Events can be triggered by something in the Flash Player itself (system events) or by interaction from the person enjoying your content (user events). System events include, for example, the completion of an audio file or the incidence of a timeline frame. Let’s explore that second one for a moment. Think of the playhead in terms of a car. When the playhead moves along the timeline, like a car driving along the street, it dispatches an “enter frame” event at a rate comparable to the movie’s frame rate (by default, 12 frames per second). The event is simply a behind-the-scenes message that states, “Hey, I just entered a frame!” This happens, by the way, even if a stop() action tells the timeline to halt. If a car arrives at a duck crossing and hits the brakes, its engine continues to idle, after all. At any time, you can program other objects to react to this event. We’ll build up to this ourselves in just a bit. First, let’s respond to some user events.
When a user clicks one of your buttons, a number of mouse-related events are dispatched in much the same way as above. One event happens when the mouse is pressed, another when the mouse is released and, depending on the version of ActionScript you’re using, yet another when the mouse is pressed inside a button symbol but released outside of it. In all of these cases, the event happens whether you respond to it or not. If you do respond – this is called event handling – you need to write a function for it.
1 Let’s say you’ve paused the timeline at frame 20 with a stop() action. From that point forward, you’re halting the timeline every ten frames, because you want to give the user a chance to read something important on each of those keyframes. You have the stop() part down, but how do you get the timeline moving again?
2 Since you’re planning to use a button, you’ll need to put a button symbol on the stage. Use the Property inspector to give your button an instance name – that’s what allows ActionScript to call out this particular object from all the others and use that instance name to tell the button what to do. In this example the instance name is myButton.
3 In ActionScript 3.0, the main way to associate an event handler function with an event is the addEventListener() method. In this case, we’re “wiring up” the myButton instance by way of two parameters. The first parameter specifies what event to listen for and the second defines the function to perform.
4 These parameters can be simple, such as the event part MouseEvent. MOUSE_UP or fairly complex, such as the complete definition of a function, which might otherwise stand on its own.
5 Putting the pieces into place, these parameters would fit as shown. Use the Actions panel to type the following code into a keyframe at frame 1.
6 You could optionally use a named function, like this. See the difference? In this second approach, you’re defining the function as an entity of its own, a custom function arbitrarily named startTimeline(), then using that function’s name as the second parameter. Notice that it doesn’t matter how many lines it takes to code up the addEventListener() method. As long as you provide the two parameters it’s looking for, you’re good.
Hot Tip
The version of ActionScript you’re using determines how this function is associated with the event at hand. Every object has its own selection of events, and these are listed in the relevant ActionScript Language Reference entry for the object in question.
7 This ActionScript appears in frame 1 in a layer named “scripts,” while the myButton symbol appears in its own layer, but also in frame 1. That’s the important part, that they line up vertically; that is, they both appear in frame 1, so that they can “see” each other, otherwise the code and the button can’t be associated. They might both appear in frame 2 or frame 10, it doesn’t matter – as long as they line up.
ActionScript 2.0
ActionScript 2.0 handles things a bit differently. If you’re publishing for Flash Player 8 or earlier, you can’t use ActionScript 3.0 (only Flash Player 9 contains AVM2, the virtual machine that understands AS3). If your project specs require Flash Player 8 or back to Flash Player 6, here’s a more “old-fashioned” approach to the previous scenario.
Or...
8 This time, the pattern is myButton.onRelease = function; and here, too, the function can be dictated right in the event handler or defined elsewhere as a named function.
9 Let’s make sure we’re caught up on the nitty-gritty details. In the AS3 version, the event handler function receives a parameter that the AS2 version’s function does not, captured here under the arbitrary name evt.
What’s going on here? In this version of the language, every event carries with it an event object. In this sample, that incoming object isn’t actually being used – we’re just having the function execute a native play() action – but AS3 is pretty strict, so the function needs to at least let that object “in the door” even if it just sits there. The type of object matters, and this is a MouseEvent, so that explains the :MouseEvent suffix after evt. Finally, there’s that :void business at the end. In AS3, type matters not only for incoming objects, but also for outgoing objects. This is a function, and functions either return a value or they don’t. This function does not – it just performs an action, then quits – so the :void suffix lets AS3 know not to look for a return value. In the AS2 version, you’ll notice the :void suffix starts with an upper case letter. It’s just one of those things. In AS2, all datatype suffixes start that way. In AS3, most do, but a handful don’t, and those are all lower case. Yes, it’s like learning state capitals back in grade school, but there are only three all-lower case examples: int (integers), uint (unsigned integers) and void.
10 In both AS3 and AS2, neither of these named function approaches (above) uses parentheses after the startTimeline() function. What gives? The reason for this omission is that the parentheses actually carry out whatever the function does. By leaving them off in these lines, you’re telling ActionScript to carry them out when the event occurs, rather than when the playhead encounters them.
11 In the Help files, which open in a browser, look up “on handler” and “onClipEvent handler,” then use the “Refine results” area to filter your search for ActionScript 2.0, which covers both AS1 and AS2. To look up the AS2 events for buttons, search “Button class”; for movie clips, search “MovieClip class”. You’ll find even more events to pick from! For ActionScript 3.0, filter the Help books appropriately and look up button events under “SimpleButton” and movie clip events under “MovieClip”. When you see a hyperlink under the Events heading (Show Inherited Events), click it. Believe it or not, buttons support around 30 events in AS3 – the exact number depends on the version of Flash Player you choose – so bear in mind that each new version of the language gives you greater control. In addition, the AS2 and AS3 approaches allow you to reassign and even cancel event handlers after the movie is compiled. The full list for each of these can be found in the built-in documentation and in the live docs: http://help.adobe.com/en_US/AS3LCR/Flash_10.0/flash/display/MovieClip.html
Hot Tip
The Flash 5era on() and onClipEvent() functions are not supported by ActionScript 3.0, so if you see those in sample code online, be prepared to upgrade the general principles to the format shown here.