PreviousNext

Using event handler methods

An event handler method is a class method that is invoked when an event occurs on an instance of that class. For example, the Button class defines an onPress event handler that is invoked whenever the mouse is pressed on a Button object. Unlike other methods of a class, however, you don't invoke an event handler directly; Flash Player invokes it automatically when the appropriate event occurs.

By default, event handler methods are undefined: when a particular event occurs, its corresponding event handler is invoked, but your application doesn't respond further to the event. To have your application respond to the event, you define a function with the function statement and then assign that function to the appropriate event handler. The function you assign to the event handler is then automatically invoked whenever the event occurs.

An event handler consists of three parts: the object to which the event applies, the name of the object's event handler method, and the function you assign to the event handler. The following example shows the basic structure of an event handler. 

object.eventMethod = function () {
  // Your code here, responding to event
}

For example, suppose you have a button named next_btn on the Stage. The following code assigns a function to the button's onPress event handler; this function advances the playhead to the next frame in the Timeline.

next_btn.onPress = function () 
  nextFrame();
}

In the above code, the nextFrame() function is assigned directly to onPress. You can also assign a function reference (name) to an event handler method and then define the function later.

// Assign a function reference to button's onPress event handler method
next_btn.onPress = goNextFrame;

// Define doSubmit() function
function goNextFrame() {
  nextFrame();
}

Notice that you assign the function reference, not the function's return value, to the onPress event handler.

// Incorrect!
next_btn.onPress = goNextFrame();
// Correct.
next_btn.onPress = goNextFrame;

Some event handlers receive passed parameters that provide information about the event that occurred. For example, the TextField.onSetFocus event handler is invoked when a text field instance gains keyboard focus. This event handler receives a reference to the text field object that previously had keyboard focus.

For example, the following code inserts some text into the text field that just lost keyboard focus.

userName_txt.onSetFocus = function(oldFocus_txt) {
  oldFocus_txt.text = "I just lost keyboard focus";
}

The following ActionScript classes define event handlers: Button, ContextMenu, ContextMenuItem, Key, LoadVars, LocalConnection, Mouse, MovieClip, MovieClipLoader, Selection, SharedObject, Sound, Stage, TextField, XML, and XMLSocket. For more information about the event handlers they provide, see these class entries in ActionScript Dictionary Overview.

You can also assign functions to event handlers for objects you create at runtime. For example, the following code creates a new movie clip instance (newclip_mc) and then assigns a function to the clip's onPress event handler.

_root.attachMovie("symbolID", "newclip_mc", 10);
newclip_mc.onPress = function () {
  trace("You pressed me");
}

For more information, see Creating movie clips at runtime.

PreviousNext