An event handler method is a method of a class that is invoked when
an event occurs on an instance of that class. For example, the
MovieClip class defines an onPress event handler that is invoked
whenever the mouse is pressed on a movie clip 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.
The following ActionScript classes are examples of classes that 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 the entries for each class in ActionScript 2.0 Language Reference. The word handler is added in the title of each event handler.
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 current timeline:
next_btn.onPress = function () { nextFrame();
}
Assigning a function reference:
In the previous code, the nextFrame() function is assigned to an event handler for onPress. You can also assign a function reference (name) to an event handler method and later define the function, as shown in the following example:
// Assign a function reference to button's onPress event handler.next_btn.onPress = goNextFrame;
// Define goNextFrame() function.function goNextFrame() { nextFrame();
}
Notice in the following example 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;
Receiving passed parameters:
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 a text field that no longer has keyboard focus:
this.createTextField("my_txt", 99, 10, 10, 200, 20);
my_txt.border = true;
my_txt.type = "input";
this.createTextField("myOther_txt", 100, 10, 50, 200, 20);
myOther_txt.border = true;
myOther_txt.type = "input";
myOther_txt.onSetFocus = function(my_txt:TextField) {
my_txt.text = "I just lost keyboard focus";
};
Event handlers for runtime objects:
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:
this.attachMovie("symbolID", "newclip_mc", 10);
newclip_mc.onPress = function (
)
{ trace("You pressed me");
Overriding event handler methods:
By creating a class that extends an ActionScript class, you can override event handler methods with the functions that you write. You can define an event handler in a new subclass that you can then reuse for various objects by linking any symbol in the library of the extended class to the new subclass. The following code overrides the MovieClip class's onPress event handler with a function that decreases the transparency of the movie clip:
// FadeAlpha class -- sets transparency when you click the movie clip.
class FadeAlpha extends MovieClip {
function onPress() {
this._alpha -= 10;
}
}
Using button and movie clip event handlers:
You can attach event handlers directly to a button or movie clip instance on the Stage by using the onClipEvent() and on() event handlers. The onClipEvent() event handler broadcasts movie clip events, and the on() event handler handles button events.
To attach an event handler to a button or movie clip instance, click the button or movie clip instance on the Stage to bring it in focus, and then enter code in the Actions panel. The title of the Actions panel reflects that code will be attached to the button or movie clip: Actions Panel - Button or Actions Panel - Movie Clip. For guidelines about using code that's attached to button or movie clip instances,
Do not confuse button and movie clip event handlers with component events, such as SimpleButton.click, UIObject.hide, and UIObject.reveal, which must be attached to component instances and are discussed in Using Components.
You can attach onClipEvent() and on() only to movie clip instances that have been placed on the Stage during authoring. You cannot attach onClipEvent() or on() to movie clip instances that are created at runtime (using the attachMovie() method, for example). To attach event handlers to objects created at runtime, use event handler methods or event listeners.
Attaching onClipEvent() and on() handlers is not a recommended practice. Instead, you should put your code in frame scripts or in a class file, as demonstrated throughout this manual. For more information,
The following ActionScript classes are examples of classes that 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 the entries for each class in ActionScript 2.0 Language Reference. The word handler is added in the title of each event handler.
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 current timeline:
next_btn.onPress = function () { nextFrame();
}
Assigning a function reference:
In the previous code, the nextFrame() function is assigned to an event handler for onPress. You can also assign a function reference (name) to an event handler method and later define the function, as shown in the following example:
// Assign a function reference to button's onPress event handler.next_btn.onPress = goNextFrame;
// Define goNextFrame() function.function goNextFrame() { nextFrame();
}
Notice in the following example 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;
Receiving passed parameters:
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 a text field that no longer has keyboard focus:
this.createTextField("my_txt", 99, 10, 10, 200, 20);
my_txt.border = true;
my_txt.type = "input";
this.createTextField("myOther_txt", 100, 10, 50, 200, 20);
myOther_txt.border = true;
myOther_txt.type = "input";
myOther_txt.onSetFocus = function(my_txt:TextField) {
my_txt.text = "I just lost keyboard focus";
};
Event handlers for runtime objects:
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:
this.attachMovie("symbolID", "newclip_mc", 10);
newclip_mc.onPress = function (
)
{ trace("You pressed me");
Overriding event handler methods:
By creating a class that extends an ActionScript class, you can override event handler methods with the functions that you write. You can define an event handler in a new subclass that you can then reuse for various objects by linking any symbol in the library of the extended class to the new subclass. The following code overrides the MovieClip class's onPress event handler with a function that decreases the transparency of the movie clip:
// FadeAlpha class -- sets transparency when you click the movie clip.
class FadeAlpha extends MovieClip {
function onPress() {
this._alpha -= 10;
}
}
Using button and movie clip event handlers:
You can attach event handlers directly to a button or movie clip instance on the Stage by using the onClipEvent() and on() event handlers. The onClipEvent() event handler broadcasts movie clip events, and the on() event handler handles button events.
To attach an event handler to a button or movie clip instance, click the button or movie clip instance on the Stage to bring it in focus, and then enter code in the Actions panel. The title of the Actions panel reflects that code will be attached to the button or movie clip: Actions Panel - Button or Actions Panel - Movie Clip. For guidelines about using code that's attached to button or movie clip instances,
Do not confuse button and movie clip event handlers with component events, such as SimpleButton.click, UIObject.hide, and UIObject.reveal, which must be attached to component instances and are discussed in Using Components.
You can attach onClipEvent() and on() only to movie clip instances that have been placed on the Stage during authoring. You cannot attach onClipEvent() or on() to movie clip instances that are created at runtime (using the attachMovie() method, for example). To attach event handlers to objects created at runtime, use event handler methods or event listeners.
Attaching onClipEvent() and on() handlers is not a recommended practice. Instead, you should put your code in frame scripts or in a class file, as demonstrated throughout this manual. For more information,
Posts
