Book HomeActionScript: The Definitive GuideSearch this book

13.8. Movie Clip Methods

In Chapter 12, "Objects and Classes", we learned about a special type of property called a method, which is a function attached to an object. Methods are most commonly used to manipulate, interact with, or control the objects to which they are attached. To control movie clips in various programmatic ways, we may use one of the built-in movie clip methods. We may also define our own movie clip methods in an individual instance or in the Library symbol of a movie clip.

13.8.1. Creating Movie Clip Methods

To add a new method to a movie clip, we define a function on the clip's timeline (or in one of the clip's event handlers) or we assign a function to a property of the clip. For example:

// Create a method by defining a function on the timeline of a clip
function halfSpin( ) {
  _rotation += 180;
}
// Create a method by assigning a function literal to a property of a clip
myClip.coords = function( ) { return [_x, _ y]; };
// This method applies a custom transformation to a clip
myClip.myTransform = function ( ) {
  _rotation += 10;
  _xscale -= 25;
  _ yscale -= 25;
  _alpha -= 25;
}

13.8.2. Invoking Movie Clip Methods

Invoking a method on a movie clip works exactly like invoking a method on any object. We supply the name of the clip and the name of the method, as follows:

myClip.methodName( );

If the method requires arguments, we pass them along during invocation:

_root.square(5);   // Provide 5 as an argument to the square() method

As we learned earlier, when we're working on the timeline of a clip or in a clip's event handler, we may invoke most methods on the current clip directly, without specifying an instance identifier:

square(10);        // Invoke the custom square() method of the current clip
play( );            // Invoke the built-in play() method of the current clip

But some built-in methods require an instance identifier; see Section 13.8.3.1, "Method versus global function overlap issues".

13.8.3. Built-in Movie Clip Methods

Recall that the generic Object class equips all its member objects with the built-in methods toString( ) and valueOf( ). Recall similarly that other classes define built-in methods that can be used by their member objects: Date objects have a getHours( ) method, Color objects have setRGB( ), Array objects have push( ) and pop( ), and so on. Movie clips are no different. They come equipped with a series of built-in methods that we use to control movie clips' appearance and behavior, to check their characteristics, and even to create new movie clips. The movie clip methods are one of the central features of ActionScript. Table 13-2 gives an overview of the movie clip methods that are covered in depth in Part III, "Language Reference".

Table 13-2. The Built-in Movie Clip Methods

Method Name

Method Description

attachMovie( )

Creates a new instance

duplicateMovieClip( )

Creates a copy of an instance

getBounds( )

Describes the visual region occupied by the clip

getBytesLoaded( )

Returns the number of downloaded bytes of an instance or a movie

getBytesTotal( )

Returns the physical byte size of an instance or a movie

getURL( )

Loads an external document (usually an .html file) into the browser

globalToLocal( )

Converts main Stage coordinates to clip coordinates

gotoAndPlay( )

Moves the playhead to a new frame and plays the movie

gotoAndStop( )

Moves the playhead to a new frame and halts it there

hitTest( )

Indicates whether a point is within a clip

loadMovie( )

Brings an external .swf file into the Player

loadVariables( )

Brings external variables into a clip or movie

localToGlobal( )

Converts clip coordinates to main Stage coordinates

nextFrame( )

Moves the playhead ahead one frame

play( )

Plays the clip

prevFrame( )

Moves the playhead back one frame

removeMovieClip( )

Deletes a duplicated or attached instance

startDrag( )

Causes the instance or movie to physically follow the mouse pointer around the Stage

stop( )

Halts the playback of the instance or movie

stopDrag( )

Ends any drag operation currently in progress

swapDepths( )

Alters the layering of an instance in an instance stack

unloadMovie( )

Removes an instance or main movie from a document level or host clip

valueOf( )

A string representing the path to the instance in absolute terms, using dot notation

13.8.3.1. Method versus global function overlap issues

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. You'll see a long list of Actions including gotoAndPlay( ), gotoAndStop( ), nextFrame( ), and unloadMovie( ). Those 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:

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.

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

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):

duplicateMovieClip( )

loadMovie( )

loadVariables( )

print( )

printAsBitmap( )

removeMovieClip( )

startDrag( )

unloadMovie( )

If you're experiencing unexplained problems in a movie, you may want to check that 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.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.