MovieClip.onUnload( ) Event Handler

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock
	Chapter 18.  ActionScript Language Reference

MovieClip.onUnload( ) Event Handler

Flash 6

---

callback invoked when the clip is removed from the Stage or when unloadMovie( ) executesFlash 5; callback form introduced in

mc.onUnload()     onClipEvent (unload) {   statements }

Description

The onUnload( ) event handler is the callback form (and more modern analogue) of the legacy onClipEvent (unload) event handler. The onUnload( ) event is the opposite of the onLoad( ) event; it occurs when mc expires?that is, it occurs immediately after the last frame in which mc is present on stage (but before the first frame in which it is absent). The onUnload( ) event does not apply to main movies (e.g., _root, _level1, etc.)

The following incidents trigger onUnload( ):

• The playhead reaches the end of the span of frames upon which mc resides.

• mc is removed via the removeMovieClip( ) function (which deletes clips generated by the attachMovie( ) and duplicateMovieClip( ) functions).

• The unloadMovie( ) function is invoked on mc.

• mc has an external .swf file loaded into it.

This last onUnload( ) event trigger may seem a little odd, but it is actually a natural result of the way movies are loaded into Flash. Anytime a .swf or .jpg file is loaded into a movie clip, the previous contents of that clip are displaced, triggering an onUnload( ) event. Here's an example that illustrates the behavior of the onLoad( ) and onUnload( ) events in connection with loadMovie( ):

1. In the Flash authoring tool, we place an empty movie clip on stage at frame 1 of a movie's main timeline. We name our clip emptyClip.

2. At frame 5 of the main timeline, we load the movie test.swf into emptyClip using the following code:

   emptyClip.loadMovie("test.swf");

3. We play the movie using Control Play movie.

The results are:

1. The emptyClip clip appears on frame 1, causing an onLoad( ) event.

2. On frame 5, the loadMovie( ) function is executed in two stages:

   1. The placeholder content of emptyClip is removed to make room for the incoming test.swf, causing an onUnload( ) event.

   2. The movie test.swf loads, causing an onLoad( ) event.

The onUnload( ) event typically is used to perform housecleaning code?code that cleans up the Stage or resets the program environment in some way. An onUnload( ) handler also provides a means for performing some action (such as playing another movie) after a movie clip ends.

Unlike its cousin onLoad( ), whose callback form has limited use, onUnload( ) works identically whether defined as a callback or in an onClipEvent(unLoad) block. However, the usual differences between callback handlers and onClipEvent( ) handlers still apply:

• When the contents of mc are unloaded, the onUnload( ) callback is lost, but the onClipEvent(unload) handler is retained.

• When mc is duplicated via duplicateMovieClip( ), the onUnload( ) callback is not copied to the duplicate clip, but the onClipEvent(unLoad) handler is.

Usage

Perhaps surprisingly, in Flash 6, onUnload( ) is not triggered when the Flash Player is closed or when _level0 (the main movie) is removed from the Player. Macromedia may address this idiosyncrasy in the future.

See Also

MovieClip.onLoad( ), MovieClip.unloadMovie( )