| MovieClip.onEnterFrame ( ) Event Handler | Flash 6 |
| handler executed at every tick of the frame rate in the Flash PlayerFlash 5; callback form introduced in |
The onEnterFrame( ) event
handler is the callback form (and more modern analogue) of the legacy
onClipEvent (enterFrame) event handler. The
onEnterFrame( ) handler is
executed once for every tick of the frame rate of a movie, such as
when the playhead advances or when the Player rerenders the current
frame while the playhead is stopped. In either case, the frequency of
the onEnterFrame( ) event
is directly related to the frame rate achieved by the Player. If the
frame rate specified at authoring time under Modify
Document is 20 frames per second, then a tick of
the frame rate will theoretically occur every 1/20th of a second. But
if the Player cannot display the movie at the frame rate specified
(for example, because the computer is too slow or has many
applications open), the actual frame rate will be lower and a tick
will be longer. For example, if the actual frame rate is 12 frames
per second, a tick will be 1/12th of a second. Note that a
tick is not a constant time measurement, nor is
it even a formal term in ActionScript (as it is in Lingo); it simply
denotes a single cycle of the frame rate in the Flash Player.
The following handler increases cloud_mc's size by 10 pixels per frame-rate tick:
cloud_mc.onEnterFrame = function () {
this._height += 10;
this._width += 10;
};
When displayed in the Flash Player, all Flash movies are constantly running, even when nothing is moving on screen or when a movie's playhead is stopped on a frame. Hence, an individual movie clip's onEnterFrame( ) handler will be executed repeatedly for as long as that clip is on stage, regardless of whether the clip is playing or stopped. If a clip's playhead is moved by a gotoAndStop( ) function call, the clip's onEnterFrame( ) event handler is still triggered with each passing frame. And if every playhead of an entire movie has been halted with a stop( ) function, all onEnterFrame( ) event handlers on all clips will still execute.
The onEnterFrame( ) event normally is used to update the state of a movie clip repeatedly over time. But an onEnterFrame( ) event handler need not apply directly to the clip that bears it—onEnterFrame( ) can be used on a movie's main timeline or on a single-frame, empty clip to execute code repeatedly. This technique, called a clip event loop (or, more loosely, a process) is demonstrated in Section 8.7. The setInterval( ) function is also a useful tool for repeatedly executing code.
To stop a callback from handling the onEnterFrame( ) event, use the delete operator to remove the handler, as in:
// Make sure to omit the () operator after the function name! delete theClip_mc.onEnterFrame;
Note that the code in an onEnterFrame( ) event handler is executed before any code that appears on the timeline of the clip containing the handler.
The following code extends our earlier example to make the cloud_mc clip grow to a specific size:
cloud_mc.maxHeight = 300
cloud_mc.onEnterFrame = function () {
if (this._height < this.maxHeight) {
this._height += 10;
} else {
delete this.onEnterFrame;
}
}