| MovieClip.onLoad ( ) Event Handler | Flash 6 |
| handler executed when the clip first appears on the Stage or when a .swf file finishes loading into the clipFlash 5; callback form introduced in | | mc.onLoad() onClipEvent (load) { statements }
Description The onLoad( ) event handler is the callback form (and more modern analogue) of the legacy onClipEvent(load) event handler. The onLoad( ) event handler executes when a movie clip is born that is, when a movie clip appears on stage for the first time. It does not apply to main movies (e.g., _root, _level1, etc.). A movie clip appears on stage (i.e., it triggers an onLoad( ) event) in one of the following ways: -
The playhead moves onto a keyframe that contains a new instantiation of the clip, placed in the authoring tool. -
The clip is duplicated from another clip via the duplicateMovieClip( ) or MovieClip.duplicateMovieClip( ) function. -
The clip is added to the Stage programmatically via the attachMovie( ) function. -
An external .swf file is loaded into the clip with the loadMovie( ) or MovieClip.loadMovie( ) function. The body of an onLoad( ) event handler is executed after any code on the timeline where the movie clip first appears. When implemented as a Flash 5-style onClipEvent(load) block, the onLoad( ) event handler is often used to initialize variables in a clip or to perform some setup task (such as sizing or positioning a dynamically generated clip). An onClipEvent(load) handler can also provide a nice way to prevent a movie clip from automatically playing: // Code placed directly on a movie clip object at authoring time onClipEvent (load) { stop(); } An onClipEvent(load) handler can also be used to trigger some function that relies on the existence of a particular clip or loaded .swf file in order to execute properly.  | The callback form of onLoad( ) operates quite differently from onClipEvent(load) it has an effect only when assigned at the class level, not the instance level. In the latter case, it will be ignored. | | Suppose we assign an onLoad( ) callback to a clip created with, say, attachMovie( ) or duplicateMovieClip( ): this.attachMovie("BallSymbol", "theBall_mc", 1); // THIS WILL NEVER EXECUTE: theBall_mc.onLoad = function () { trace("loaded"); }; When the first line runs, theBall_mc is attached to the current movie clip and the onLoad( ) phase passes. When the second line runs, a callback function is assigned to theBall_mc.onLoad, but it never executes because the clip is already loaded before the callback is assigned. Similarly, an attempt to assign onLoad( ) from frame 1 of a movie clip will fail: // THIS WILL NEVER EXECUTE: this.onLoad = function() { trace("loaded"); }; Unlike its Flash 5-style onClipEvent(load) cousin, the onLoad( ) event handler is not applied on a per-instance basis to movie clip instances. Instead, it is used at the class level to initialize the instances of a MovieClip subclass. The intended location of an onLoad( ) callback assignment is, therefore, in a movie clip subclass's #initclip block. For example: // CODE ON FRAME 1 OF THE MOVIE CLIP SYMBOL "ballSymbol" #initclip // Ball constructor function Ball () { // Initialize the ball instance here... } // Set the Ball superclass to MovieClip Ball.prototype = new MovieClip(); // Associate the Ball class with the Library symbol named "ballSymbol" Object.registerClass("ballSymbol", Ball); // Assign the onLoad handler to all instances Ball.prototype.onLoad = function () { trace(this._name + " loaded."); } #endinitclip For details on movie clip subclasses, see the #initclip pragma and Chapter 14. | Assigning onLoad( ) at the class level, as shown in the Ball code, admittedly works, but it is effectively a duplication of roles. Instance initialization code should normally be placed inside the class constructor function. | | Note that a clip's onLoad( ) callback is deleted when an external .swf or .jpg file is loaded into the clip, but its onClipEvent(load) handler is not deleted and will execute across multiple loadMovie( ) calls. (The onLoad( ) callback is deleted because an onLoad( ) event handler property is technically a function stored in a clip's property; clip properties are deleted when a clip is removed from the player.) Usage The Flash 5-style onClipEvent(load) handler executes when the contents of a clip are unloaded with the unloadMovie( ) function (because an empty placeholder clip is loaded into the clip when its contents are expelled). In contrast, on its own, an onLoad( ) callback function will not execute when a clip's contents are unloaded. However, strangely enough, when both types of handlers are applied to the same clip, both will execute when unloadMovie( ) runs. Example The following code uses the onClipEvent(load) form of onLoad( ) to generate an entire field of star clips using a single event handler in a cascading chain. The onClipEvent(load) handler is attached to a clip instance named star0. When the clip loads, it duplicates itself and its onClipEvent(load) handler, causing the duplicate, in turn, to duplicate itself. The process stops when the 100th clip is duplicated. Note that we cannot use the callback form of onLoad( ) to achieve the same effect because callbacks are not copied to duplicated movie clips. The .fla file for this example is available at the online Code Depot: // Attach this onLoad() handler to a clip named star0 onClipEvent (load) { // Place the current clip at a random position _x = Math.floor(Math.random() * 550); _y = Math.floor(Math.random() * 400); // Reset clip scale so we don't inherit previous clip's scale _xscale = 100; _yscale = 100; // Randomly size current clip between 50 and 150 percent randScale = Math.floor(Math.random() * 100) - 50; _xscale += randScale; _yscale += randScale; // If we're not at the 100th star, make another one if (_name != "star100") { nextStarNumber = Number(_name.substring(4, _name.length)) + 1; this.duplicateMovieClip("star" + nextStarNumber, nextStarNumber); } } | 
