Controlling Movie Playback

To take full advantage of button functionality, we need to discuss one last topic: control of the movie's playhead. As you might recall, a playhead exists for each timeline in your movie. If a timeline has only one frame, it plays that one frame and then stops. However, if there is more than one frame in a timeline, the playhead plays each frame in order, and after playing them all, it jumps back to frame 1 and continues to play.

That's all well and good, but sometimes we will want to stop and start timelines , cause the playhead to jump from one frame to another frame far down the timeline, or even play in reverse. ActionScript gives us the ability to control playback any way we like with a set of simple functions.

Caution  

All the playback functions affect the timelines of movies and movie clips. They do not affect events or the way in which event handlers are called. For example, a movie clip on the stage will still have onEnterFrame events regardless of whether it's stopped or playing.

The stop Function

If a movie is currently playing and you want it to stop, you can call the stop function. The stop function causes the playhead to freeze at its current frame until it's told to move again. The general form of stop is as follows :

 void  myMovieClip  .stop(); 

As you can see, stop is called on a reference to the clip whose timeline you want to stop. It returns nothing and takes no arguments. You can, of course, call this function in a given frame or event handler, and it will refer to the currently scoped timeline, as with any function that is called on a clip. You've already seen stop used in this way in our previous button example. Remember that we added a call to stop on each frame of the button? That was to keep it from cycling through each of the button states. Let's see an example of it being used with a clip reference.

Create a new movie, create a new symbol called anime , and export it in the linkage properties. Now edit the clip and in the first frame, draw a square. Add blank keyframes to the second and third frames , and draw a circle and a triangle in them, respectively. You should now have a three-frame movie that has a square in the first frame, a circle in the second, and a triangle in the third. Add a new layer called labels and add blank keyframes in the first three frames. Label each frame with the name of the shape contained in it. So the first frame should be named square , the second circle , and the third triangle . Now add the following script to the main timeline:

 attachMovie("anime"," anime", 1); anime._x += 50; anime._y += 50; 

Test your movie, and you should see the shape changing rapidly . Now add the following line to your main timeline script, at the end:

 anime.stop(); 

If you test now, you'll see that the clip is no longer cycling through its frames and changing shape because we issued a stop function on it.

When the playhead is ordered to stop , the current frame is displayed and any script attached to that frame is executed. The playhead freezes after those two things happen.

If you haven't noticed yet, when you create a new symbol and the Create New Symbol dialog box opens, there is a button labeled Advanced. Click it, and you'll see more properties listed. One set is the linkage properties where you can export the symbol. By keeping this Advanced panel open , you can tell Flash to export a symbol at the same time you are creating the symbol, saving you the time of exporting it later and the hassle of forgetting to export it. Figure 4.15 shows the fully expanded dialog box.

Figure 4.15: In the Create New Symbol dialog box, you can open the Advanced panel and set your linkage properties during creation.

The play Function

If a playhead has been stopped, you can start it playing again by issuing the play function. The general form of this is as follows:

 void  myMovieClip  .play(); 

As you can see, this function is also called on a clip, returns nothing, and takes no arguments. Using the same script from the previous example, add the following line to the end:

 anime.onPress = function(){     this.stop(); } anime.onRelease = function(){     this.play(); } 

Now test the script and click on the anime clip. Notice that we didn't have to label frames with _up , _down , or _over to get the onPress event working. So when you click and hold the button, the clip stops cycling. But when you release the button, it begins cycling again. Of course, the clip is stopped initially because of the script we added in the previous example, but because the main timeline is only one frame long, it does not cycle, and that script only stops the clip once. After you start clicking on the instance, it behaves as its onPress and onRelease handlers dictate .

The gotoAndPlay Function

This function is similar to the play function, except that it also specifies a frame for the playhead to move to before playing. The general form is as follows:

 void  myMovieClip  .gotoAndPlay(  frame  ); 

In this case, the function returns nothing, is called on the movie clip to be played , and requires one argument. The argument, frame , is either a literal string or a variable string indicating the frame label to go to. It can also be a literal or variable number indicating the frame number to go to. Either is acceptable to Flash.

Caution  

Although Flash will let you put a number in the gotoAndPlay function, it's a terrible idea. If you later edit your symbol and insert a frame, the numbering system for your frames will change and your script will not work right, which means you'll have to go in and edit script. By using labels exclusively in your gotoAndPlay calls, you can insert frames into a timeline without editing the associated script. For that reason, I almost always use frame labels when working with movie playback. The exception is when I want to go to a specific frame regardless of the actual timeline events that occur there (frame 1, for example).

The gotoAndStop Function

This function, gotoAndStop , causes the playhead to move to a given frame and then freeze. Any script in said frame will execute, the frame will be displayed, and the playhead will stop until further notice. The general form is as follows:

 void  myMovieClip  .gotoAndStop(  frame  ); 

As before, this function returns nothing, is called on the movie clip to stop, and requires one argument. This single argument, frame , indicates either the frame label or frame number that the playhead should go to before freezing. Note that any script attached to that frame will be executed; the playhead just won't move on to the next frame when it's done.

Caution  

Just like gotoAndPlay , the gotoAndStop function can take either a string or a number as its argument. Giving it a number is a terrible idea and you should rarely, if ever, do it. Instead, use labels so that you can edit your symbol and timeline without editing your script.

The nextFrame Function

This function is used to advance the playhead of a timeline by one frame. If the playhead is in the last frame of a movie, nextFrame will do nothing. The general form is as follows:

 void  myMovieClip  .nextFrame(); 

As you can see, the function has no return value, no arguments, and is called upon the movie clip to advance. This function has the additional affect of stopping the movie as if stop were called on it. In that sense, it's like the playhead is told to play only the next frame and then stop. Let's look at this one in action.

Remove all the script from your main timeline and add the following code in its place:

 attachMovie("anime"," anime",1); anime._x += 50; anime._y += 50; anime.stop(); anime.onPress = function(){     this.nextFrame(); } 

Test this code and notice that you can only click on the anime instance twice to advance it. After that, it's in the last frame, and a nextFrame call will do nothing.

The prevFrame Function

The prevFrame function moves the playhead one frame backward. Like nextFrame , the clip will stop playing when prevFrame is called on it. When called, the new frame (the previous one) is displayed, and any script attached to it is executed. So in that sense, using the prevFrame function is like telling Flash to play the previous frame and then stop. If the playhead is over frame 1, the prevFrame call does nothing. The general form follows:

 void  myMovieClip  .prevFrame(); 

prevFrame takes no arguments, has no return value, and is called on the clip whose playhead you want moved. It's time for an example.

Remove the script from your main timeline and replace it with the following:

 attachMovie("anime"," anime",1); anime._x += 50; anime._y += 50; anime.gotoAndStop("triangle"); anime.onPress = function(){     this.prevFrame(); } 

In this example, the anime clip is given a gotoAndStop call with the triangle frame label as the argument. Because triangle is the label of the previous frame, this call first moves the playhead to the last frame (frame 3) and then stops it. Then each time the button is pressed, a call to prevFrame is invoked. This in turn causes the clip to step backward one frame, essentially playing the timeline in reverse. Notice that after two presses, the playhead is in the first frame; further clicking does nothing.

Caution  

I've said this before, but it's worth repeating. All the playback functions affect the timelines of movies and movie clips. They do not affect events or the way in which event handlers are called. For example, a movie clip on the stage will still have onEnterFrame events regardless of whether it's stopped or playing.

The _currentframe Property

An important property that goes along with the movie playback functions is _currentframe . This movie clip property cannot be changed (read-only) and represents the frame number that a movie clip's playhead is currently on. Beware, however; you cannot use labels with the _currentframe property ”only numbers . That's inconvenient, but that's the way life is sometimes.

Let's have an example of this property's use. Remove your main script and replace it with the following:

 attachMovie("anime"," anime",1); anime._x += 50; anime._y += 50; anime.gotoAndStop("triangle"); anime.onPress = function(){     if(this._currentframe == 1)         this.gotoAndStop("triangle");     else         this.prevFrame(); } 

In this new script, we have a new and improved onPress function that first tests to see whether the movie is already at frame 1. If it is, we call gotoAndStop with the last frame's label (triangle), which resets the movie playhead to the last frame. If the playhead is anywhere other than the first frame, the onPress function calls prevFrame , which backs the movie up one frame.

Notice that we did not use if(this._ currentframe == "square") because _currentframe cannot be used with labels ”only numbers.

Caution  

Notice that the f in _currentframe is not capitalized. This is an unfortunate inconsistency in Flash, and it's certainly not the only one.

The _totalframes Property

The _totalframes property represents the total number of frames in a particular movie's timeline. This is an easy way to find out if you are in the last frame of a movie, as in the following example.

Remove your script one final time and replace it with the following:

 attachMovie("anime"," anime",1); anime._x += 50; anime._y += 50; anime.stop(); anime.onPress = function(){     if(this._currentframe == this._totalframes)         this.gotoAndStop("square");     else         this.nextFrame(); } 

In this example, we're playing the movie forward, so in our onPress function, we're testing to see if the _currentframe is the same as the _totalframes . If it is, we know we're at the end of the movie, so we call gotoAndStop with the first frame label (square). If it's not, we advance one frame. This example is the same as the previous one except that this time we're playing the movie forward instead of backward.

Caution  

Notice that the f in _totalframes is not capitalized. Although this is the official way Flash uses the property, Flash still works with the capitalized version. Unfortunately, the capitalized version does not trigger the syntax coloring.