Recipe 11.1. Performing Actions Repeatedly Over Time

Problem

You want to do some action or actions repeatedly over time.

Solution

Use a setInterval( ) action to tell Flash to invoke a function at an interval in milliseconds. Or, alternatively, you can use the onEnterFrame( ) method for a movie clip to have an action or group of actions execute at the frame rate of the movie.

Discussion

Admittedly the concept of performing actions repeatedly over time is not exclusive to movie clips, but it is something that you will use very often in conjunction with movie clips.

There are basically two ways to have Flash automatically perform an action or group of actions repeatedly. The first way we'll take a look at uses interval functions. An interval function is a function that Flash invokes at a frequency (in milliseconds) that you define. For example, you might want to set up a function that moves a movie clip to the right by six pixels, and then you can tell Flash to call that function every hundred milliseconds. The result would be that the movie clip would appear to animate to the right across the stage. Of course, the application of interval functions is not limited to moving a movie clip. But that should give you an idea of at least one way in which you can use this technique.

In order to set an interval for a function you should use the aptly named setInterval( ) global function. The setInterval( ) function takes at least two parameters: a reference to the function and the number of milliseconds between each function call. The setInterval( ) function also returns an interval ID that can later be used to stop the interval if you want. And obviously, in order to use setInterval( ), you will need to have first created the interval function itself. An interval function is nothing other than a regular function (named or anonymous) that gets called at the specified frequency. You don't have to do anything special or different with the function itself to get it to work as an interval function.

Even though you don't have to do anything beyond that of a regular function, if your interval function might run faster than the frame rate of the movie, and if the interval function updates some visual aspect (such as the location of a movie clip), you should place a call to the global function updateAfterEvent( ) as the last line in the function body. This function tells Flash to update the display even if it is between frames or enter frame events, which will ensure a smooth animation.

	// Define an interval function. Notice that this is just a regular, named function.
	function exampleIntervalFunction():Void {
	  trace("This is an interval function");
	}

	// Call setInterval( ). Pass it a reference to the interval function and a number
	// of milliseconds between each call. In this case, we're telling Flash to call
	// the interval function once every thousand milliseconds, or, in other terms, once
	// every second
	var nIntervalID:Number = setInterval(exampleIntervalFunction, 1000);

You also have the option of passing parameters to an interval function by appending those values to the parameters list of the setInterval( ) function.

	
	// Here we define an interval function that expects two parameters.
	function exampleIntervalFunction(sCharacter1:String, sCharacter2:String):Void {
	  trace("parameters: " + sCharacter1 + " ," + sCharacter2);
	}

	// Now, we define the interval, and tell Flash to pass the values "a" and "b" to
	// the interval function each time it is called.
	var nIntervalID:Number = setInterval(exampleIntervalFunction, 1000, "a", "b");

You'll notice, however, that the same values are always passed to the interval function. Even if you use variables in the setInterval( ) function, those variables are evaluated only once. Therefore, often the most useful situations in which to pass parameters to interval functions are those in which you use a single interval function for slightly different tasks. For example, you might want to write a single interval function that can move any movie clip in any direction. Then you can create multiple intervals that call the same function, but that tell Flash to move different movie clips in different directions.

	// First, we define the interval function. The function accepts a reference to a 
	// movie clip and the change in the x and y directions. It then moves the movie clip
	// appropriately.
	function moveMovieClip(mClip:MovieClip, nX:Number, nY:Number):Void {
	  mClip._x += nX;
	  mClip._y += nY;

	  // Add an updateAfterEvent( ) call here, as this function updates the position
	  // of a movie clip.
	  updateAfterEvent();
	}

	// Create an interval that calls moveMovieClip( ) every three hundred milliseconds 
	// in order to move a movie clip named mSquare one pixel at a time in the y 
	// direction. 
	var nMoveSquareIntervalID:Number = setInterval(moveMovieClip, 300, mSquare, 0, 1);

	// Set another interval at which the moveMovieClip( ) is called every five 
	// hundred milliseconds. But this time, instead of moving mSquare, we're moving 
	// mCircle one pixel at a time in the x direction. 
	var nMoveCircleIntervalID:Number = setInterval(moveMovieClip, 500, mCircle, 1, 0);

You can also tell Flash to stop calling the interval function using the clearInterval( ) global function. This function needs to know which interval to stop, so this is where the interval ID comes in handy. Because you've saved the ID to a variable at the time when you initially set the interval, you can pass that variable to the clearInterval( ) function:

	clearInterval(nIntervalID);

It is also possible to use object methods as interval functions. This procedure is not discussed in this book, but you can find more information on this subject in the ActionScript Cookbook (O'Reilly, 2003).

As an alternative to using interval functions, you can also use the built-in event handler method onEnterFrame( ). The former technique is preferred because it allows you more control over how often the actions are being called. The onEnterFrame( ) technique is dependent on the movie's frame rate. However, there are some cases in which you want some action or actions to occur at the frame rate of the movie. For example, Recipe 10.6 explained how to use an onEnterFrame( ) event handler method to play a movie clip's timeline in reverse. In that case, you want the playhead to move backward at the same rate at which it would normally move forward. You can, of course, use some simple mathematics to determine the correct frequency at which to call an interval function. But because the onEnterFrame( ) method is already called at that frequency, it is a good fit.

The onEnterFrame( ) method is what is called an event handler method. This means that when the enter frame event occurs in Flash, this method is automatically invoked. The enter frame event occurs at the frame rate of the movie. So if the frame rate is 12 frames per second, the enter frame event occurs 12 times per second, and, in turn, the onEnterFrame( ) method for any and all movie clips is invoked. The enter frame event is somewhat of a misnomer, because this event occurs regardless of whether the playhead is entering a frame. The event occurs at the frame rate if the movie is playing or stopped. Therefore, as long as the frame rate is high enough (the default of 12 frames per second is generally sufficient for most actions), you can use an onEnterFrame( ) method to have Flash perform actions repeatedly.

Even though Flash tries to call the onEnterFrame( ) method for all movie clips, the method is undefined until you define it. So normally, no actions necessarily take place when the enter frame event occurs. It is up to you to define this method for a movie clip. In order to do so, you need only to assign a function reference to the onEnterFrame( ) method for that movie clip. The function reference can be either to a named or anonymous function. The most common practice is to define the function inline as an anonymous function, as shown here:

	mClip.onEnterFrame = function ():Void {
	  trace("This gets called at the movie's frame rate.");
	};

You should notice that when you assign the function reference to the onEnterFrame( ) method, you do not include the function call operator (()) after onEnterFrame. This is very important. If you add the function call operator, it will not work.

	// This will not work. It is incorrect to add the function call operator after 
	// the name (exp 3pod.com) of the method to which you are assigning the function. 
	mClip.onEnterFrame() = function ():Void {
	  // …
	};