Basic event handling -- Flash CS3

The technique for specifying certain actions that should be performed in response to particular events is known as event handling. When you are writing ActionScript code to perform event handling, there are three important elements you'll want to identify:

Any time you write ActionScript code to handle events, it will include these three elements, and the code will follow this basic structure (elements in bold are placeholders you'd fill in for your specific case):

This code does two things. First, it defines a function, which is the way to specify the actions you want performed in response to the event. Next, it calls the addEventListener() method of the source object, in essence "subscribing" the function to the specified event so that when the event happens, the function's actions are carried out. We'll consider each of these parts in more detail.

A function provides a way for you to group actions together, with a single name that is like a shortcut name to carry out the actions. A function is identical to a method except that it isn't necessarily associated with a specific class (in fact, a method could be defined as a function that is associated with a particular class). When you're creating a function for event handling, you must choose the name for the function (named eventResponse in this case), and you must also specify one parameter (named eventObject in this example). Specifying a function parameter is like declaring a variable, so you also have to indicate the data type of the parameter. There is an ActionScript class defined for each event, and the data type you specify for the function parameter is always the class associated with the particular event you want to respond to. Finally, between the opening and closing curly braces ({ ... }), you write the instructions you want the computer to carry out when the event happens.

Once you've written the event-handling function, you need to tell the event source object (the object that the event happens to--for example, the button) that you want your function to be called when the event happens. You do this by calling the addEventListener() method of that object (all objects that have events also have an addEventListener() method). The addEventListener() method takes two parameters:

Comments

sneakyimp said on Jan 21, 2008 at 10:02 PM :

There is a quick-start guide that appears to take text from this page here:
http://www.adobe.com/devnet/flash/quickstart/event_handling_as3/

Interestingly, THAT code refers to 'eventTarget' rather than 'eventSource.'

Neither that description nor this one describes clearly the role of the parameter EventType.EVENT_NAME. Does that name mean that of all events triggered by eventSource, we only want to run the eventResponse function when some other parameter somewhere matches a constant defined in the class EventType with the name EVENT_NAME?

It would be helpful to know more about that first parameter.

No screen name said on Jul 10, 2008 at 1:59 AM :

This is very confusing, even to those with other programming knowledge. This sentence makes no sense to me:

"There is an ActionScript class defined for each event, and the data type you specify for the function parameter is always the class associated with the particular event you want to respond to."

brsnyder117 said on Jul 14, 2008 at 2:13 PM :

A writer has rewritten this section of the page as follows; we will update the next rev of the docs accordingly. Thanks for your feedback.

When you're creating a function for event handling, you must choose the name for the function (named eventResponse in this case). You must also specify one parameter (named eventObject in this example). Specifying a function parameter is like declaring a variable, so you also have to indicate the data type of the parameter. (In this example, the parameter's data type is EventType.) Each type of event that you want to listen to has an ActionScript class associated with it. The data type you specify for the function parameter is always the associated class of the specific event you want to respond to. For example, a click event (triggered when the user clicks on an item with the mouse) is associated with the MouseEvent class. To write a listener function for a click event, you define the listener function with a parameter with the data type MouseEvent.

gausim said on Jul 28, 2008 at 11:08 AM :

I am confused. can u plz tell me that what is d role of "eventObject " in the above script..

and y we r using d "EventType.EVENT_NAME" in the addEventListener as we have already written whle declaring d function...

I m looking for ur reply

thanks
Gausim

Todays Past said on Jul 31, 2008 at 10:28 AM :

Problem: confusing

original: "Which object is the one the event is going to happen to?"
consider: "Which object is the event going to happen to?"

Joe ... Ward said on Aug 8, 2008 at 10:12 AM :

In this example "eventObject" is the name of the parameter that is passed to the event handler function, eventResponse. When creating an event handler, you must define a parameter of the expected class. So if your handler is going to be used to handle mouse clicks, you would make the parameter of type MouseEvent. The MouseEvent object has properties that give you information about the mouse event, such as where the click occurred, whether any modifier keys were down at the time, etc.

When an event, such as a mouse click, occurs within an event dispatching object, such as eventSource in the example, the object checks an internal list of registered functions for that event and calls each one in turn. The event dispatcher separates the list of functions to call based on the event type, which is the first parameter of the addEventListener() function.

So to use a more concrete example, if you have a clickable object (let's call it clickableObject), then you listen for and handle a mouse click event with the following code:

clickableObject.addEventListener( MouseEvent.CLICK, onClickFunction );

function onClickFunction( mouseEventObject:MouseEvent ):void{
trace( "Click offset = " + mouseEventObject.localX + ", " + mouseEventObject.localY );
}

The onClickFunction() traces the location of the click in relation to the clicked object using the mouseEventObject parameter.

To sum up the answer to your second question, EventType.EVENT_NAME is used in the addEventListener() function to tell the event dispatcher object (eventSource) that you want it to call your function when an event of that kind occurs. The listenr function must declare a parameter of the correct event class because that is the class of object that the dispatcher will pass to your function.

Note, EventType.EVENT_NAME is really just a string constant. For example, MouseEvent.CLICK equals "click". It is better to use the EventType.EVENT_NAME form, though, because then the compiler can tell you that you misspelled the name. If you called addEventlistener with "clllck", no error would occur, but your function would never be called since there is no such thing as a "clllck" event.