Event handlers are so named because they catch, or handle, the events in a movie. An event handler is simply a function that is invoked automatically when a particular event occurs. We've learned that all events occur in relation to some object. Hence, in order to create an event handler, we must specify three things:
The object to which the event applies
The name of the event handler
The function to be executed when the event occurs (known as the event handler's callback function)
For example, suppose we want to animate a movie clip named ball by changing its position every time a frame passes in the Flash Player. If we define an onEnterFrame( ) handler for the ball clip, it will be executed once for each tick of the movie's frame rate. So, given a movie clip, ball, we can create an onEnterFrame( ) event handler for ball as follows:
Create a new empty Flash movie.
Create a new movie clip symbol, named ballSymbol, that contains a circle shape.
Place an instance of ballSymbol on Layer 1.
Name the ballSymbol instance ball.
On frame 1 of Layer 1 of the main movie timeline, attach the following code:
ball.onEnterFrame = moveDown;
function moveDown ( ) {
// Move the ball down 5 pixels with each frame.
this._y += 5;
}In this code, ball is the object to which the event applies, onEnterFrame is the event we wish to handle, and moveDown is the function that should run when onEnterFrame( ) occurs.
Notice that we assign the moveDown function reference, not the return value of a moveDown( ) function call, to onEnterFrame. Therefore, the function invocation operator ( ) must not be included.
// The following is incorrect! The ( ) operator must not be used. ball.onEnterFrame = moveDown( ); // The following is correct. ball.onEnterFrame = moveDown;
To be more succinct when assigning an event handler, we can specify the callback function with a function literal, as follows:
ball.onEnterFrame = function ( ) {
this._y += 5;
};
The ball example shows how to specify a handler for an clip from outside the clip (i.e., from the main timeline). To define an event handler for the current movie clip from a frame on its own timeline, use the following syntax instead:
this.theEventHandler = function ( ) {
statements
};
In general, then, the syntax of an event handler is either:
someObject.someEventHandler = function ( ) {
statements
};
in which case the event handler is defined as a function literal, or:
someObject.someEventHandler = someFunction;
in which case someFunction must also be defined elsewhere, as in:
function someFunction ( ) {
statements
}
The latter approach is preferred in situations where the event handler is added and removed repeatedly, or where multiple objects use the same function as an event handler.
Event handlers can also receive parameters generated by the event. For example, in the following code, a text field, userName_txt, defines an event handler, onSetFocus( ), that receives a reference to the previously focused text field via the parameter oldFocus. The handler uses oldFocus to color the previously focused text field black.
userName_txt.onSetFocus = function (oldFocus) {
// Color the previously focused field black.
oldFocus.backgroundColor = 0x000000;
// Color the newly focused field orange.
this.backgroundColor = 0xF5BF70;
}
Object-oriented programmers will recognize event handler syntax as identical to the syntax for defining an object method. This is not a matter of coincidence. Event handlers are, in fact, methods that happen to be invoked automatically by the interpreter. And since methods in ActionScript are object properties that store functions, the event handler format shown in our onSetFocus( ) example is known as an event handler property.
Within the body of an event handler callback function, the this keyword refers to the object for which the event was triggered. In our ball's onEnterFrame( ) handler, we used this to refer to the ball movie clip object, which we moved down by 5 pixels:
this._y += 5;
Similarly, in our userName_txt.onSetFocus( ) handler this refers to userName_txt:
this.backgroundColor = 0xF5BF70;
To remove an event handler from an object, use the delete operator as follows:
delete theObject.theEventHandler;
For example, executing the following code from the main timeline causes the ball movie clip to stop responding to the onEnterFrame( ) event:
delete ball.onEnterFrame;
If the code were attached to the ball movie clip itself, you could instead write:
delete this.onEnterFrame;
For a list of event handlers offered by a specific class or object, see the appropriate entry in the Language Reference. In particular, be sure to study the Button and MovieClip classes, which define the majority of user-interaction events. For example, to cause a submitForm( ) function to execute when a Submit button is pressed, we use:
submit_btn.onRelease = submitForm;
function submitForm ( ) {
// Validate data and send it to the server...
}
where submit_btn is the button object, the onRelease event is invoked when the button is pressed and then released, and submitForm( ) is a custom function that sends the form data to the server. For a complete form-submission example, see Chapter 17.
Event handlers are convenient, but they also suffer from a shortcoming: only one callback function can be registered (assigned) to an event handler at a time. That is, only one action can be performed for each event when using event handler properties. We'll learn how to overcome this limitation in the next section using listener events.
