13.7 Method Versus Global Function Overlap Issues

	ActionScript for Flash MX: The Definitive Guide, 2nd Edition By Colin Moock
	Chapter 13.  Movie Clips

As we've mentioned several times during this chapter, some movie clip methods have the same name as equivalent global functions. You can see this for yourself in the Flash authoring tool. Open the Actions panel, make sure you're in Expert Mode, and then take a look in the Actions folder under Movie Control and Movie Clip Control. You'll see a list of Actions, including gotoAndPlay( ), gotoAndStop( ), nextFrame( ), and unloadMovie( ). These Actions are also available as movie clip methods. The duplication is not purely a matter of categorization; the Actions are global functions, fully distinct from the corresponding movie clip methods.

So, when we execute:

theClip.gotoAndPlay(5);

we're accessing the movie clip method named gotoAndPlay( ). But when we execute:

gotoAndPlay(5);

we're accessing the global function called gotoAndPlay( ). These two commands have the same name, but they are not the same thing. The gotoAndPlay( ) global function operates on the current instance or movie. The gotoAndPlay( ) method operates on the clip object through which it is invoked. Most of the time, this subtle difference is of no consequence. But for some overlapping method/function pairs, this difference is potentially quite vexing.

Some global functions require a target parameter that specifies the clip on which the function should operate. This target parameter is not required by the comparable clip methods because the methods automatically operate on the clips through which they are invoked. For example, in its method form, unloadMovie( ) works like this:

theClip.unloadMovie();

As a method, unloadMovie( ) is invoked without parameters, and it automatically affects theClip. But in its global function form, unloadMovie( ) works like this:

unloadMovie(target);

The global function version of unloadMovie( ) requires target as a parameter that specifies which movie to unload. Why should this be a problem? Well, the first reason is that we may mistakenly expect to be able to unload the current document by using the global version of unloadMovie( ) without any parameters, as we'd use gotoAndPlay( ) without parameters:

unloadMovie();

This format does not unload the current clip. It causes a "Wrong number of parameters" error. The second reason that target parameters in global functions can cause problems is a little more complex and can be quite a pain to track down if you're not expecting it. To supply a target clip to a global function that requires a target parameter, we can use either a string, which expresses the path to the clip we wish to affect, or a clip reference. For example:

unloadMovie(_level1);    // Target clip is a reference unloadMovie("_level1");  // Target clip is a string

We can use a reference simply because references to clip objects are converted to movie clip paths when used in a string context. This is simple enough, but if the target parameter resolves to an empty string or an undefined value, the function operates on the current timeline!

These examples demonstrate how an incorrect target clip reference can unintentionally unload the current timeline:

unloadMovie(x);   // If x doesn't exist, x yields undefined, so                   // the function operates on the current timeline unloadMovie("");  // The target is the empty string, so the function operates                   // on the current timeline

This can cause some quite unexpected results. Consider what happens if we refer to a level that doesn't exist:

unloadMovie(_level1);

If _level1 is empty, the interpreter resolves the reference as though it were an undeclared variable. This yields undefined, so the function operates on the current timeline, not _level1! So, how do we accommodate this behavior? There are a few options. We can check for the existence of our target before executing a function on it:

if (_level1) {   unloadMovie(_level1); }

Or, we can choose to always use a string to indicate the path to our target. If the path specified in our string does not resolve to a real clip, the function fails silently:

unloadMovie("_level1");

In some cases, we can use the equivalent numeric function for our operation:

unloadMovieNum(1);

Finally, we can choose to avoid the issue altogether by always using clip methods:

_level1.unloadMovie();

For reference, here are the troublemakers (the ActionScript global functions that take target parameters):

duplicateMovieClip( )

loadMovie( )

loadVariables( )

print( )

printAsBitmap( )

removeMovieClip( )

startDrag( )

unloadMovie( )

If you're experiencing unexplained problems in a movie, you may want to check this list to see if you're misusing a global function. When passing a clip reference as a target parameter, be sure to double-check your syntax.