13.8.3.1. Method versus global function overlap issues

So, when we execute:

myClip.gotoAndPlay(5);

we're accessing the 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, the subtle difference is of no consequence. But for some overlapping method/function pairs, the difference is potentially quite vexing.

myClip.unloadMovie( );

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

unloadMovie(target);

The global function 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 may 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 may use a reference simply because references to clip objects are converted to movie clip paths when used in a string context. Simple enough, but if the target parameter resolves to an empty string or an undefined value, the function operates on the current timeline ! For example:

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 may check for the existence of our target before executing a function on it:

if (_level1) {
  unloadMovie(_level1);
}

We may 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 may use the equivalent numeric function for our operation:

unloadMovieNum(1);

Or, we may choose to avoid the issue altogether by always using methods:

_level1.unloadMovie( );

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