Recipe 10.4. Skipping the Playhead to a Different Frame of the Timeline

Problem

You want to skip the playhead ahead or back within a timeline.

Solution

Use the MovieClip.gotoAndPlay( ) or MovieClip.gotoAndStop( ) method. Optionally, if you want to specify a scene to which you want to have the playhead move, you may use the gotoAndPlay( ) or gotoAndStop( ) global function.

If you want to simply move the playhead to the next frame or the previous frame, use the MovieClip.nextFrame( ) or MovieClip.prevFrame( ) method.

Discussion

Flash has several ways by which you can instruct the playhead to move to a specific frame in a timeline. Some of the ways tell the playhead to go to a frame and then keep playing from there. Others tell the playhead to go to a frame and then stop. That is logical enough. But what may not be obvious is the reasoning for two sets of each. You can use either the methods of the MovieClip class or the global functions of the same name. Typically, the methods of the MovieClip class are preferable, because they allow more flexibility in most ways than the global function counterparts. The global functions remain in Flash, because the MovieClip class methods were not introduced until Flash 5. That means that for Flash to continue to support Flash 4 content, it must support the global functions.

Both the gotoAndPlay( ) and gotoAndStop( ) methods of the MovieClip class skip the playhead to a specific frame of the timeline. As their names suggest, gotoAndPlay( ) skips the playhead to the specified frame and begins playback from that point, and gotoAndStop( ) skips the playhead to the specified frame and pauses playback. Both functions require that you pass a parameter indicating the frame to which you want the playhead to move. You can indicate the frame either as a number or as a quoted string value indicating the frame label.

Which timeline is affected is determined by which movie clip you use to call the method. To call the method, first reference the movie clip. Follow the movie clip reference with a dot (.), and then the name of the method. There should be no spaces between the movie clip reference, the dot, or the name of the method. The following example instructs the timeline of a movie clip instance named mAnimation to go to the tenth frame and stop:

 mAnimation.gotoAndStop(10); 

If mAnimation happens to have a frame label of AnimationStart at the tenth frame, you could accomplish the same thing as the preceding example with the following code:

 mAnimation.gotoAndStop("AnimationStart"); 

The benefit of using frame labels is that even if the frame number changes, your code will still work. For example, if you later added a few frames to the beginning of the mAnimation instance's timeline, what was previously at frame 10 would move to a later frame. If you referenced the frame by number in your code, you'd also need to change the code for your Flash movie to work correctly. On the other hand, if you use a frame label, as long as the frame label moves to the appropriate frame within the timeline, your code will still work.

If you want to add some code to the main timeline that sends instructions to the main timeline itself, you need to know how a timeline can refer back to itself. As you saw in the previous examples, you need to use a movie clip reference in order to call the gotoAndStop( ) or gotoAndPlay( ) method. But unlike other movie clip instances that you place on stage, you cannot add an instance name to the main timeline. Instead, you can use a special ActionScript keyword called this. The this keyword allows an object (such as the main timeline) to refer to itself without having to know its own name. The following code is an example of how you can instruct the main timeline to go to frame 40:

 this.gotoAndPlay(40); 

Often, Flash developers want to use the timeline playback methods such as gotoAndStop( ) or gotoAndPlay( ) to allow the user to control the playback of a timeline. For example, you may want to allow a user to jump to different sections of an animation. Or you may want to allow the user to rewind and play an animation again. In the majority of scenarios, you want to target one timeline from another timeline or object. For example, you may want to add buttons that allow the user to jump to different sections of the timeline. Therefore, you will want to place the gotoAndStop( ) and/or gotoAndPlay( ) method calls within button event handler methods such as onPress( ) or onRelease( ). When you do that, you have to be aware of an issue called targeting or addressing. You need to make sure that you provide Flash with the correct way to locate the timeline you want to control, or it won't be able to do as you have asked. This is similar to sending a postal letter: if you send it to the wrong address, it doesn't matter what's in the letter. So you need to make sure you provide the correct address so that Flash can find the correct timeline. Addressing issues are discussed in more detail in Recipe 11.11.

If you want to move the playhead to the next frame or previous frame of a timeline, you can use the nextFrame( ) and prevFrame( ) methods, respectively. Both of the methods move the playhead to a frame and then stop the playback at that point. They are particularly useful methods when you are creating something like a slide-show presentation in which the user gets to move the playhead back and forth through the timeline one frame at a time. The methods don't require any parameters, and you should call them using the same type of dot-syntax as is used with the gotoAndStop( ) and gotoAndPlay( ) methods. For example:

 mAnimation.nextFrame(); 

If you want to jump back and forth by more than one frame at a time, you can use the _currentframe property as part of an expression. The _currentframe property returns the number of the frame through which the playhead is currently moving. You can add or subtract from that value to get the number of a frame that is a specific distance before or after the current frame. For example, if you want to tell Flash to move the playhead within mAnimation 10 frames forward, use the following code:

 mAnimation.gotoAndStop(mAnimation._currentframe + 10); 

Notice that the _currentframe property is referenced using dot-syntaxjust as when calling one of the methods of a movie clip. The property returns the current frame for the movie clip from which it is called.

Using _currentframe as part of an expression to skip ahead or backward by more than a single frame can create the need for something called bounds checking. Bounds checking refers to a script that tests whether the specified frame target is within the bounds of the timeline; for example, if the playhead is on frame 12 and a gotoAndStop( ) method sends it back 20 frames, the action would attempt to send the playhead out of the bounds of the movie.

Bounds checking is not absolutely necessary in the sense that leaving out bounds checking will not cause an error: Flash ignores any script that attempts to send the playhead to a frame before frame 1 or after the last frame in the timeline. That is, if the script is on frame 12 and a script attempts to send it back 20 frames, the playhead will remain on frame 12. In the opposite case, where a script attempts to send the playhead beyond the last frame, Flash advances the playhead to the last frame. Thus, if the playhead is on frame 92 of a 100 frame movie, and a script attempts to advance the playhead 20 frames, Flash will move it to frame 100. Therefore, bounds checking is needed to achieve certain behaviors. You would need it, for example, if you wanted the button that skips backward to behave the same way as a button that skips forward. That is, if you wanted a button either to rewind by 20 frames, or to rewind to the first frame when the playhead is on a frame lower than 20, you would incorporate bounds checking into the script:

 btSkipBackward.onPress = function():Void {   var nFrame:Number = mAnimation._currentframe20;   if(nFrame < 1) {     mAnimation.gotoAndStop(1);   }   else {     mAnimation.gotoAndStop(nFrame);   } }; 

As mentioned previously, Flash continues to support the gotoAndPlay( ) and gotoAndStop( ) global functions. The global functions are very similar to the MovieClip methods already described. However, they affect only the timeline from which they are called. That makes them less useful as you start to create more complex animations and applications with Flash.

One reason that many people still use the global functions instead of the recommended methods is that both the gotoAndPlay( ) and gotoAndStop( ) global functions allow you to specify a scene to which you want to have the timeline jump. With either of the functions, you can specify up to two parameters. If you only specify one parameter, it should be the number or label of the frame to which you want the timeline to move. For example:

 gotoAndPlay(1); 

If you specify two parameters, the first should be the name of the scene to which you want the playhead to move. The second parameter should be either the number or label of the frame. For example:

 gotoAndPlay("Scene Two", 1); 

You may use the scene label parameter only with the gotoAndStop( ) and gotoAndPlay( ) methods when targeting the main timeline.

Although the global functions may, at first, appear to have a distinct advantage when you are using scenes, the recommended approach is to continue to use the MovieClip class methods with frame labels. Simply add a frame label to the first frame of each of your scenes. For example, you can add a frame label of Scene_Two to a scene in your document. Then, from the main timeline, the following code will cause the playhead to jump to the first frame of the scene.

 this.gotoAndStop("Scene_Two"); 

See Also

Recipe 9.2, Recipe 9.8