ActionScript 3 event handling tutorial

This article or section is currently under construction

In principle, someone is working on it and there should be a better version in a not so distant future.
If you want to modify this page, please discuss it with the person working on it (see the "history")

Overview

Learning goals

Learn how to understand the event handling model of Flash 9 (CS3) / ActionScript 3.

Learn some Action Script 3 (to be used within the Flash IDE)

Prerequisites

Flash CS3 desktop tutorial

Flash drawing tutorial

Flash components tutorial

Moving on

The Flash article has a list of other tutorials.

Quality

This text should technical people get going and may not be good enough for self-learning beginners. It can be used as handout in a "hands-on" class. That is what Daniel K. Schneider made it for...

Level

It aims at beginners. However at some point you really should buy introductory book to ActionScript programming. We won't be able to really teach you programming.

Learning materials

Grab the various *.fla files from here:

http://tecfa.unige.ch/guides/flash/ex/action-script-3-intro/

Introduction

According to the Flash CS3 documentation, retrieved 12:43, 7 September 2007 (MEST):

Every component broadcasts events when a user interacts with it. When a user clicks a Button, for example, it dispatches a MouseEvent.CLICK event and when a user selects an item in a List, the List dispatches an Event.CHANGE event. An event can also occur when something significant happens to a component such as when content finishes loading for a UILoader instance, generating an Event.COMPLETE event. To handle an event, you write ActionScript code that executes when the event occurs.

Below a few basic principles

Principles of event driven programming

Events are broadcasted by the instance.

That implies that you should give a name to each symbol instance. Otherwise your AS code can't find them.

• So before you code anything in ActionScript, click on the instance, open the parameters window and fill in label parameter.

This name must be legal:

• Start the label name with a letter
• Do not use whitespaces or punctuation characters or dashes

All ActionScript goes to the timeline

AS2 also would allow you to attach code to instances. You can't do this.

• Always put AS code into a separate layer, e.g. call it "Action"

For simple stuff, just put it in frame 1

• Click on frame 1 of the "Action" layer
• Hit F9, then code :)

Code will only work within the frames the layer extends to. So if your code is supposed to be valid throughout the animation.

• Go to the last Frame
• Hit F5

Event registration

For each event (user action or something else) you would like to intercept, you must register a so-called event listener.

The syntax is the following:

addEventListener(Type_of_event.Name_of_event Name_of_function_YOU_define);

(Note: I am sure if all require the same arguments)

Example:

• Let's say you have a button instance. In the parameters panel you named it hello_button.
• If you want to tell the button to watch out for user clicks then you have to write something like to register the event.
• So goto the ActionScript layer and hit F9. Then type:

hello_button.addEventListener(MouseEvent.CLICK, click_handler);

Programmers (only): You should be aware that a a component's events inherit from the parent classes. You also can remove a listener with the removeEventListener()

The Event handler function

The event handler function (also called a callback function) will be called by Flash as soon as the event happens. The function you have to define yourself will receive the following:

• A single object that will contain information about the event type and the instance (e.g. the hello_button in our case).
• In other words, the function will know "what" happened and "where".

For this kind of information the event handler function can receive you must write code that deals with it, e.g. moves to playhead in the timeline to another frame.

See below ....

Multiple events, multiple listeners

• You can register multiple listeners to one instance.
• You can register the same listener to multiple instances.

The event object

The event object contains at least the following information:

The Event type

type - a string indicating the type of event

target - the instance that sent the event (i.e. a reference to it).

Since target refers to an object you then can extract information from it, e.g. its label (if it has one).

The event handler function

After you registered an event handling function like

hello_button.addEventListener(MouseEvent.CLICK, click_handler);

you then have to define this function. E.g. if we called our function click_handler we get the following template:

function click_handler(event_object:MouseEvent) {

 /* Do something with this event */

}

event_object is a variable name (we came up with) and that will contain the name of instance we defined, e.g. hello_button in our case.

A simple example

From the Flash button tutorial. When a user clicks on the "launch_button", then the launchRocket function is called. It will move the animation to Frame 2 and let it play.

launch_button.addEventListener(MouseEvent.CLICK,launchRocket);

function launchRocket(event:MouseEvent) { gotoAndPlay(2); }

An example

This is the copy/pasted example from the Flash components tutorial.

We first register an event handling function with five different buttons.

btn_rainbow.addEventListener(MouseEvent.CLICK, clickHandler);
btn_tecfa.addEventListener(MouseEvent.CLICK, clickHandler);
btn_bosses.addEventListener(MouseEvent.CLICK, clickHandler);
btn_my_computers.addEventListener(MouseEvent.CLICK, clickHandler);
btn_credits.addEventListener(MouseEvent.CLICK, clickHandler);

The function itself looked like this:

function clickHandler(event:MouseEvent):void {
	switch (event.currentTarget.label)
	{
		case "Rainbow" :
			gotoAndStop(2);
			break;
		case "TECFA" :
			gotoAndStop(3);
			break;
		case "Bosses" :
			gotoAndStop(4);
			break;
		case "My computers" :
			gotoAndStop(5);
			break;
		case "Credits" :
			gotoAndStop(6);
			break;
	}
}

The function will receive an object that contains information about the event.

Let's now look at the first line. What does it mean ?

function clickHandler(event:MouseEvent):void {

• The function is called clickHandler (we can give it any name we like)
• The event object it will receive for processing when something happens is associated with event. In more technical terms event is a parameter that you can use as a variable in subsequent code.
• MouseEvent is the type of the event variable and we do have to declare this.
• :void means that the function will not return any information.

Non-programmers: Just insert these last two elements the same way and don't worry.

switch is a programming statement that is use to organize program flow. In other words, we need to take different action for different user input. Its syntax is the following:

switch (value) {
  case value_1 :
    /* do something */
    break;
  case value_2 :
    /* do something */
    break;
  ....
  }

So event.currentTarget.label means that we ask the event object event its current target (i.e. the button on which the user clicked) and from this its label (i.e. what the user sees). This will allow us to figure out which button was clicked.

Mouse events

All display objects with which you can interact: mouse, keyboard, and focus.

• InteractiveObject (Adope ActionScript 3.0 Language and Components Reference)

Here is a list of mouse event properties:

CLICK

Dispatched when user presses and releases the main button of the user's pointing device over the same InteractiveObject.

DOUBLE_CLICK

Dispatched when user clicks twice in rapid succession over the object

FOCUS_IN

Dispatched after a display object gains focus

FOCUS_OUT

Dispatched after a display object loses focus. This happens when a user highlights a different object.

MOUSE_DOWN

a user presses the pointing device button over an InteractiveObject instance in the Flash Player window

MOUSE_FOCUS_CHANGE

Dispatched when the user attempts to change focus by using a pointer device.

MOUSE_MOVE

a user moves the pointing device while it is over an InteractiveObject.

MOUSE_OUT

Dispatched when the user moves a pointing device away from an InteractiveObject instance.

MOUSE_OVER

Dispatched when the user moves a pointing device over an InteractiveObject instance in the Flash Player window.

MOUSE_UP

Dispatched when a user releases the pointing device button over an InteractiveObject instance in the Flash Player window

MOUSE_WHEEL

Dispatched when a mouse wheel is spun over an InteractiveObject instance in the Flash Player window. If the target is a text field, the text scrolls as the default behavior.