Recipe 7.3 Affecting Playback

7.3.1 Problem

You want to control the playhead of a movie clip's timeline.

7.3.2 Solution

Use the global functions and movie clip methods that control the playhead.

7.3.3 Discussion

You can use the timeline-affecting methods, shown in Table 7-1, to control the playback of a movie clip. These methods are most meaningful for movie clips that have more than one frame in their timelines. Therefore, movie clips created using the createEmptyMovieClip( ) method cannot be usefully affected by the timeline-affecting methods because they have only one frame, and there is no way to programmatically add more frames.

There are many potential uses for each of these methods. You should use them to meet the needs of your movie. Here are some tips for how you might use each method.

You can use the play( ) method to play the timeline of an animation when the user rolls over the movie clip:

myMovieClip.onRollOver = function (  )  {
  this.play(  );
};

You can also use play( ) to play the timeline of a movie clip once a callback method, such as the onLoad( ) method of a LoadVars object, has been invoked. This can be useful for situations in which you want to ensure that data has been loaded into the movie before allowing the user to see a particular part of it. It is also useful when the movie clip depends on loaded data to work properly.

// lv is a LoadVars object.
lv.onLoad = function (  )  {
  // Process the loaded data.

  // Call the play(  ) method of a movie clip on _root.
  _root.myMovieClip.play(  );
};

You can use the stop( ) method to stop the playback of a movie clip at the outset. This is useful if you want to prevent playback until certain conditions are met, such as when the user rolls over the movie clip or when data loads into the movie, etc. Movie clips always play by default, so you have to explicitly tell them to stop:

myMovieClip.stop(  );

By default, movie clip timelines continue to loop (playback begins again at the first frame after the playhead reaches the last frame). If you want a timeline to play only once, you should use the stop( ) method on the last frame of the movie clip's timeline:

this.stop(  );

You can use the gotoAndPlay( ) method to play a particular section of a timeline when a user performs an action, such as clicking on a navigational button. Generally, it is not the best practice to create multiple sections of a timeline. Rather, each timeline should be a distinct unit. However, you may have good reason in some cases to have a single timeline in which many parts of an animation take place, and in these cases gotoAndPlay( ) is a useful method. (That said, ActionScript doesn't mesh well with scenes, so Flash scenes should generally be avoided in ActionScript-heavy movies.) Here are two examples:

// When the user clicks and releases myButtonMovieClip 
// (presumed to be a navigational button in your movie), 
// tell the main timeline (_root) to begin playback from frame 33.
myButtonMovieClip.onRelease = function (  ) {
  _root.gotoAndPlay(33);
};

// This example is the same as the previous one, except it uses the frame label 
// "section b" instead of a frame number. You can apply frame labels by selecting the
// frame and entering a value into the Frame field of the Property inspector.
myButtonMovieClip.onRelease = function (  ) {
  _root.gotoAndPlay("section b");
};

You can use the gotoAndStop( ) method to go to a single frame of a timeline when a user performs an action, such as rolling out of a movie clip. Recipe 7.5 discusses how movie clips used as buttons automatically have a gotoAndStop( ) method applied for the _up, _over, and _down labels within the movie clip, if they exist. You could make a more interesting movie clip button by also adding _rollout and other such labels to the timeline and using gotoAndStop( ) within the appropriate event handler methods:

myButtonMovieClip.onRollOut = function (  ) {
  this.gotoAndStop("_rollout");
};

You can use the nextFrame( ) and prevFrame( ) methods to navigate back and forth along a movie clip's timeline, such as in a slide presentation:

// This code allows a user to move back and forth along the frames of the main 
// timeline. prevBtn and nextBtn are buttons or movie clips that act as buttons.
prevBtn.onRelease = function (  ) {
  _root.prevFrame(  );
};

nextBtn.onRelease = function (  ) {
  _root.nextFrame(  );
};

You can also use the _currentframe property in conjunction with gotoAndStop( ) or gotoAndPlay( ) to instruct the playhead to move to a frame on the timeline relative to the current frame:

forwardFiveBtn.onRelease = function (  ) {
  _root.gotoAndStop(_currentframe + 5);
};