Recipe 1.7 Repeating a Task at Timed Intervals

1.7.1 Problem

You want to perform an action or actions at a specific timed interval.

1.7.2 Solution

Use the setInterval( ) function.

1.7.3 Discussion

The setInterval( ) function allows you to specify an interval (in milliseconds) at which your Flash movie will invoke a function. Use setInterval( ) to perform a particular action over time but not necessarily at the frequency of the frame rate of the movie.

// Define a function.
function myIntervalFunction (  ) {

  // Output the difference between the current timer value and its value from the
  // last time the function was called.
  trace(getTimer(  ) - lastTime);
  lastTime = getTimer(  );
}

// Set up an interval that attempts to invoke myIntervalFunction(  ) once every
// millisecond.
setInterval(myIntervalFunction, 1);

In the preceding example, even though the interval is theoretically one millisecond, in practice, its accuracy and granularity depend on computer playback performance in relation to other tasks being demanded of the processor. There are two implications to this:

• Don't rely on intervals to be extremely precise.

• Don't rely on intervals to be smaller than a few milliseconds.

The setInterval( ) function returns an identifier for the newly created interval. If you want to be able to stop the interval at a later time, you must store the return value, as follows:

// Set an interval such that someFunction(  ) is called approximately once per second.
// Assign setInterval(  )'s return value to the variable myIntervalID for later use.
myIntervalID = setInterval(someFunction, 1000);

You can use the clearInterval( ) function to stop an interval if you know the interval's identifier:

clearInterval(myIntervalID);

If you want the interval to invoke the method of an object instead of a standalone function, you can use the variation of the setInterval( ) function in which you pass it three parameters—a reference to the object, the name of the function (as a string), and the interval in milliseconds— instead of just two:

// Create a simple object using the Object constructor.
obj = new Object(  );

// Assign a method named myMethod to an object, obj.
obj.myMethod = function (  ) {
  trace("obj.myMethod(  ) has been called");
};

// Use setInterval(  ) to tell the movie to invoke the myMethod(  ) method of the obj
// object approximately every six seconds.
setInterval(obj, "myMethod", 6000);

Whichever variation of the setInterval( ) function you use, any additional parameters that you pass to the setInterval( ) function are passed along to the function or method:

// Define a function that accepts a parameter and displays it in the Output window.
function displayValue (val) {
  trace(val);
}

// Use setInterval(  ) to call displayValue(  ) once per minute. The third parameter is 
// passed to the function when it is called so that each time "Bunny rabbits go 
// hippity-hop" is displayed in the Output window.
setInterval(displayValue, 60000, "Bunny rabbits go hippity-hop");

Be aware that any values that you pass to a function or method by way of the setInterval( ) function are evaluated only at the time the interval is initialized. So the same parameter values are always passed to a function or method that is called via setInterval( ):

obj = new Object(  );

obj.traceAnimalName = function (name) {
  trace(name);
};

myAnimalName = "cub";

setInterval(obj, "traceAnimalName", 30, myAnimalName);

// Even if myAnimalName is assigned a new value, the value "cub" is always passed to
// traceAnimalName(  ), because myAnimalName was "cub" when setInterval(  ) was first
// called.
myAnimalName = "puppy";

One of the neat things you can do with setInterval( ) is create animations that are independent of the movie's frame rate. Remember that the onEnterFrame( ) method executes at the same interval as the frame rate, so using that technique ties you to the movie's properties. But with setInterval( ) you can call a function or method at any interval you want. Here is an example in which two intervals are set—one for a square movie clip (every 50 milliseconds) and one for a circle movie clip (every 100 milliseconds):

// Define the function first. This function takes three parameters: a reference to 
// the movie clip object, the change in x, and the change in y.
function moveObj (obj, dx, dy) {

  // Increment the movie clip's x and y coordinates.
  obj._x += dx;
  obj._y += dy;

  // In case the interval is less than the movie's frame rate, you need to use the 
  // built-in updateAfterEvent(  ) method to refresh the Stage.
  updateAfterEvent(  );
}

// Create two intervals. Each invokes the moveObj(  ) function, but at different 
// intervals and with different movie clip references as parameters.
squareInterval = setInterval(moveObj, 50,  square, 1, 1);
circleInterval = setInterval(moveObj, 100, circle, 1, 1);